View a markdown version of this page

查询 Amazon EC2 的请求 - Amazon Elastic Compute Cloud
GET 请求的结构查询参数查询 API 身份验证查询响应结构分页防止通过 HTTP 发送请求

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

查询 Amazon EC2 的请求

查询请求是使用 HTTP 动词 GET 或 POST 以及名为的查询参数的 HTTP 或 HTTPS 请求Action。对于每个 Amazon EC2 API 操作，您可以选择使用 GET 还是 POST。无论您选择哪个动词，都会发送和接收相同的数据。有关 Amazon EC2 API 操作的列表，请参阅操作。

GET 请求的结构

Amazon EC2 文档将 GET 请求以网址的形式呈现，可以直接在浏览器中使用。

注意

由于 GET 请求是 URL，因此您必须对参数值进行网址编码。在 Amazon EC2 文档中，我们未对示例 GET 请求进行编码，以便于阅读。

该请求包括以下内容：

  • 端点：用作 Web 服务入口点的 URL。有关更多信息，请参阅 Amazon EC2 服务终端节点。

  • 操作：您要执行的操作；例如，RunInstances用于启动实例。

  • 参数：操作的任何参数；每个参数用 & 符号 (&) 分隔。

  • 版本：要使用的 API 版本。对于亚马逊 EC2 API，版本为 2016-11-15。

  • 授权参数： AWS 用于确保请求有效性和真实性的授权参数。Amazon EC2 支持签名版本 2 和签名版本 4。我们建议您使用 Signature 版本 4。有关更多信息，请参阅 I AM 用户指南中的签署 AWS API 请求。

您的请求中可以包含以下可选参数：

  • DryRun：检查您是否拥有操作所需的权限，而无需实际发出请求。如果您拥有所需的权限，则请求会返回DryRunOperation；否则，它会返回UnauthorizedOperation。

  • SecurityToken：通过调用获得的临时安全令牌 AWS Security Token Service。

有关 API 请求的常用参数的更多信息，请参阅常用查询参数。

以下是启动实例的请求示例：

https://ec2.amazonaws.com/?Action=RunInstances&ImageId=ami-2bb65342&MaxCount=3&MinCount=1&Placement.AvailabilityZone=us-east-1a&Monitoring.Enabled=true&Version=2016-11-15&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIDEXAMPLE%2F20130813%2Fus-east-1%2Fec2%2Faws4_request&X-Amz-Date=20130813T150206Z&X-Amz-SignedHeaders=content-type%3Bhost%3Bx-amz-date&X-Amz-Signature=525d1a96c69b5549dd78dbbec8efe264102288b83ba87b7d58d4b76b71f59fd2
Content-type: application/json
host:ec2.amazonaws.com

为了使这些示例请求更易于阅读， AWS 文档可以采用以下格式呈现：

https://ec2.amazonaws.com/?Action=RunInstances
&ImageId=ami-2bb65342
&MaxCount=3
&MinCount=1
&Placement.AvailabilityZone=us-east-1a
&Monitoring.Enabled=true
&Version=2016-11-15
&X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=AKIAIOSFODNN7EXAMPLEus-east-1%2Fec2%2Faws4_request
&X-Amz-Date=20130813T150206Z
&X-Amz-SignedHeaders=content-type%3Bhost%3Bx-amz-date
&X-Amz-Signature=ced6826de92d2bdeed8f846f0bf508e8559e98e4b0194b84example54174deb456c
Content-type: application/json
host:ec2.amazonaws.com

第一行指定请求的端点。终端节点后是一个问号 (？)，将终端节点与参数隔开。有关亚马逊 EC2 终端节点的更多信息，请参阅亚马逊 EC2 服务终端节点。

Action 参数表示要执行的操作。有关操作的完整列表，请参阅操作。其余几行为请求指定了其他参数。

在 Amazon EC2 API 文档中提供的示例查询请求中，我们省略了标头、常用必需参数和身份验证参数，以便您可以更轻松地专注于操作的参数。我们将它们替换为&AUTHPARAMS文字字符串，以提醒您必须在请求中包含这些参数；例如：

https://ec2.amazonaws.com/?Action=RunInstances
&ImageId=ami-2bb65342
&MaxCount=3
&MinCount=1
&Placement.AvailabilityZone=us-east-1a
&Monitoring.Enabled=true
&AUTHPARAMS
重要

在为AWSAccessKeyId或Credential参数指定访问密钥 ID 之前，请查看并遵循AWS 安全证书中的指导。

查询参数

每个 Query 请求都必须包含处理身份验证和操作选择所需的常用参数。查询参数区分大小写。

有些操作会使用参数列表。这些列表是使用 param.n 表示法指定的，其中 n 是从 1 开始的整数。

以下示例使用BlockDeviceMapping参数列表将多个设备添加到块储存设备映射中。

http://ec2.amazonaws.com/?Action=RunInstances
&ImageId.1=ami-72aa081b
...
&BlockDeviceMapping.1.DeviceName=/dev/sdj
&BlockDeviceMapping.1.Ebs.NoDevice=true
&BlockDeviceMapping.2.DeviceName=/dev/sdh
&BlockDeviceMapping.2.Ebs.VolumeSize=300
&BlockDeviceMapping.3.DeviceName=/dev/sdc
&BlockDeviceMapping.3.VirtualName=ephemeral1
&AUTHPARAMS

查询 API 身份验证

您可以通过 HTTP 或 HTTPS 协议发送查询请求。

无论使用哪种协议，都必须在每个查询请求中包含签名。Amazon EC2 支持签名版本 2 和签名版本 4。我们建议您使用 Signature 版本 4。有关更多信息，请参阅 I AM 用户指南中的签署 AWS API 请求。

签名版本 4 请求允许您在单个标头中指定所有授权参数，例如：

Content-Type: application/x-www-form-urlencoded; charset=UTF-8
X-Amz-Date: 20130813T150211Z
Host: ec2.amazonaws.com
Authorization: AWS4-HMAC-SHA256 Credential=AKIDEXAMPLE/202230813/us-east-1/ec2/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature=ced6826de92d2bdeed8f846f0bf508e8559e98e4b0194b84example54174deb456c

http://ec2.amazonaws.com/?Action=RunInstances
ImageId=ami-2bb65342
&MaxCount=3
&MinCount=1
&Monitoring.Enabled=true
&Placement.AvailabilityZone=us-east-1a
&Version=2016-11-15

查询响应结构

作为对查询请求的响应，该服务会返回一个符合为 Amazon EC2 定义的 XML 架构的 XML 数据结构。XML 响应的结构特定于关联的请求。通常，响应数据类型是根据所执行的操作以及数据类型是否为容器（可以有子项）来命名的。容器的示例包括groupSet用于安全组和密钥对keySet的容器（参见以下示例）。项目元素是容器的子元素，其内容因容器的角色而异。

每个成功的响应在requestId元素中都包含一个请求 ID，每个失败的响应在RequestID元素中都包含一个请求 ID。该值是一个唯一的 AWS 赋值字符串。如果您在处理特定请求时遇到问题， AWS 将要求您提供请求编号以帮助解决问题。下面显示了一个示例响应。

<DescribeKeyPairsResponse xmlns="http://ec2.amazonaws.com/doc/2016-11-15/">
  <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId>
  <keySet>
    <item>
      <keyName>gsg-keypair</keyName>
      <keyFingerprint>
         00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00
      </keyFingerprint>
    </item>
  </keySet>
</DescribeKeyPairsResponse>
注意事项

  • 自 2024 年 7 月 31 日起，对于任何新的 Amazon EC2 API 操作或新支持的 AWS 区域，响应中的 XML 数据结构将不包含新行和缩进。如果您使用自定义客户端，请确保它不依赖于包括换行符和缩进在内的响应。

  • 自 2025 年 7 月 31 日起，回复中的 XML 数据结构将不再包含新行和缩进。此更改将减小响应的大小。如果您使用自定义客户端，请确保它不依赖于包括换行符和缩进在内的响应。

  • 响应中元素（包括嵌套结构中的元素）的顺序可能会有所不同。应用程序不应假设元素按特定顺序出现。

分页

对于可以返回一长串项目的操作，Amazon EC2 API 包含支持分页的参数：MaxResults、NextToken（输入）和nextToken（输出）。使用分页时，您可以为指定大小，MaxResults然后每次调用都会向MaxResults项目和集合nextToken返回 0。如果还有其他项目要迭代，nextToken则为非空，您可以在后续调用的NextToken参数中指定其值以获取下一组项目。使用分页时，即使您收到的项目少于MaxResults项（包括零项），您仍会继续调用该操作，直到nextToken为空。

如果您调用 describe API 操作，同时包含 ID 列表和MaxResults，则请求将失败并显示错误InvalidParameterCombination。

我们建议您在使用可能返回大量结果的描述操作时使用分页，例如DescribeInstances。使用分页限制返回的项目数量和这些调用返回所需的时间。

有关更多信息，请参阅 Amazon EC2 开发人员指南中的分页。

防止通过 HTTP 发送请求

如果您的工作负载不要求您使用 HTTP，我们建议您避免使用它来防止传输和接收未加密的数据，而是改用 HTTPS。您可以在 IAM 策略中使用aws:SecureTransport全局 IAM 条件密钥来防止用户通过 HTTP 发送请求。

以下示例策略禁止用户通过 HTTP 发送请求。

{
    "Statement": [
        {
            "Sid": "AllowAllEC2HttpsRequests",
            "Effect": "Allow",
            "Action": "ec2:*",
            "Resource": "*",
            "Condition": {
                "StringEqualsIgnoreCase": {
                    "aws:SecureTransport": "true"
                }
            }
        }
    ]
}