さくらのクラウドAPI1.1

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

はじめに

ご利用方法

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

一般注記事項

API URL

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ゾーン)

APIはゾーン毎に存在します。第2ゾーンにサーバを作成する時は第2ゾーンの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
}

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

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