创建 API 请求和处理响应

本文档描述如何构建 API 请求以及处理来自 Compute Engine API 的 API 响应。本文档介绍了如何执行以下操作：

  • 构建请求正文。
  • 确定请求所需的资源网址。
  • 处理 API 响应。
  • 确定 API 请求是否成功。

本文档未介绍如何向 API 提供授权。要了解如何向 API 提供授权，请参阅给请求授权。

准备工作

构建 API 请求

Compute Engine API 要求 API 请求采用 JSON 格式。若要发出 API 请求，您可以使用 curl 或 httplib2 等工具发出直接 HTTP 请求，也可以使用一个可用客户端库。

当您发出的 API 请求需要请求正文时，例如 POST、UPDATE 或 PATCH 请求，请求正文将包含您要在此请求中设置的资源属性。例如，以下 curl 命令向实例资源 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 
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 
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

区域资源用 region 规范替换 zone 规范：

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 参考文档介绍了您可以为特定资源设置的所有可能属性。参考文档区分了可变属性和不可变属性（在属性说明中用 [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 资源发出 GET 请求并提供操作的 name 来获取操作的状态。

直到 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 
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 
/**
 * 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();
}