さくらのクラウドでは、さくらのクラウドをコントロールパネルとは別に操作するためのAPIを提供しております。 APIを通して、サーバやディスクの作成や削除などができます。
さくらのクラウドのコントロールパネルからAPIキーを発行する必要があります。 APIキーの発行はコントロールパネルのAPIキー管理から行えます。
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ページをご確認ください。
2013-01-14T09:30:00+09:00
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" // 先頭にマイナスを付けると降順
]
}
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"// 作成日時がこの時刻より前(演算子は時刻・数値カラムのみ使用可)
// (これらをすべて満たすレコードが抽出されます)
}
通信量やクライアントのメモリを節約したい場合、取得情報を指定し除外できます。
GET /cloud/1.1/servers
{
Exclude: [ "Zone.Name", "Interfaces.*" ]
}
GET /cloud/1.1/servers
{
Include: [ "Name", "Status.*", "Zone.ID", "Region.*" ]
}
「リソースの設定」インタフェースを持つAPIが返すレスポンスは、以下のようなオブジェクト構造を持ちます。
{
"is_ok": 処理結果, /* boolean (true|false) */
"リソース名": リソース情報, /* object */
}
//原則として、API処理の実行結果はis_ok = true で、判定ができます。
{
"is_ok":true,
"Server": { /* 原則としてリソース名 */
"ID": xxxxxxxxxxxx, /* サーバID */
...
}
}
取得キーが指定(限定)できます。「リソースの検索」共通インタフェースのリクエストパラメータの取得キーを除外と取得キーの選択を参照してください。
「リソースの取得」インタフェースを持つ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,
...
}
「リソースの設定」インタフェースを持つAPIが返すレスポンスは、以下のようなオブジェクト構造を持ちます。
{
Success: 処理結果, /* boolean (true|false) */
}
原則として、API処理の実行結果はSuccess = true で判定ができます。
{
Success: true
}
共通仕様は特にありません。
「リソースの解放」インタフェースを持つAPIが返すレスポンスは、以下のようなオブジェクト構造を持ちます。
{
Success: 処理結果, /* boolean (true|false) */
is_ok: API 共通処理結果 /* boolean (true|false) */
}
原則として、API処理の実行結果はSuccess = true で、判定ができます。 認証やAPI の構文など、技術的な例外が発生したときは、 is_ok = false となります。
{
Success: true,
is_ok: true
}
共通仕様は特にありません。