さくらのVPS APIドキュメント (1.12.0)

Download OpenAPI specification:Download

「さくらのVPS」が提供するAPIの利用方法とサンプルを公開しております。

「さくらのVPS」が提供するAPIはまだ一部の機能に制限しておりますが、順次機能を追加していく予定です。

基本的な使い方

APIキーの発行

APIを利用するためには、認証のための「APIキー」が必要です。
APIキーはVPSコントロールパネルから発行ができます。
このドキュメント内では発行したAPIキーの例としてSAMPLETOKENSAMPLETOKENSAMPLETOKと記載します。

操作マニュアル

APIキー | さくらのVPSマニュアル

APIへのリクエスト

APIのURLは https://secure.sakura.ad.jp/vps/api/v7/(エンドポイント) となります。

認証方式はHTTP Bearer認証です。HTTPリクエストヘッダにAuthorization: Bearer SAMPLETOKENSAMPLETOKENSAMPLETOKを指定します。

# リクエストのサンプル
curl -H 'Authorization: Bearer SAMPLETOKENSAMPLETOKENSAMPLETOK' \
   'https://secure.sakura.ad.jp/vps/api/v7/servers'

APIへのリクエスト結果

APIへのリクエストが成功したか失敗したかは、HTTPレスポンスのステータスコードで判断が可能です。

結果	ステータスコード
成功 (要求を受け付けた)	2xx
失敗（要求が受け付けられなかった）	4xx, 5xx

リクエストに成功すると、HTTPレスポンスのボディにはコンテンツ（データ）がJSON形式(UTF-8)で入っています。ただしコンテンツ（データ）を返さないリクエストの場合はボディは空です。

# コンテンツ（データ）のサンプル
{
  "id": 1,
  "name": "sample_data"
}

リクエストに失敗すると、HTTPレスポンスのボディには失敗した理由などがJSON形式(UTF-8)で入っています。

# 失敗した場合のボディのサンプル
{
  "code": "not_found",
  "message": "見つかりませんでした"
}

APIリクエスト回数の制限(Rate Limiting)

時間あたりに実行できるリクエスト回数に上限があります
- 基本はご利用の アカウントごとに100リクエスト/1分 まで
リクエスト回数の上限に達した場合、リクエストは処理されず HTTPステータスコードが429 となります
これらの制限は、今後のお客様の利用状況により予告なく変更する場合があります

サーバー

サーバー情報一覧を取得する

Authorizations:

ApiKeyAuth

query Parameters

page	integer
per_page	integer
switch	integer switchのid 対象のスイッチに接続されているサーバーに絞り込む
zone_code	string Enum: "tk1" "tk2" "tk3" "os1" "os2" "os3" "is1" ゾーンコードで絞り込む tk1 東京第1 tk2 東京第2 tk3 東京第3 os1 大阪第1 os2 大阪第2 os3 大阪第3 is1 石狩第1 例: 東京第1ゾーンのサーバーのみ取得: zone_code=tk1
service_type	string Enum: "linux" "windows" サービスタイプで絞り込む例: linuxのサーバーのみ取得: service_type=linux
ipv4_address	string Example: ipv4_address=192.0.2.0 IPアドレスで絞り込む
monitoring_resource_id	integer サーバー監視リソースIDで絞り込む
sort	string Enum: "service_code" "-service_code" "name" "-name" "storage_size_gibibytes" "-storage_size_gibibytes" "memory_mebibytes" "-memory_mebibytes" "cpu_cores" "-cpu_cores" "hostname" "-hostname" "ipv6_hostname" "-ipv6_hostname" "ipv4_address" "-ipv4_address" "ipv6_address" "-ipv6_address" "zone_code" "-zone_code" "ipv4_ptr" "-ipv4_ptr" "ipv6_ptr" "-ipv6_ptr" データの並び順。項目名の頭に`-`をつけると降順で取得する例: サービスコード昇順: sort=service_code サービスコード降順: sort=-service_code
search	string 名前、説明文、ホスト名、ipv4アドレス、ipv6アドレス、サービスコードから部分一致検索

Responses

Response samples

200
400
401
429

Content type

application/json

{"results": [{"id": 0,
"name": "string",
"description": "string",
"service_type": "linux",
"service_status": "on_trial",
"cpu_cores": 2,
"memory_mebibytes": 1024,
"storage": [{"port": 0,
"type": "ssd",
"size_gibibytes": 100
}
],
"zone": {"code": "tk1",
"name": "石狩第1"
},
"options": ["SQL Server Web Edition"
],
"version": "v5",
"ipv4": {"address": "198.51.100.2",
"netmask": "255.255.254.0",
"gateway": "198.51.100.1",
"nameservers": ["203.0.113.1"
],
"hostname": "example.jp",
"ptr": "example.jp"
},
"ipv6": {"address": "2001:e42:102:1501:153:121:89:107",
"prefixlen": 64,
"gateway": "fe80::1",
"nameservers": ["2001:e42::1"
],
"hostname": "example.jp",
"ptr": "example.jp"
},
"contract": {"plan_code": 3439,
"plan_name": "さくらのVPS(v5)  1G IK01",
"service_code": "100000000000"
},
"power_status": "power_on"
}
],
"count": 100,
"next": "https://api.example.com/?page=3&per_page=10",
"previous": "https://api.example.com/?per_page=10"
}

個別のサーバー情報を取得する

Authorizations:

ApiKeyAuth

path Parameters

server_id

required

integer

サーバーID

Responses

Response samples

200
401
404
429

Content type

application/json

{"id": 0,
"name": "string",
"description": "string",
"service_type": "linux",
"service_status": "on_trial",
"cpu_cores": 2,
"memory_mebibytes": 1024,
"storage": [{"port": 0,
"type": "ssd",
"size_gibibytes": 100
}
],
"zone": {"code": "tk1",
"name": "石狩第1"
},
"options": ["SQL Server Web Edition"
],
"version": "v5",
"ipv4": {"address": "198.51.100.2",
"netmask": "255.255.254.0",
"gateway": "198.51.100.1",
"nameservers": ["203.0.113.1"
],
"hostname": "example.jp",
"ptr": "example.jp"
},
"ipv6": {"address": "2001:e42:102:1501:153:121:89:107",
"prefixlen": 64,
"gateway": "fe80::1",
"nameservers": ["2001:e42::1"
],
"hostname": "example.jp",
"ptr": "example.jp"
},
"contract": {"plan_code": 3439,
"plan_name": "さくらのVPS(v5)  1G IK01",
"service_code": "100000000000"
},
"power_status": "power_on"
}

個別のサーバー情報を更新する

Authorizations:

ApiKeyAuth

path Parameters

server_id

required

integer

サーバーID

Request Body schema: application/json

name required	string 名前
description required	string 説明

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"description": "string"
}

Response samples

200
400
401
404
429

Content type

application/json

{"id": 0,
"name": "string",
"description": "string",
"service_type": "linux",
"service_status": "on_trial",
"cpu_cores": 2,
"memory_mebibytes": 1024,
"storage": [{"port": 0,
"type": "ssd",
"size_gibibytes": 100
}
],
"zone": {"code": "tk1",
"name": "石狩第1"
},
"options": ["SQL Server Web Edition"
],
"version": "v5",
"ipv4": {"address": "198.51.100.2",
"netmask": "255.255.254.0",
"gateway": "198.51.100.1",
"nameservers": ["203.0.113.1"
],
"hostname": "example.jp",
"ptr": "example.jp"
},
"ipv6": {"address": "2001:e42:102:1501:153:121:89:107",
"prefixlen": 64,
"gateway": "fe80::1",
"nameservers": ["2001:e42::1"
],
"hostname": "example.jp",
"ptr": "example.jp"
},
"contract": {"plan_code": 3439,
"plan_name": "さくらのVPS(v5)  1G IK01",
"service_code": "100000000000"
},
"power_status": "power_on"
}

サーバーの電源状態を取得する

Authorizations:

ApiKeyAuth

path Parameters

server_id

required

integer

サーバーID

Responses

Response samples

200
401
404
429
503

Content type

application/json

{"status": "power_on"
}

サーバーを起動する

Authorizations:

ApiKeyAuth

path Parameters

server_id

required

integer

サーバーID

Responses

Response samples

401
404
409
429
503

Content type

application/json

{"code": "not_authenticated",
"message": "認証情報が含まれていません。"
}

サーバーをシャットダウンする

Authorizations:

ApiKeyAuth

path Parameters

server_id

required

integer

サーバーID

Request Body schema: application/json

force

boolean

Default: false

強制停止を行うか

Responses

Request samples

Payload

Content type

application/json

{"force": false
}

Response samples

401
404
409
429
503

Content type

application/json

{"code": "not_authenticated",
"message": "認証情報が含まれていません。"
}

サーバーを強制再起動する

Authorizations:

ApiKeyAuth

path Parameters

server_id

required

integer

サーバーID

Responses

Response samples

401
404
409
429
503

Content type

application/json

{"code": "not_authenticated",
"message": "認証情報が含まれていません。"
}

サーバーのipv4の逆引きホスト名を設定する

Authorizations:

ApiKeyAuth

path Parameters

server_id

required

integer

サーバーID

Request Body schema: application/json

hostname

string

Default: "example.jp"

ホスト名

Responses

Request samples

Payload

Content type

application/json

{"hostname": "example.jp"
}

Response samples

400
401
404
429
503

Content type

application/json

{"code": "invalid",
"message": "Invalid input.",
"errors": {"foo": [{"code": "required",
"message": "この項目は必須です"
}
]
}
}

個別のサーバーのインターフェース情報一覧を取得する

Authorizations:

ApiKeyAuth

path Parameters

server_id

required

integer

サーバーID

Responses

Response samples

200
401
404
429

Content type

application/json

{"results": [{"id": 0,
"device": "eth0",
"connectable_to_global_network": true,
"connect_to": "global",
"mac": "9C:A3:BA:00:00:00",
"switch_id": 1
}
],
"count": 100,
"next": "https://api.example.com/?page=3&per_page=10",
"previous": "https://api.example.com/?per_page=10"
}

個別のインターフェース情報を取得する

Authorizations:

ApiKeyAuth

path Parameters

server_id required	integer サーバーID
interface_id required	integer サーバーインターフェースID

Responses

Response samples

200
401
404
429

Content type

application/json

{"id": 0,
"device": "eth0",
"connectable_to_global_network": true,
"connect_to": "global",
"mac": "9C:A3:BA:00:00:00",
"switch_id": 1
}

接続スイッチの切り替え

Authorizations:

ApiKeyAuth

path Parameters

server_id required	integer サーバーID
interface_id required	integer サーバーインターフェースID

Request Body schema: application/json

switch_id

required

integer or null

スイッチID

Responses

Request samples

Payload

Content type

application/json

{"switch_id": 1
}

Response samples

Content type

application/json

{"id": 0,
"device": "eth0",
"connectable_to_global_network": true,
"connect_to": "global",
"mac": "9C:A3:BA:00:00:00",
"switch_id": 1
}

サーバーのipv6の逆引きホスト名を設定する

Authorizations:

ApiKeyAuth

path Parameters

server_id

required

integer

サーバーID

Request Body schema: application/json

hostname

string

Default: "example.jp"

ホスト名

Responses

Request samples

Payload

Content type

application/json

{"hostname": "example.jp"
}

Response samples

400
401
404
429
503

Content type

application/json

{"code": "invalid",
"message": "Invalid input.",
"errors": {"foo": [{"code": "required",
"message": "この項目は必須です"
}
]
}
}

個別のサーバーのビデオデバイスの設定を取得する

Authorizations:

ApiKeyAuth

path Parameters

server_id

required

integer

サーバーID

Responses

Response samples

200
401
404
429
503

Content type

application/json

{"type": "vga"
}

個別のサーバーのビデオデバイスの設定をする

Authorizations:

ApiKeyAuth

path Parameters

server_id

required

integer

サーバーID

Request Body schema: application/json

type

required

string

Enum: "vga" "cirrus"

ビデオデバイスの種類

Responses

Request samples

Payload

Content type

application/json

{"type": "vga"
}

Response samples

Content type

application/json

{"type": "vga"
}

個別のサーバーの制限情報を取得する

Authorizations:

ApiKeyAuth

path Parameters

server_id

required

integer

サーバーID

Responses

Response samples

200
401
404
429
503

Content type

application/json

{"cpu_performance_limit": "enabled",
"network_bandwidth_limit": "enabled",
"outbound_port_25_blocking": "enabled",
"storage_iops_limit": "enabled"
}

NFSサーバー

NFSサーバー情報一覧を取得する

Authorizations:

ApiKeyAuth

query Parameters

page	integer
per_page	integer
switch	integer switchのid 対象のスイッチに接続されているサーバーに絞り込む
zone_code	string Enum: "tk1" "tk2" "tk3" "os1" "os2" "os3" "is1" ゾーンコードで絞り込む tk1 東京第1 tk2 東京第2 tk3 東京第3 os1 大阪第1 os2 大阪第2 os3 大阪第3 is1 石狩第1 例: 東京第1ゾーンのサーバーのみ取得: zone_code=tk1
sort	string Enum: "service_code" "-service_code" "name" "-name" "storage_size_gibibytes" "-storage_size_gibibytes" "ipv4_address" "-ipv4_address" "zone_code" "-zone_code" データの並び順。項目名の頭に`-`をつけると降順で取得する例: サービスコード昇順: sort=service_code サービスコード降順: sort=-service_code

Responses

Response samples

200
400
401
429

Content type

application/json

{"results": [{"id": 0,
"name": "string",
"description": "string",
"service_status": "in_preparation",
"setting_status": "done",
"storage": [{"type": "ssd",
"size_gibibytes": 100
}
],
"zone": {"code": "tk1",
"name": "石狩第1"
},
"ipv4": {"address": "198.51.100.2",
"netmask": "255.255.254.0"
},
"contract": {"plan_code": 3439,
"plan_name": "さくらのVPS(v5)  NFS 200GB OS03",
"service_code": "100000000000"
},
"power_status": "power_on"
}
],
"count": 100,
"next": "https://api.example.com/?page=3&per_page=10",
"previous": "https://api.example.com/?per_page=10"
}

個別のNFSサーバー情報を取得する

Authorizations:

ApiKeyAuth

path Parameters

nfs_server_id

required

integer

NFSサーバーID

Responses

Response samples

200
401
404
429

Content type

application/json

{"id": 0,
"name": "string",
"description": "string",
"service_status": "in_preparation",
"setting_status": "done",
"storage": [{"type": "ssd",
"size_gibibytes": 100
}
],
"zone": {"code": "tk1",
"name": "石狩第1"
},
"ipv4": {"address": "198.51.100.2",
"netmask": "255.255.254.0"
},
"contract": {"plan_code": 3439,
"plan_name": "さくらのVPS(v5)  NFS 200GB OS03",
"service_code": "100000000000"
},
"power_status": "power_on"
}

個別のNFSサーバー情報を更新する

Authorizations:

ApiKeyAuth

path Parameters

nfs_server_id

required

integer

NFSサーバーID

Request Body schema: application/json

name required	string 名前
description required	string 説明

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"description": "string"
}

Response samples

200
400
401
404
429

Content type

application/json

{"id": 0,
"name": "string",
"description": "string",
"service_status": "in_preparation",
"setting_status": "done",
"storage": [{"type": "ssd",
"size_gibibytes": 100
}
],
"zone": {"code": "tk1",
"name": "石狩第1"
},
"ipv4": {"address": "198.51.100.2",
"netmask": "255.255.254.0"
},
"contract": {"plan_code": 3439,
"plan_name": "さくらのVPS(v5)  NFS 200GB OS03",
"service_code": "100000000000"
},
"power_status": "power_on"
}

NFSサーバーのipv4を設定する

Authorizations:

ApiKeyAuth

path Parameters

nfs_server_id

required

integer

NFSサーバーID

Request Body schema: application/json

address required	string ipv4アドレス
netmask required	string ネットマスク

Responses

Request samples

Payload

Content type

application/json

{"address": "string",
"netmask": "string"
}

Response samples

Content type

application/json

{"code": "invalid",
"message": "Invalid input.",
"errors": {"foo": [{"code": "required",
"message": "この項目は必須です"
}
]
}
}

NFSサーバーの電源状態を取得する

Authorizations:

ApiKeyAuth

path Parameters

nfs_server_id

required

integer

NFSサーバーID

Responses

Response samples

200
401
404
429
503

Content type

application/json

{"status": "power_on"
}

個別のNFSサーバーのインターフェースを取得する

Authorizations:

ApiKeyAuth

path Parameters

nfs_server_id

required

integer

NFSサーバーID

Responses

Response samples

200
401
404
429

Content type

application/json

{"id": 0,
"device": "eth0",
"connect_to": "switch",
"mac": "9C:A3:BA:00:00:00",
"switch_id": 1
}

接続スイッチの切り替え

Authorizations:

ApiKeyAuth

path Parameters

nfs_server_id

required

integer

NFSサーバーID

Request Body schema: application/json

switch_id

required

integer or null

スイッチID

Responses

Request samples

Payload

Content type

application/json

{"switch_id": 1
}

Response samples

Content type

application/json

{"id": 0,
"device": "eth0",
"connect_to": "switch",
"mac": "9C:A3:BA:00:00:00",
"switch_id": 1
}

スイッチ

スイッチを作成する

Authorizations:

ApiKeyAuth

Request Body schema: application/json

name required	string 名前
description required	string 説明
zone_code required	string Enum: "tk2" "tk3" "os3" "is1" ゾーンコード tk2 東京第2 tk3 東京第3 os3 大阪第3 is1 石狩第1

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"description": "string",
"zone_code": "tk2"
}

Response samples

201
400
401
409
429

Content type

application/json

{"id": 0,
"name": "string",
"description": "string",
"switch_code": "string",
"zone": {"code": "tk2",
"name": "石狩第1"
},
"server_interfaces": [ ],
"nfs_server_interfaces": [ ],
"external_connection": null
}

スイッチ情報一覧を取得する

Authorizations:

ApiKeyAuth

query Parameters

page	integer
per_page	integer
zone_code	string Enum: "tk1" "tk2" "tk3" "os1" "os2" "os3" "is1" ゾーンコードで絞り込む tk1 東京第1 tk2 東京第2 tk3 東京第3 os1 大阪第1 os2 大阪第2 os3 大阪第3 is1 石狩第1 例: 東京第1ゾーンのサーバーのみ取得: zone_code=tk1
interface	integer interfaceのid 対象のインターフェースに接続されているスイッチに絞り込む
sort	string Enum: "name" "-name" "zone" "-zone" "interfaces_count" "-interfaces_count" データの並び順。項目名の頭に`-`をつけると降順で取得する例: 接続インターフェース数昇順: sort=interfaces_count 接続インターフェース数降順: sort=-interfaces_count
search	string 名前と説明文から部分一致検索

Responses

Response samples

200
400
401
429

Content type

application/json

{"results": [{"id": 0,
"name": "string",
"description": "string",
"switch_code": "string",
"zone": {"code": "tk1",
"name": "石狩第1"
},
"server_interfaces": [0
],
"nfs_server_interfaces": [0
],
"external_connection": {"service_code": "100000000000",
"type": "cloud",
"services": [{"service_category": "cloud",
"service_name": "クラウド東京第1ゾーン",
"switch_code": "111111111111"
}
]
}
}
],
"count": 100,
"next": "https://api.example.com/?page=3&per_page=10",
"previous": "https://api.example.com/?per_page=10"
}

個別のスイッチ情報を取得する

Authorizations:

ApiKeyAuth

path Parameters

switch_id

required

integer

スイッチID

Responses

Response samples

200
401
404
429

Content type

application/json

{"id": 0,
"name": "string",
"description": "string",
"switch_code": "string",
"zone": {"code": "tk1",
"name": "石狩第1"
},
"server_interfaces": [0
],
"nfs_server_interfaces": [0
],
"external_connection": {"service_code": "100000000000",
"type": "cloud",
"services": [{"service_category": "cloud",
"service_name": "クラウド東京第1ゾーン",
"switch_code": "111111111111"
}
]
}
}

個別のスイッチ情報を更新する

Authorizations:

ApiKeyAuth

path Parameters

switch_id

required

integer

スイッチID

Request Body schema: application/json

name required	string 名前
description required	string 説明

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"description": "string"
}

Response samples

200
400
401
404
429

Content type

application/json

{"id": 0,
"name": "string",
"description": "string",
"switch_code": "string",
"zone": {"code": "tk1",
"name": "石狩第1"
},
"server_interfaces": [0
],
"nfs_server_interfaces": [0
],
"external_connection": {"service_code": "100000000000",
"type": "cloud",
"services": [{"service_category": "cloud",
"service_name": "クラウド東京第1ゾーン",
"switch_code": "111111111111"
}
]
}
}

個別のスイッチを削除する

Authorizations:

ApiKeyAuth

path Parameters

switch_id

required

integer

スイッチID

Responses

Response samples

401
404
409
429

Content type

application/json

{"code": "not_authenticated",
"message": "認証情報が含まれていません。"
}

ディスク

ディスク情報一覧を取得する

Authorizations:

ApiKeyAuth

Responses

Response samples

200
401
429

Content type

application/json

{"results": [{"id": 0,
"name": "string",
"description": "string",
"license_required": true
}
],
"count": 100,
"next": "https://api.example.com/?page=3&per_page=10",
"previous": "https://api.example.com/?per_page=10"
}

個別のディスク情報を取得する

Authorizations:

ApiKeyAuth

path Parameters

disc_id

required

integer

ディスクID

Responses

Response samples

200
401
404
429

Content type

application/json

{"id": 0,
"name": "string",
"description": "string",
"license_required": true
}