Más contenido relacionado
La actualidad más candente (20)
Similar a インフラエンジニアなら『さくらのクラウド』をAPIでいじろう【入門編】 (20)
インフラエンジニアなら『さくらのクラウド』をAPIでいじろう【入門編】
- 1. (C)Copyright 1996-2016 SAKURA Internet Inc.
【入門編】
インフラエンジニアなら「さくらのクラウド」をAPIでいじろう
初めての人のためAPI入門! APIをコマンドラインで触ってみよう
2016年3月3日
さくらインターネット株式会社
エバンジェリスト
寺尾 英作
- 4. 会社概要
東京支社外観
商 号 さくらインターネット株式会社 (東証一部:3778)
大阪本社
東京支社
大阪市中央区南本町1-8-14 堺筋本町ビル9F
東京都新宿区西新宿7-20-1 住友不動産西新宿ビル33F
設 立 1999年8月17日 (サービス開始: 1996年12月23日)
資 本 金 8億9,530万円
売上高 105億7,600万円(2015年3月期)
事業内容
インターネットでのサーバの設置及びその管理業務
電気通信事業法に基づく電気通信事業
従業員数 266名(2015年3月末現在)
所属団体
社団法人日本ネットワークインフォメーションセンター 会員(JPNIC)
特定非営利活動法人日本データセンター協会 会員(JDCC)
社団法人インターネットプロバイダー協会 会員(JAIPA)
グリーン・グリッド(The Green Grid)
IPv6普及・高度化推進協議会 会員
ASP・SaaSインダストリ・コンソーシアム 会員 など
4
- 21. REST と JSON
API を使うにはREST とJSONは避けて通れません
REST (Representational State Transfer )とは
Webアーキテクチャスタイル(設計思想)の一つ。
同じURLやパラメータの組み合わせ時には、常に同じ結果が返されること
が期待される。
システムの状態やセッションに依存しない。
RESTに準拠したインタフェースのことをRESTful API と呼びます。
さくらのクラウドのAPIもRESTful APIです
- 25. さくらのクラウド API 1.1
http://developer.sakura.ad.jp/cloud/api/1.1/
API URL(エンドポイントのベースURL)
https://secure.sakura.ad.jp/cloud/zone/tk1a/api/cloud/1.1/ (東京第1ゾーン)
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)
エンドポイントのURL
ベースURL パス
https://secure.sakura.ad.jp/cloud/zone/tk1a/api/cloud/1.1 /server
ゾーン バージョン
- 35. 簡易リクエスト方法
メソッドは GET / POST / PUT / DELETE の4種類あります。
GET 情報の取得
POST リソースの登録・作成
PUT リソースの部分登録・変更
DELETE リソースの削除
- 40. サーバを作成する
• その前に
2xx系 成功
3xx系 情報
4xx系 一時的失敗
5xx系 失敗
ステータスコード 内容
200 OK
正常に処理され、何らかのレスポンスが返却さ
れた。
201 Created
正常に処理され、何らかのリソースが作成され
た。
例:仮想サーバを作成した
202 Accepted
正常に受け付けられたが、処理は完了していな
い。
例:ディスクの複製を開始したが、まだ完了し
ていない
204 No Content 正常に処理され、空のレスポンスが返却された。
ステータスコード 内容
305 Use Proxy
Locationフィールドに示されたプロクシ経由
でのアクセスが必要。
ステータスコード 内容
500 Internal
Server Error
内部エラーが発生した。
例:PHPエラーが発生した。
503 Service
Unavailable
何らかの事情によりサービスが利用可能
でない。
例:DB接続に失敗した
次ページ参照
- 41. サーバを作成する
4xx系 成功
ステータスコード 内容
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フォーマットを要求した。
- 42. 共通インタフェース
• 「リソースの検索」共通インタフェース
• レスポンスの共通仕様
• リクエストパラメータの共通仕様
• ページング / ソート / フィルタリング / 取得キーを除外 / 取得キーの選択
• 各オプション指定時の挙動
• リソース取得(GET)
• レスポンスの共通仕様
• リクエストパラメータの共通仕様
• 取得キーについて
• リソース登録(POST)
• レスポンスの共通仕様
• リクエストパラメータの共通仕様
• 返却件数の指定 /返却件数の排除
• リソース設定(PUT)
• レスポンスの共通仕様
• リクエストパラメータの共通仕様
• リソース解放(DELETE)
• レスポンスの共通仕様
• リクエストパラメータの共通仕様
- 44. 「リソースの検索」共通インタフェース
{
"Total": 300,
"From": 100, /* 0から始まる通し番号 */
"Count": 50,
"Servers": [ /* 原則としてリソース名の複数形 */
{
"Index": 100, /* 0から始まる通し番号 */
"ID": xxxxxxxxxxxx, /* サーバID */
...
},
{
"Index": 101,
"ID": yyyyyyyyyyyy,
...
},
...
{
"Index": 150,
"ID": zzzzzzzzzzzz,
...
}
]
}
- 59. サーバプランの確認
GET /product/server | jq . | more
レスポンス
{
"is_ok": true,
"ServerPlans": [
{
"Availability": "available",
"ServiceClass": "cloud/plan/1core-1gb",
"MemoryMB": 1024,
"CPU": 1,
"Description": "",
"Name": "プラン/1Core-1GB",
"ID": 1001,
"Index": 0
},
....
サーバの作成をするには、まずサーバプランを指定する必要があります。
こんな感じで取得できるのですが、たくさんプランが出てくるので見にくいです。
- 60. サーバプランの取得
GET /product/server?Sort=CPU | jq -c
".ServerPlans[] | {Availability, ID, ServiceClass,ServiceClass,CPU,MemoryMB}"
{"MemoryMB":1024,"CPU":1,"ServiceClass":"cloud/plan/1core-1gb","ID":1001,"Availability":"available"}
{"MemoryMB":2048,"CPU":1,"ServiceClass":"cloud/plan/1core-2gb","ID":2001,"Availability":"available"}
{"MemoryMB":3072,"CPU":1,"ServiceClass":"cloud/plan/1core-3gb","ID":3001,"Availability":"available"}
{"MemoryMB":4096,"CPU":1,"ServiceClass":"cloud/plan/1core-4gb","ID":4001,"Availability":"available"}
{"MemoryMB":5120,"CPU":1,"ServiceClass":"cloud/plan/1core-5gb","ID":5001,"Availability":"available"}
{"MemoryMB":2048,"CPU":2,"ServiceClass":"cloud/plan/2core-2gb","ID":2002,"Availability":"available"}
{"MemoryMB":3072,"CPU":2,"ServiceClass":"cloud/plan/2core-3gb","ID":3002,"Availability":"available"}
…
GETのリクエストストリングで指定する場合、
JSON形式と、URL形式(a=a&B-b)の2つの方法が
選べます。URL形式の方が楽ちんです。
• SortやFlterでキーを指定する場合は、トップレベルのキー(ここでは`ServerPlans`)は不要です
• jq –c を指定すると出力がコンパクトにまとまります。
値を絞り込んで出力したい場合、以下の
ように、jq でキーを列挙することで指定
のキーのみを取り出すことが出来ます。
- 61. サーバ作成
POST /cloud/1.1/server
リクエスト
{
"Count": 0,
"Server": {
"WaitDiskMigration": true,
"Icon": null,
"Tags": [ "@virtio-net-pci", "apitest" ],
"Description": ”apitest",
"Name": "ServerAPI03",
"ConnectedSwitches": [
{
"virtio": true,
"BandWidthMbps": 100,
"Scope": "shared",
"_operation": "internet"
}
],
"ServerPlan": { "ID": 1001 }
}
}
ServerPlanを確認する必要があります
インターネット接続は
100Mbps 共有ベストエフォート
インターネット接続は
100Mbps 共有ベストエフォート
- 62. サーバ作成
curl --user "Access_Token":"Access_Token_Secret"
-X POST -d
'{"Server":{"ServerPlan":{"ID":1001},"ConnectedSwitches":[{"_operation":"internet","Scope":"sh
ared","BandWidthMbps":100,"virtio":true}],"Name":"ServerAPI03","Description":"apitest","Tags
":["@virtio-net-pci","apitest"],"Icon":null,"WaitDiskMigration":true},"Count":0}'
https://secure.sakura.ad.jp/cloud/zone/is1a/api/cloud/1.1/server | jq .
リクエスト
ようやく、サーバ作成が出来ます。
リクエストデータをcurlの –d オプションで指定します。
シングルクオーテーションで全体を囲みます。(JSONに
ダブルクオーテーションが多いので)
- 63. サーバ作成
{
"is_ok": true,
"Success": true,
"Server": {
"Interfaces": [
{
"Subnet": {
"DefaultRoute": "133.242.70.1",
"NetworkMaskLen": 24,
"NetworkAddress": "133.242.70.0",
"ID": null
},
},
"IPAddress": "133.242.70.90",
}
],
"ID": "112800580022",
"Name": "ServerAPI03",
"HostName": "localhost",
"Description": "test",
"Availability": "migrating",
"ServiceClass": "cloud/plan/1core-1gb",
}
}
レスポンス(抜粋)
ネットワーク情報
割り当てられたIPアドレス
サーバのリソースID(サーバID)
- 64. サーバの検索
/server?Filter=Servers.Tags:apitest |
jq -c ".Servers[] | {ID, Name, HostName, IPAddress : .Interfaces[].IPAddress ,
Status : .Instance.Status } "
サーバが出来たかを確認しましょう。
{"Status":"down","IPAddress":"133.242.19.104","HostName":"localhost","Name":"ServerAPI01
","ID":"112800578058"}
{"Status":"down","IPAddress":"133.242.22.14","HostName":"localhost","Name":"ServerAPI01"
,"ID":"112800578062"}
{"Status":"up","IPAddress":"133.242.49.106","HostName":"localhost","Name":"plesk02","ID"
:"112800528996"}
リクエスト
レスポンス
- 65. アーカイブの一覧の取得
GET /archive?Filter="Scope":"shared"&Sort=Name' | jq -c ".Archives[] |
{ID,Name,Scope,SizeMB}"
アーカイブの一覧を取得します。
パブリックアーカイブがインストールの元となるアーカイブです。
{"SizeMB":20480,"Scope":"shared","Name":"CentOS 5.11 64bit","ID":"112800291714"}
{"SizeMB":102400,"Scope":"shared","Name":"CentOS 5.11 64bit","ID":"112800291715"}
{"SizeMB":20480,"Scope":"shared","Name":"CentOS 6.7 64bit","ID":"112800239057"}
{"SizeMB":20480,"Scope":"shared","Name":"CentOS 7.2 64bit","ID":"112800239060"}
{"SizeMB":20480,"Scope":"shared","Name":"CoreOS 367.1.0 (stable)","ID":"112600559834"}
{"SizeMB":20480,"Scope":"shared","Name":"Debian GNU/Linux 7.10.0 64bit","ID":"112800438502"}
{"SizeMB":20480,"Scope":"shared","Name":"Debian GNU/Linux 8.4.0 64bit","ID":"112800438543"}
......
リクエスト
レスポンス
パブリックアーカイブは、
Scopeが"shared" となっています
- 66. ディスクプランの取得
curl --user "Access_Token":"Access_Token_Secret"
https://secure.sakura.ad.jp/cloud/zone/is1a/api/cloud/1.1/product/disk
| jq -c ".DiskPlans[] | {ID,Name, SizeMB : .Size[].SizeMB}"
{"SizeMB":20480,"Name":"SSDプラン","ID":4}
{"SizeMB":102400,"Name":"SSDプラン","ID":4}
{"SizeMB":256000,"Name":"SSDプラン","ID":4}
{"SizeMB":512000,"Name":"SSDプラン","ID":4}
{"SizeMB":40960,"Name":"標準プラン","ID":2}
{"SizeMB":61440,"Name":"標準プラン","ID":2}
{"SizeMB":81920,"Name":"標準プラン","ID":2}
{"SizeMB":102400,"Name":"標準プラン","ID":2}
{"SizeMB":256000,"Name":"標準プラン","ID":2}
{"SizeMB":512000,"Name":"標準プラン","ID":2}
{"SizeMB":768000,"Name":"標準プラン","ID":2}
{"SizeMB":1048576,"Name":"標準プラン","ID":2}
{"SizeMB":2097152,"Name":"標準プラン","ID":2}
{"SizeMB":4194304,"Name":"標準プラン","ID":2}
レスポンス
リクエスト
- 67. ディスクの作成とサーバとの接続
POST /cloud/1.1/disk
{
"Count": 0,
"Disk": {
"Server": {
"ID": "112800580022"
},
"Name": "ServerAPI03",
"Connection": "virtio",
"SizeMB": 20480,
"SourceArchive": {
"ID": "112800239060"
},
"Plan": { "ID": 4 }
}
}
リクエスト
接続するサーバと同じ
先ほど作成したサーバの
リソースID(サーバID)を指定。ディスク作成後
直ぐに接続する。
ディスクプランで取得したIDを指定
HDD:2 / SSD:4
ディスクプランで取得したディスクサイズ
を数値で指定
アーカイブ一覧で取得したパブリックアーカイ
ブ(OS)のIDを指定
- 68. ディスクの作成とサーバとの接続
curl --user "Access_Token":"Access_Token_Secret"
-X POST –d
'{"Disk":{"Plan":{"ID":4},"SourceArchive":{"ID":"112800239060"},"SizeMB":20480
,"Connection":"virtio","Name":"ServerAPI03","Server":{"ID":"112800580022"}},"C
ount":0}'
https://secure.sakura.ad.jp/cloud/zone/is1a/api/cloud/1.1/disk | jq .
{
"is_ok": true,
"Success": "Accepted",
"Disk": {
"SizeMB": 20480,
"Name": "ServerAPI03",
"ID": "112800580030"
}
}
レスポンス(抜粋)
リクエストコマンド
作成したディスクのID
- 69. ディスクの修正
PUT cloud/1.1/disk/112800579885/config
{
"Count": 0,
"HostName": "ServerAPI03",
"Password": "124YJNLu"
}
リクエスト
サーバのホスト名を書き込み
root パスワードを書き込み
作成したディスクのID
curl --user "Access_Token":"Access_Token_Secret"
-X PUT -d '{"Password":"124YJNLu","HostName":"ServerAPI03","Count":0}'
https://secure.sakura.ad.jp/cloud/zone/is1a/api/cloud/1.1/disk/112800580030/co
nfig | jq .
リクエストコマンド
{ "is_ok": true, "Success": true }
レスポンス
- 71. サーバの検索
/server?Filter=Servers.Tags:apitest |
jq -c ".Servers[] | {ID, Name, HostName, IPAddress : .Interfaces[].IPAddress ,
Status : .Instance.Status } "
サーバが出来たかを確認しましょう。
{"Status":"down","IPAddress":"192.168.xx.104","HostName":"localhost","Name":"ServerAPI01
","ID":"112800578058"}
{"Status":"down","IPAddress":"192.168.x.14","HostName":"localhost","Name":"ServerAPI01",
"ID":"112800578062"}
{"Status":"up","IPAddress":" 192.168.xx.106","HostName":"localhost","Name":" ServerAPI03
","ID":"112800580022"}
リクエスト
レスポンス
- 73. シンプル監視の登録
POST cloud/1.1/commonserviceitem
{
"Count": 0,
"CommonServiceItem": {
"Description": "ServerAPI03",
"Icon": {},
"Tags": [],
"Provider": {
"Class": "simplemon"
},
"Settings": {
"SimpleMonitor": {
"NotifySlack": {
"Enabled": "False"
},
リクエスト
"NotifyEmail": {
"Enabled": "True"
},
"Enabled": "True",
"HealthCheck": {
"Protocol": "ping"
},
"DelayLoop": 60
}
},
"Status": {
"Target": "133.242.70.90"
},
"Name": "133.242.70.90"
}
}
シンプル監視は アプライアンス関連APIの commonserviceitem を通して設定をおこないます。
- 74. シンプル監視の登録
curl --user "Access_Token":"Access_Token_Secret"
-X PUT -d ''
'{"CommonServiceItem":{"Name":"133.242.70.90","Status":{"Target":"133.242.70.9
0"},"Settings":{"SimpleMonitor":{"DelayLoop":60,"HealthCheck":{"Protocol":"pin
g"},"Enabled":"True","NotifyEmail":{"Enabled":"True"},"NotifySlack":{"Enabled"
:"False"}}},"Provider":{"Class":"simplemon"},"Tags":[],"Icon":{},"Description"
:"ServerAPI03"},"Count":0}'
https://secure.sakura.ad.jp/cloud/zone/is1a/api/cloud/1.1/commonserviceitem |
jq .
リクエストコマンド
{
"is_ok": true,
"Success": true,
"CommonServiceItem": {
"ID": "112800580626",
}
}
レスポンス(抜粋)
修正や削除はこのIDを使って指定します
- 77. 料金一覧表の取得
– サーバやディスクはゾーンごとに料金が異なります。どのゾーンにリクエストをお
こなうかで、どのゾーンの料金が帰ってくるかが決まります
– このエンドポイントのみ認証が必要ありません。
• Authorizationヘッダは指定しないでください。
• 次のヘッダを指定してください。 X-Requested-With: XMLHttpRequest
• 廃止されたサービスや、一部のお客様向けの特殊なサービス等は表に含まれません。
石狩第一ゾーンの価格一覧表を取得
curl -H "X-Requested-With:XMLHttpRequest"
https://secure.sakura.ad.jp/cloud/zone/is1a/api/cloud/1.1/public/price.json
curl --user "Access Token":"Access Token Secret"
https://secure.sakura.ad.jp/cloud/zone/is1a/api/cloud/1.1/public/price.json
APIキーによる認証を行う場合のリクエストコマンド
APIキーによる認証を行わない場合のリクエストコマンド
GET /public/price
リクエスト
- 78. 料金一覧表の取得
"65": {
"ServiceClassPath": "cloud/plan/2core-3gb",
"ServiceClassName": "plan/2core-3gb",
"ServiceClassID": 50179,
"Price": {
"Zone": "is1a",
"Monthly": 4050,
"Hourly": 19,
"Daily": 203,
"Base": 0
},
"IsPublic": true,
"DisplayName": "プラン/2Core-3GB"
}
レスポンス(抜粋)
サーバやディスクなどの料金は、時間、日次、月次それぞれで料金が決まっています。
Hourly x 時間数 : Daily (およそ10時間前後)
Daily x 日数 : Monthly (およそ20時間前後)
のどちらが安いかで、どちらの料金が採用になるかが決まります。Monthlyが上限となります
- 79. アカウントIDの確認
• APIを実行するには、アカウントのアカウントIDが必要
• testaccount xxx000001(数字列)
• アカウントコード アカウントのリソースID(アカウントID)
curl --user 'ACCESS_TOKEN':'ACCESS_TOKEN_SECRET'
https://secure.sakura.ad.jp/cloud/zone/tk1a/api/cloud/1.1/auth-status |
jq -c " .Account "
{"Code":"billTest","Name":"APIテスト用","Class":"account","ID":"000000526782"}
レスポンス
リクエストコマンド
※どのゾーンにリクエストしても構いません
アカウントID
- 81. 過去の請求履歴を確認
{
"is_ok": true,
"ResponsedAt": "2016-06-01T13:33:13+09:00",
"Count": 12,
"Bills": [
{
"PaymentClassID": 200,
"PayLimit": "2016-06-30T00:00:00+09:00",
"Paid": false,
"MemberID": "xxx000001",
"Date": "2016-06-10T00:00:00+09:00",
"BillID": 13481639,
"Amount": 4330
},
.....(月が繰り返します)
}
レスポンス
請求書No。さらに詳細を見るときに使います。
請求書No。さらに詳細を見るときに使います。
請求書No。さらに詳細を見るときに使います。
請求年月
- 82. 請求明細を取得(CSV)
printf "`curl --user 'ACCESS_TOKEN':'ACCESS_TOKEN_SECRET'
https://secure.sakura.ad.jp/cloud/zone/tk1a/api/system/1.0/billdetail/xxx000001/
000000000/csv | jq .Body`"
リクエストコマンド(請求関連API)
""連番","請求書番号","利用年月","支払いステータス","会員ID","アカウントコード","リソー
スID","商品ID","商品名","ゾーンID","ゾーン名","日数","時間","商品金額(税別)","税金","リ
ソース名"
"1","000000000","2015/09","入金済み","xxx000001","payTest","112700526782","50000","さく
らのクラウド",,,"30","0","0","0",
"2","000000000","2015/09","入金済み","xxx000001","payTest","112700654736","50118","ISOイ
メージアップロード/5GB","is1b","石狩第2ゾーン","30","0","100","8","名称未設定 ISOイメー
ジ 14ef10fedac"
"3","000000000","2015/09","入金済み
","xxx000001","payTest","112700675125","50295","GSLB",,,"28","16","500","40","テスト"
"
レスポンス 請求書ID
アカウントID
JSON形式の応答は、必要な情報を追加で山ほど取ってくる必要があるため、CSV形式を推奨します。
エスケープコードの処理のため
- 85. Apendix
• さくらのクラウドAPI
– http://developer.sakura.ad.jp/cloud/api/1.1/
– 価格一覧表をAPI経由で取得できるようになりました
– http://cloud-news.sakura.ad.jp/2016/04/01/cloud-pricelist-api/
• さくらのクラウドAPI請求関連API
– http://developer.sakura.ad.jp/cloud/api/1.1/bill/
• 請求関連APIの使い方
– http://cloud-news.sakura.ad.jp/billapi/
• 【TIPS】さくらのクラウドでAuto Scaling
– http://cloud-news.sakura.ad.jp/2016/03/18/auto-scaling/
85
Notas del editor
- コロケーションからホスティングまで、データセンター事業を幅広く展開している数少ないインフラ提供事業者です。
さくらのレンタルサーバ 2004年7月のリリースから11年 が経過し、ご利用件数40万件突破
さくらのVPS 2010年9月のリリースから、5年ご利用件数7万件突破
- その他に提供形態によるSaaS,PaaS,IaaSといった形態
また資産を持たずサービスとして利用できるメリットもあります。
アメリカ合衆国の連邦政府機関の一つで、科学技術に関連する標準についての研究などを行う機関。
http://www.idcf.jp/cloud/column/rentalserver_cloud.html