このドキュメントでは、API リクエストを作成して、Compute Engine API からの API レスポンスを処理する方法について説明します。このドキュメントで説明する内容は以下のとおりです。
- リクエスト本文を作成する。
- リクエストに必要なリソース URI を確認する。
- API レスポンスを処理する。
- API リクエストが成功したかどうか確認する。
このドキュメントでは API から承認を受ける方法については説明しません。API から承認を受ける方法については、リクエストを承認するを参照してください。
始める前に
- REST API について習熟します。
- Compute Engine API に対するリクエストを承認する方法を把握します。
API リクエストを作成する
Compute Engine API は、API リクエストが JSON 形式で記述されているものとして処理を進めます。API リクエストを作成するには、curl や httplib2 などのツールを使用して直接 HTTP リクエストを作成するか、またはいずれかの利用可能なクライアント ライブラリを使用します。
POST
、UPDATE
、PATCH
リクエストのように、リクエストの本文を必要とする API リクエストを作成する場合は、リクエストの本文に、そのリクエストで設定する必要のあるリソース プロパティを含めます。たとえば、次の curl コマンドでは、Instances リソース URI に対する POST
リクエストを作成しています。このリクエストにより、リクエストの本文に指定されたプロパティを使って新しいインスタンスが作成されます。
curl -X POST -H "Authorization: Bearer [OAUTH_TOKEN]" -H "Content-Type: application/json" https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances -d '{ "disks":[ { "boot":"true", "initializeParams":{ "sourceImage":"https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-8-jessie-v20160301" } } ], "machineType":"https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/machineTypes/n1-standard-1", "name":"[INSTANCE_NAME]", "networkInterfaces":[ { "accessConfigs":[ { "name":"external-nat", "type":"ONE_TO_ONE_NAT" } ], "network":"https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/networks/default" } ] }'
このケースでは、リクエストの本文を -d
フラグで指定しています。リクエストの本文は次の部分になります(読みやすいようにフォーマットを整えてあります)。
{ "disks":[ { "boot":"true", "initializeParams":{ "sourceImage":"https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-8-jessie-v20160301" } } ], "machineType":"https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/machineTypes/n1-standard-1", "name":"[EXAMPLE_INSTANCE]", "networkInterfaces":[ { "accessConfigs":[ { "name":"external-nat", "type":"ONE_TO_ONE_NAT" } ], "network":"https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/networks/default" } ] }
以下の点に注意してください。
別のリソースを参照する際には、完全修飾リソース URI を使用します。たとえば、
network
プロパティでは、default
ネットワークに対する完全修飾 URI を使用しています。イメージ URI のプロジェクト ID(
debian-cloud
)が、ユーザーのプロジェクト ID と異なっています。これは、イメージが、そのタイプに応じて、異なるプロジェクトに属するためです。たとえば、Compute Engine によって提供されているすべての一般公開 Debian イメージは、debian-cloud
プロジェクトでホストされています。
以下に、Python および Java クライアント ライブラリを使用した別の API リクエストの例を示します。
Python
Java
URI リソースを作成する
上の例では、別の Google Cloud Platform リソースを参照する必要があるときはいつでも、次のような完全修飾 URI を指定しています。
https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/[RESOURCE_TYPE]/[SPECIFIC_RESOURCE]
API を使用するときに、イメージ、マシンタイプ、ネットワーク、その他の任意のリソースを指定する際にはいつでも、そのリソースに対する URI を指定する必要があります。gcloud
や Google Cloud Platform Console のようなクライアント ツールを使用すれば、こうしたリソース URI の作成という面倒な作業をすべて肩代わりしてくれますが、API を直接オペレーションする場合は、そうしたリソース URI を自分で作成する必要があります。
リソース URI は、リソースのタイプに応じて若干異なります。たとえば、ゾーンリソースの場合は、URI に zone
指定が必要です。次に例を示します。
https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/machineTypes/n1-standard-1
リージョン リソースの場合は、zone
指定を region
指定で置き換えます。
https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/regions/[REGION]/addresses/[ADDRESS_NAME]
グローバル リソースの場合は、global
指定が必要です。
https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/images/[IMAGE_NAME]
Compute Engine API では、部分 URI も使用できます。プロジェクト ID のような情報はサービス側で推測できるからです。したがって、上記の URI は、次のように部分 URI として書くことも可能です。
zones/[ZONE]/machineTypes/n1-standard-1
regions/[REGION]/addresses/[ADDRESS_NAME]
project/[PROJECT_ID]/global/images/[IMAGE_NAME]
上記の部分 URI では、ゾーン URI とリージョン URI の両方でプロジェクト ID が省略されていますが、イメージ URI では省略されていません。これは、Compute Engine によって一般公開されているイメージが別のプロジェクト(Debian イメージの場合は debian-cloud
、Ubuntu イメージの場合は ubuntu-os-cloud
など)でホストされているためです。これらのイメージを使用するには、適切なプロジェクト ID を指定する必要があります。イメージのプロジェクト ID を省略すると、Compute Engine は現在のプロジェクト内でイメージを探そうとしますが、該当するイメージが存在しないため、リクエストは失敗します。
一方、現在のプロジェクト(このリソースを作成しているプロジェクト)に属するカスタム イメージを使用する場合は、イメージ URI を指定する際にプロジェクトの指定を省略できます。
必要なプロパティを確認する
v1 API およびベータ版 API で利用可能な API リファレンス ドキュメントには、特定のリソースに設定可能なすべてのプロパティが記載されています。このリファレンス ドキュメントでは、変更可能なプロパティと変更不可のプロパティ(プロパティの説明で [Output Only]
とマークされている)を区別していますが、リソースの必須プロパティを確認するには、そのタスクに固有のドキュメントを参照する必要があります。
たとえば、新しいインスタンスを作成する場合は、インスタンスの作成と開始に関するドキュメントを読んで、リクエストに必要な API プロパティを確認します。API で外部の静的 IP アドレスを作成する必要がある場合は、外部の静的 IP アドレスに関するドキュメントをお読みください。
あるいは、API explorer で API リクエストを検証することも可能です。これにより、簡単かつ迅速にコードをチェックできます。
API レスポンスを処理する
データを変更するリクエストを作成すると、Compute Engine は Operations オブジェクトを返します。このオブジェクトをポーリングするとリクエストのステータスを取得できます。以下に、Operation リソースの例を示します。
{ "kind": "compute#operation", "id": "7127550864823803662", "name": "operation-1458856416788-52ed27a803e22-1c3bd86a-9e95017b", "zone": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]", "operationType": "insert", "targetLink": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[EXAMPLE_INSTANCE]", "targetId": "4132355614508179214", "status": "PENDING", "user": "user@example.com", "progress": 0, "insertTime": "2016-03-24T14:53:37.788-07:00", "selfLink": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/operations/operation-1458856416788-52ed27a803e22-1c3bd86a-9e95017b" }
元のリクエストがゾーンリソース(インスタンスやディスク)を変更するものであった場合、Compute Engine は zoneOperations
オブジェクトを返します。同様に、リージョン リソースとグローバル リソースについては、regionOperations
オブジェクトと globalOperations
オブジェクトがそれぞれ返されます。オペレーションのステータスを取得するには、特定の Operation リソースに対して name
でオペレーションの名前を指定して GET
リクエストを実行します。
Operation リソースの状態として DONE
が返されるまでリクエストは完了していません。リクエストの性質によっては、完了までに時間を要することもあります。オペレーションの状態が DONE
として返されたら、オペレーションが成功したかどうか、エラーが発生していないかどうかを確認する必要があります。
たとえば、上記のオペレーションに対する次のレスポンスは、ステータスが DONE
になっているので、オペレーションが完了したことを示しています。
endTime: '2016-03-24T14:54:07.119-07:00' id: '7127550864823803662' insertTime: '2016-03-24T14:53:37.788-07:00' kind: compute#operation name: operation-1458856416788-52ed27a803e22-1c3bd86a-9e95017b operationType: insert progress: 100 selfLink: https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/operations/operation-1458856416788-52ed27a803e22-1c3bd86a-9e95017b startTime: '2016-03-24T14:53:38.397-07:00' status: DONE targetId: '4132355614508179214' targetLink: https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[EXAMPLE_INSTANCE] user: phunl@google.com zone: https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]
確認するには、当該リソースに対して GET
リクエストを実行して、そのリソースが存在しており、なおかつ実行中であることを確認します。次に例を示します。
GET /compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[EXAMPLE_INSTANCE] { "cpuPlatform": "Intel Haswell", "creationTimestamp": "2016-03-24T14:53:37.170-07:00", "disks": [ ..[snip].. "selfLink": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[EXAMPLE_INSTANCE]", "status": "RUNNING", "tags": { "fingerprint": "42WmSpB8rSM=" }, "zone": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]" }
オペレーションをポーリングする
オペレーションが正常に完了しているかどうか確認するために、オペレーションのステータスを取得するリクエストを繰り返し実行するのは面倒です。そのような場合は、オペレーションを定期的にポーリングして、オペレーション ステータスが DONE
になったら復帰するコードを書くことをおすすめします。以下に、Python と Java で書かれたポーリングの例を示します。