本文档描述如何构建 API 请求以及处理来自 Compute Engine API 的 API 响应。本文档介绍了如何执行以下操作:
- 构建请求正文。
- 确定请求所需的资源网址。
- 处理 API 响应。
- 确定 API 请求是否成功。
本文档未介绍如何向 API 进行身份验证。如需了解如何向 API 进行身份验证,请参阅向 Compute Engine 进行身份验证。
准备工作
创建 API 请求
Compute Engine API 要求 API 请求采用 JSON 格式。如需发出 API 请求,您可以使用 curl
或 httplib2
等工具发出直接 HTTP 请求,您也可以使用某个可用的客户端库。
当您发出需要请求正文的 API 请求(例如 POST
、UPDATE
或 PATCH
请求)时,请求正文包含您要在此请求中设置的资源属性。例如,以下 curl
命令向实例资源 URI 发出 POST
请求。该请求会创建一个具有请求正文中定义的属性的实例。请求正文由 -d
标志指示:
curl -X POST -H "Authorization: Bearer [OAUTH_TOKEN]" -H "Content-Type: application/json" https://compute.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-10-buster-v20210122" } } ], "machineType":"https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/e2-standard-2", "name":"VM_NAME", "networkInterfaces":[ { "accessConfigs":[ { "name":"external-nat", "type":"ONE_TO_ONE_NAT" } ], "network":"https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/default" } ] }'
映像 URI 的项目 ID (debian-cloud
) 与您的项目 ID 不同,这是因为映像属于不同的项目,具体取决于映像类型。例如,Compute Engine 提供的所有公开可用的 Debian 映像都托管在 debian-cloud
项目中。
引用其他资源时,请使用完全限定的资源 URI。例如,network
属性使用 default
网络的完全限定 URI。
API 请求示例
Python
Java
创建资源 URI
在 Compute Engine API 中,对另一个 Google Cloud 资源的引用以完全限定的 URI 形式提供:
https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/RESOURCE_TYPE/SPECIFIC_RESOURCE
每次您指定映像、机器类型、网络或任何其他资源,都必须在使用 API 时提供资源的 URI。Google Cloud CLI 和 Google Cloud 控制台等客户端工具可隐藏这种复杂性并为您创建这些资源 URI,但是在与 API 直接交互时,您必须自行创建这些资源 URI。
不同类型资源的资源 URI 略有不同。例如,可用区级资源在 URI 中具有 zone
规范:
https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/e2-standard-2
区域级资源将 zone
规范替换为 region
规范:
https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/addresses/ADDRESS_NAME
同样,全球性资源具有 global
规范:
https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/images/VM_NAME
Compute Engine API 也接受部分 URI,因为服务可以推断项目 ID 等信息。因此,早期 URI 的以下部分版本也是可以接受的:
zones/ZONE/machineTypes/e2-standard-2
regions/REGION/addresses/ADDRESS_NAME
project/PROJECT_ID/global/images/VM_NAME
在部分 URI 中,可用区 URI 和区域 URI 都省略了项目 ID,但映像 URI 未省略。这是因为 Compute Engine 提供的公开可用的映像托管在其他项目中,例如所有 Debian 映像都托管在 debian-cloud
,所有 Ubuntu 映像都托管在 ubuntu-os-cloud
。您需要提供适当的项目 ID 才能使用这些映像。如果您省略了映像的项目 ID,Compute Engine 会尝试在您的项目中查找该映像,由于映像不存在,请求会失败。
但是,如果您使用属于您的项目(您要在其中创建相应资源的项目)的自定义映像,则可以在提供映像 URI 时省略项目规范。
确定所需的属性
适用于 v1 和 Beta 版 API 的 Compute Engine API 参考文档介绍了您可以为特定资源设置的所有可能的属性。此参考文档区分了可变属性和不可变属性(在属性说明中用 [Output Only]
标记),但是如需确定资源所需的属性,您需要查看特定于该任务的文档。
例如,如果您要创建实例,请参阅从映像创建实例文档以查看请求所需的 API 属性。如果要在 API 中创建静态外部 IP 地址,请参阅静态外部 IP 地址文档。
验证 API 请求
如需验证您的 API 请求,请执行以下操作:
- 在 Compute Engine API 参考文档中,找到代码调用的方法。例如,
v1/compute.instances.insert
。 在内容菜单中,点击试试看!这会打开试用此 API 窗口。
在请求参数下,您无需提供项目或可用区,因为验证不需要提交请求。
在请求正文下,粘贴您的请求。
请求中格式错误的元素带有蓝色下划线。点击每个带下划线的部分,详细了解要解决的问题。
处理 API 响应
如果您发出更改(改动)数据的请求,Compute Engine 会返回一个 Operation
对象,然后您可以轮询该对象以获取请求的操作状态。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_VM", "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
或 wait
方法的请求并提供操作的 name
。
直到 Operation
资源的状态返回 DONE
时,您的请求才会完成。该过程可能需要一些时间,具体取决于请求的性质。然后,在 Operation
资源的状态返回 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://compute.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://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/EXAMPLE_VM user: user@example.com zone: https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE
若要确认这一点,请向资源发出 get
请求,以检查它是否存在且正在运行。例如:
GET /compute/v1/projects/PROJECT_ID/zones/ZONE/instances/EXAMPLE_VM { "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_VM", "status": "RUNNING", "tags": { "fingerprint": "42WmSpB8rSM=" }, "zone": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE" }
轮询操作
您可以编写一些代码来使用 get
或 wait
请求定期轮询操作,当操作状态为 DONE
时这些操作会返回。
使用 get
请求时,无论操作的状态是什么,它会立即返回操作。您需要定期轮询操作,以了解操作何时完成。
如果您发出 wait
请求,则当操作为 DONE
或请求接近 2 分钟时限时,该请求将返回。您可以选择使用 wait
或 get
来轮询操作,但与 get
方法相比,wait
方法具有以下某些优势:
- 您可以将客户端设置为以较低的频率轮询操作状态,从而减少 Compute Engine API 的 QPS 用量。
- 操作完成与客户端收到操作完成的通知之间的平均延迟时间会显著缩短,因为服务器在操作完成后会立即做出响应。
- 该方法的等待时间有界限。该方法等待的时间不会超过默认 HTTP 超时(2 分钟),然后返回操作的当前状态,该状态可能是
DONE
或仍在进行中。
wait
方法是尽力而为 API。如果服务器过载,则请求可能会在达到默认时限之前或等待零秒后返回。此方法也不保证仅在操作为 DONE
时返回。例如,如果请求接近 2 分钟时限,则即使操作尚未完成,该方法也会返回。如需检查操作,我们建议您使用 wait
或 get
方法(在中间存在休眠的重试循环中)定期轮询操作状态。重试间隔时间上限不应超过最短操作保留期限。
示例轮询
以下示例使用 get
方法。您可以将 get
方法替换为 wait
方法: