API リクエストの作成とレスポンスの処理

このドキュメントでは、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

compute/api/create_instance.py

GitHub で表示

def create_instance(compute, project, zone, name, bucket):
    # Get the latest Debian Jessie image.
    image_response = compute.images().getFromFamily(
        project='debian-cloud', family='debian-9').execute()
    source_disk_image = image_response['selfLink']

    # Configure the machine
    machine_type = "zones/%s/machineTypes/n1-standard-1" % zone
    startup_script = open(
        os.path.join(
            os.path.dirname(__file__), 'startup-script.sh'), 'r').read()
    image_url = "http://storage.googleapis.com/gce-demo-input/photo.jpg"
    image_caption = "Ready for dessert?"

    config = {
        'name': name,
        'machineType': machine_type,

        # Specify the boot disk and the image to use as a source.
        'disks': [
            {
                'boot': True,
                'autoDelete': True,
                'initializeParams': {
                    'sourceImage': source_disk_image,
                }
            }
        ],

        # Specify a network interface with NAT to access the public
        # internet.
        'networkInterfaces': [{
            'network': 'global/networks/default',
            'accessConfigs': [
                {'type': 'ONE_TO_ONE_NAT', 'name': 'External NAT'}
            ]
        }],

        # Allow the instance to access cloud storage and logging.
        'serviceAccounts': [{
            'email': 'default',
            'scopes': [
                'https://www.googleapis.com/auth/devstorage.read_write',
                'https://www.googleapis.com/auth/logging.write'
            ]
        }],

        # Metadata is readable from the instance and allows you to
        # pass configuration from deployment scripts to instances.
        'metadata': {
            'items': [{
                # Startup script is automatically executed by the
                # instance upon startup.
                'key': 'startup-script',
                'value': startup_script
            }, {
                'key': 'url',
                'value': image_url
            }, {
                'key': 'text',
                'value': image_caption
            }, {
                'key': 'bucket',
                'value': bucket
            }]
        }
    }

    return compute.instances().insert(
        project=project,
        zone=zone,
        body=config).execute()

Java

compute/cmdline/src/main/java/ComputeEngineSample.java

GitHub で表示

public static Operation startInstance(Compute compute, String instanceName) throws IOException {
  System.out.println("================== Starting New Instance ==================");

  // Create VM Instance object with the required properties.
  Instance instance = new Instance();
  instance.setName(instanceName);
  instance.setMachineType(
      "https://www.googleapis.com/compute/v1/projects/"
      + PROJECT_ID + "/zones/" + ZONE_NAME + "/machineTypes/n1-standard-1");

  // Add Network Interface to be used by VM Instance.
  NetworkInterface ifc = new NetworkInterface();
  ifc.setNetwork("https://www.googleapis.com/compute/v1/projects/" + PROJECT_ID + "/global/networks/default");
  List<AccessConfig> configs = new ArrayList<>();
  AccessConfig config = new AccessConfig();
  config.setType(NETWORK_INTERFACE_CONFIG);
  config.setName(NETWORK_ACCESS_CONFIG);
  configs.add(config);
  ifc.setAccessConfigs(configs);
  instance.setNetworkInterfaces(Collections.singletonList(ifc));

  // Add attached Persistent Disk to be used by VM Instance.
  AttachedDisk disk = new AttachedDisk();
  disk.setBoot(true);
  disk.setAutoDelete(true);
  disk.setType("PERSISTENT");
  AttachedDiskInitializeParams params = new AttachedDiskInitializeParams();
  // Assign the Persistent Disk the same name as the VM Instance.
  params.setDiskName(instanceName);
  // Specify the source operating system machine image to be used by the VM Instance.
  params.setSourceImage(SOURCE_IMAGE_PREFIX + SOURCE_IMAGE_PATH);
  // Specify the disk type as Standard Persistent Disk
  params.setDiskType("https://www.googleapis.com/compute/v1/projects/" + PROJECT_ID + "/zones/"
                     + ZONE_NAME + "/diskTypes/pd-standard");
  disk.setInitializeParams(params);
  instance.setDisks(Collections.singletonList(disk));

  // Initialize the service account to be used by the VM Instance and set the API access scopes.
  ServiceAccount account = new ServiceAccount();
  account.setEmail("default");
  List<String> scopes = new ArrayList<>();
  scopes.add("https://www.googleapis.com/auth/devstorage.full_control");
  scopes.add("https://www.googleapis.com/auth/compute");
  account.setScopes(scopes);
  instance.setServiceAccounts(Collections.singletonList(account));

  // Optional - Add a startup script to be used by the VM Instance.
  Metadata meta = new Metadata();
  Metadata.Items item = new Metadata.Items();
  item.setKey("startup-script-url");
  // If you put a script called "vm-startup.sh" in this Google Cloud Storage
  // bucket, it will execute on VM startup.  This assumes you've created a
  // bucket named the same as your PROJECT_ID.
  // For info on creating buckets see: https://cloud.google.com/storage/docs/cloud-console#_creatingbuckets
  item.setValue("gs://" + PROJECT_ID + "/vm-startup.sh");
  meta.setItems(Collections.singletonList(item));
  instance.setMetadata(meta);

  System.out.println(instance.toPrettyString());
  Compute.Instances.Insert insert = compute.instances().insert(PROJECT_ID, ZONE_NAME, instance);
  return insert.execute();
}

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 で書かれたポーリングの例を示します。

Python

compute/api/create_instance.py

GitHub で表示

def wait_for_operation(compute, project, zone, operation):
    print('Waiting for operation to finish...')
    while True:
        result = compute.zoneOperations().get(
            project=project,
            zone=zone,
            operation=operation).execute()

        if result['status'] == 'DONE':
            print("done.")
            if 'error' in result:
                raise Exception(result['error'])
            return result

        time.sleep(1)

Java

compute/cmdline/src/main/java/ComputeEngineSample.java

GitHub で表示

/**
 * Wait until {@code operation} is completed.
 * @param compute the {@code Compute} object
 * @param operation the operation returned by the original request
 * @param timeout the timeout, in millis
 * @return the error, if any, else {@code null} if there was no error
 * @throws InterruptedException if we timed out waiting for the operation to complete
 * @throws IOException if we had trouble connecting
 */
public static Operation.Error blockUntilComplete(
    Compute compute, Operation operation, long timeout) throws Exception {
  long start = System.currentTimeMillis();
  final long pollInterval = 5 * 1000;
  String zone = operation.getZone();  // null for global/regional operations
  if (zone != null) {
    String[] bits = zone.split("/");
    zone = bits[bits.length - 1];
  }
  String status = operation.getStatus();
  String opId = operation.getName();
  while (operation != null && !status.equals("DONE")) {
    Thread.sleep(pollInterval);
    long elapsed = System.currentTimeMillis() - start;
    if (elapsed >= timeout) {
      throw new InterruptedException("Timed out waiting for operation to complete");
    }
    System.out.println("waiting...");
    if (zone != null) {
      Compute.ZoneOperations.Get get = compute.zoneOperations().get(PROJECT_ID, zone, opId);
      operation = get.execute();
    } else {
      Compute.GlobalOperations.Get get = compute.globalOperations().get(PROJECT_ID, opId);
      operation = get.execute();
    }
    if (operation != null) {
      status = operation.getStatus();
    }
  }
  return operation == null ? null : operation.getError();
}