さくらのクラウドAPI1.1

さくらのクラウドでは、さくらのクラウドをコントロールパネルとは別に操作するためのAPIを提供しております。 APIを通して、サーバやディスクの作成や削除などができます。

はじめに

ご利用方法

さくらのクラウドのコントロールパネルからAPIキーを発行する必要があります。 APIキーの発行はコントロールパネルのAPIキー管理から行えます。

一般注記事項

API URL

https://secure.sakura.ad.jp/cloud/zone/tk1a/api/cloud/1.1/ (東京第1ゾーン)
https://secure.sakura.ad.jp/cloud/zone/tk1b/api/cloud/1.1/ (東京第2ゾーン)
https://secure.sakura.ad.jp/cloud/zone/is1a/api/cloud/1.1/ (石狩第1ゾーン)
https://secure.sakura.ad.jp/cloud/zone/is1b/api/cloud/1.1/ (石狩第2ゾーン)
https://secure.sakura.ad.jp/cloud/zone/tk1v/api/cloud/1.1/ (Sandbox)

APIはゾーン毎に存在します。第2ゾーンにサーバを作成する時は第2ゾーンのAPIにアクセスしなければなりません。
また、請求関連のAPIについてのみAPI URLが異なります。詳細は請求関連のAPIページをご確認ください。

認証

さくらのクラウドAPIはAPIキーとシークレットトークンを利用したBasic認証またはDigest認証を使用します。
APIキーとシークレットトークンは、コントロールパネルのAPIキー管理で発行または確認できます。

REST API

さくらのクラウドAPIはRESTベースです。

JSON

リクエストのパラメータとレスポンスのフォーマットにJSONを使用しています。

SSL Only

httpsでのアクセスのみ可能です。

UTF-8

文字コードはUTF-8を使用しています。

日付のフォーマット

DatetimeのフォーマットはISO 8601を使用しています。
以下のような出力になります。

2013-01-14T09:30:00+09:00

レスポンスフォーマットについて

リクエストヘッダーにX-Sakura-API-Beautify:1 をつけると整形化された読みやすいレスポンスボディを返します。curlコマンドの場合、オプションに -H 'X-Sakura-API-Beautify:1' を渡します。

注意事項

短期間に集中したアクセスはしないでください。
リソースを複数作成される場合は、個々のリソースの作成が完了してから次のリソースを作成するようにしてください。

APIレスポンス

APIは以下ので列挙されるHTTPレスポンスコードを返します。各APIでの具体的な意味合いはそれぞれの説明文中に記載しています。

各コードの意味

ステータスコード	内容
200 OK	正常に処理され、何らかのレスポンスが返却された。
201 Created	正常に処理され、何らかのリソースが作成された。例：仮想サーバを作成した
202 Accepted	正常に受け付けられたが、処理は完了していない。例：ディスクの複製を開始したが、まだ完了していない
204 No Content	正常に処理され、空のレスポンスが返却された。
305 Use Proxy	Locationフィールドに示されたプロクシ経由でのアクセスが必要。
400 Bad Request	リクエストパラメータが不正等。例：許可されないフィールドに対し、負の値、過去の日付、異なる型の値等が指定されている
401 Unauthorized	認証に失敗した。
403 Forbidden	リソースへのアクセス権限がない。例：/user/sakurai というリソースの上位にある /user にアクセスしたが、このリソースは一般ユーザにはアクセスできない。
404 Not Found	リソースが存在しない。例：taroというユーザはいないのに /user/taro というリソースにアクセスした。
405 Method Not Allowed	要求されたメソッドは非対応。例：/zone/5 というリソースにPUTメソッドは許可されていない。
406 Not Acceptable	何らかの事情でリクエストを受け入れられない。例：残りの空きリソースがない
408 Request Time-out	リクエストがタイムアウトした。
409 Conflict	リソースの現在の状態と矛盾する操作を行おうとした。例：仮想サーバの電源が既に入っているのに、電源を投入しようとした。
411 Length Required	リクエストヘッダーにLengthが含まれていない。curlコマンドの場合、curl -d ''で回避できる。
413 Request Entity Too Large	リクエストされた処理にかかる負荷が対応可能な範囲を越えた。例：アップロードファイルのサイズ制限を越えた
415 Unsupported Media Type	リクエストされたフォーマットに対応していない。例：画像データを返すリソースに対し、CSVフォーマットを要求した。
500 Internal Server Error	内部エラーが発生した。例：PHPエラーが発生した。
503 Service Unavailable	何らかの事情によりサービスが利用可能でない。例：DB接続に失敗した

「リソースの検索」共通インタフェース

レスポンスの共通仕様

「リソースの検索」インタフェースを持つAPIが返すレスポンスは、以下のようなオブジェクト構造を持ちます。

{
  Total: 検索条件にマッチする全レコード数: int,
  From: 取得された最初のレコードのオフセット: int,
  Count: 取得されたレコード数: int,
  リソース名: [
      リソース情報: object,
      リソース情報: object,
      ...
  ]
}

各リソース情報は、原則として0から始まる通し番号およびリソースIDを表すフィールドを持ちます。例えば GET /server を取得した結果、全300件中の101～150件目が返された場合は、以下のようなレスポンスになります。

{
  Total: 300,
  From: 100,                  /* 0から始まる通し番号 */
  Count: 50,
  Servers: [                  /* 原則としてリソース名の複数形 */
      {
          Index: 100,         /* 0から始まる通し番号 */
          ID: xxxxxxxxxxxx,   /* サーバID */
          ...
      },
      {
          Index: 101,
          ID: yyyyyyyyyyyy,
          ...
      },
      ...
      {
          Index: 150,
          ID: zzzzzzzzzzzz,
          ...
      }
  ]
}

リクエストパラメータの共通仕様

ページング

検索結果のリソース数が膨大になるとAPIの反応が遅くなるため、取得範囲を限定してページングすることを推奨します。例えば GET /server の101～150件目を取得する場合は、以下のようなパラメータを指定します。

GET /cloud/1.1/server
{
    From: 100,                  /* 0から始まる通し番号 */
    Count: 50
}

なお、大半のAPIリソースはLimitに一定の上限値が設けられており、省略時もその上限までのレコード数しか取得できません。上限値はリソースにより異なる場合があります。

ソート

ソートキーを文字列の配列で列挙することで、ソートすることができます。単一キーを指定する場合は、単一文字列で指定ができます。

GET /cloud/1.1/server
{
    Sort: [               // 優先順に通常配列で指定
        "Server.Name",    // 昇順
        "-Host.Zone.Name" // 先頭にマイナスを付けると降順
    ]
}

フィルタリング

文字列型カラムは中間一致、その他の型は完全一致のみ対応しています。
スカラ値を与えると部分一致のAND結合、配列を与えると完全一致のOR結合と見なされます。
大文字・小文字は区別されません。
複数の条件はAND結合されます。

リクエスト

GET /cloud/1.1/server
{
    Filter: {
        "Name": "test example", // Name に test と example を両方含みます
        "Zone.Name": [ "is1a", "is1b" ], // Zone.Name が is1a または is1b に完全一致
        "CreatedAt <": "2011-09-01T00:00:00+0900"// 作成日時がこの時刻より前（演算子は時刻・数値カラムのみ使用可） 
         // （これらをすべて満たすレコードが抽出されます）
}

取得キーを除外

通信量やクライアントのメモリを節約したい場合、取得情報を指定し除外できます。

不要なキーの配列をExcludeオプションに指定すると、マッチする要素がレスポンスから取り除かれます。
*（アスタリスク）を用いてワイルドカード指定することができます。

GET /cloud/1.1/servers
{
    Exclude: [ "Zone.Name", "Interfaces.*" ]
}

取得キーの選択

必要なキーの配列をIncludeオプションに指定すると、マッチする要素以外はレスポンスから取り除かれます。
*（アスタリスク）を用いてワイルドカード指定することができます。

GET /cloud/1.1/servers
{
    Include: [ "Name", "Status.*", "Zone.ID", "Region.*" ]
}

各オプション指定時の挙動

Excludeのみ指定時: Exclude指定されたものを除く、取得可能なすべてのキーを取得
Includeのみ指定時: Include指定されたキーのみ取得
Include, Excludeともに指定時: Includeのみ指定時の取得キーから、Exclude指定されたキーを除いて取得

リソース取得(GET)

レスポンスの共通仕様

「リソースの設定」インタフェースを持つAPIが返すレスポンスは、以下のようなオブジェクト構造を持ちます。

{
    "is_ok": 処理結果,         /* boolean (true|false) */
    "リソース名": リソース情報, /* object */
} 
//原則として、API処理の実行結果はis_ok = true で、判定ができます。
{
   "is_ok":true,
    "Server": {               /* 原則としてリソース名 */
        "ID": xxxxxxxxxxxx,   /* サーバID */
        ...
    }
}

リクエストパラメータの共通仕様

取得キーについて

取得キーが指定(限定)できます。「リソースの検索」共通インタフェースのリクエストパラメータの取得キーを除外と取得キーの選択を参照してください。

リソース登録(POST)

レスポンスの共通仕様

「リソースの取得」インタフェースを持つAPIが返すレスポンスは、以下のようなオブジェクト構造を持ちます。

{
    is_ok: 処理結果,         /* boolean (true|false) */
    ... 
}

原則として、API処理の実行結果はis_ok = true で判定ができます。

{
    is_ok: true,
    Token: "GLSzcpLRFnqmq0AqxxxDUpdIXhTzyZ1s"
    Account: {              /* 原則としてリソース名 */
        ID: xxxxxxxxxxxx,   /* Account ID */
        ...
    },
    CreatedAt: "2012-09-06T12:21:16+09:00",
    ExpiresAt: "2012-09-06T14:21:16+09:00"
}

リクエストパラメータの共通仕様

返却件数の指定

基本的に、リクエストパラメータは、個々のAPIに依存します。

返却件数の排除

Limit 件数でページングされることを防ぎます。

GET /cloud/1.1/public/account/123456789012/token
{
    From: 0,
    Count: 0,
    ...
}

リソース設定(PUT)

レスポンスの共通仕様

「リソースの設定」インタフェースを持つAPIが返すレスポンスは、以下のようなオブジェクト構造を持ちます。

{
    Success: 処理結果,         /* boolean (true|false) */
}

原則として、API処理の実行結果はSuccess = true で判定ができます。

{
    Success: true
}

リクエストパラメータの共通仕様

共通仕様は特にありません。

リソース解放(DELETE)

レスポンスの共通仕様

「リソースの解放」インタフェースを持つAPIが返すレスポンスは、以下のようなオブジェクト構造を持ちます。

{
    Success: 処理結果,         /* boolean (true|false) */
    is_ok:   API 共通処理結果 /* boolean (true|false) */
}

原則として、API処理の実行結果はSuccess = true で、判定ができます。認証やAPI の構文など、技術的な例外が発生したときは、 is_ok = false となります。

{
    Success: true,
    is_ok: true
}

リクエストパラメータの共通仕様

共通仕様は特にありません。