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

# 使用适用于 Amazon EC2 的 API
<a name="ec2-low-level-api"></a>

**重要**  
自 **2022 年 10 月 14 日**起，来自亚马逊 EC2 API 的 HTTP 响应不再包含理由短语元素。按照 [RFC7230](https://datatracker.ietf.org/doc/html/rfc7230#section-3.1.2) 的建议，您应确保您的应用程序不使用推理短语内容。确保您的应用程序改用 HTTP 响应中包含的 3 位数状态码元素。

我们提供适用于 Amazon EC2 的查询 API 以及软件开发套件 (SDK) AWS ，使您能够使用自己的首选编程语言访问 Amazon EC2。有关更多信息，请参阅 [Amazon EC2 开发人员指南](https://docs.aws.amazon.com/ec2/latest/devguide/)。

**Topics**
+ [所需知识](#required-knowledge)
+ [适用于 Amazon EC2 的可用API](#using-libraries)
+ [按服务划分的操作](OperationList-query.md)
+ [查询请求](Query-Requests.md)
+ [跨域资源共享支持](cors-support.md)
+ [VM Import 清单](manifest.md)
+ [常用查询参数](#CommonParameters)
+ [Permissions](ec2-api-permissions.md)
+ [对 API 请求错误进行故障排除](query-api-troubleshooting.md)
+ [错误代码](errors-overview.md)

## 所需知识
<a name="required-knowledge"></a>

如果您计划通过 API 访问 Amazon EC2，则应熟悉以下内容：
+ XML
+ Web 服务
+ HTTP 请求
+ 一种或多种编程语言，例如 Java、PHP、Perl、Python、Ruby、C\# 或 C\+\+。

## 适用于 Amazon EC2 的可用API
<a name="using-libraries"></a>

Amazon EC2 查询 API 提供使用 HTTP 动词 GET 或 POST 以及名为的查询参数的 HTTP 或 HTTPS 请求`Action`。

AWS 为喜欢使用特定语言的 API 而不是通过 HTTP 或 HTTPS 提交请求的软件开发人员提供库、示例代码、教程和其他资源。这些库提供了一些基本功能，可以自动处理诸如对请求进行加密签名、重试请求和处理错误响应之类的任务，因此您可以更轻松地入门。

有关更多信息，请参阅 [Amazon EC2 *开发人员指南中的使用软件开发 AWS 工具包创建 Amazon EC2* 资源](https://docs.aws.amazon.com/ec2/latest/devguide/sdk-general-information-section.html)。

## 常用查询参数
<a name="CommonParameters"></a>

大多数 Amazon EC2 API 操作都支持下表中描述的参数。根据您使用的是签名版本 2 还是签名版本 4 来签署请求，常见参数会有所不同。有关更多信息，请参阅 I *AM 用户指南*中的[签署 AWS API 请求](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html)。

**Topics**
+ [签名版本 4 的参数](#common-parameters-sigv4)
+ [签名版本 2 的参数](#common-parameters-sigv2)

### 签名版本 4 的参数
<a name="common-parameters-sigv4"></a>


| Name | 说明 | 必填 | 
| --- | --- | --- | 
|  `Action`  | 要执行的操作。<br />示例：`RunInstances` | 是 | 
|  `Version`  | 要使用的 API 版本。 | 是 | 
|  `X-Amz-Algorithm`  | 用于创建请求签名的哈希算法。<br />示例：`AWS4-HMAC-SHA256` | 是 | 
|  `X-Amz-Credential`  | 请求的凭证范围，格式为{{access-key-ID}}/{{YYYYMMDD}}/{{region}}/{{service}}`aws4_request`<br />示例：`AKIDEXAMPLE/20140707/us-east-1/ec2/aws4_request` | 是 | 
|  `X-Amz-Date`  | 签署请求的日期和时间，格式为 yyymmddthhmmssZ。该日期必须与`X-Amz-Credential`参数凭证范围中包含的日期或`Authorization`标题中使用的日期相匹配（参见表格下方的注释）。<br />示例：`20140707T150456Z` | 是 | 
| X-Amz-SignedHeaders | 您在请求中包含的标头。您必须至少包括标`host`题。如果您在请求中包含`x-amz-date`标头，则必须将其包含在已签名的标头列表中。<br />示例：`content-type;host;user-agent` | 是 | 
|  `X-Amz-Signature`  | 从您的私有访问密钥派生的签名。<br />示例：`ced6826de92d2bdeed8f846f0bf508e8559example` | 是 | 
|  `X-Amz-Security-Token`  | 通过调用获得的临时安全令牌 AWS Security Token Service。<br />示例：`AQoEXAMPLEH4aoAH0gNCAPyJxz4BlCFFxWNE1OPTgk5TthT+FvwqnKwRcOIfrRh3c/L` | 否 | 
|  `DryRun`  | 检查您是否拥有操作所需的权限，而无需实际发出请求。如果您拥有所需的权限，则请求会返回`DryRunOperation`；否则，它会返回`UnauthorizedOperation`。 | 否 | 

`X-Amz-Algorithm`、`X-Amz-Credential``X-Amz-SignedHeaders`、和`X-Amz-Signature`参数既可以在查询字符串中指定为单独的参数，也可以将其值包含在单个`Authorization`标题中。有关更多信息，请参阅 I *AM 用户指南*中的[签署 AWS API 请求](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html)。

### 签名版本 2 的参数
<a name="common-parameters-sigv2"></a>


| Name | 说明 | 必填 | 
| --- | --- | --- | 
|  `Action`  | 要执行的操作。<br />示例：`RunInstances` | 是 | 
|  `Version`  | 要使用的 API 版本。 | 是 | 
|  `AWSAccessKeyId`  | 请求发送者的访问密钥 ID。这标识了将为使用该服务而收取费用的账户。与访问密钥 ID 关联的账户必须注册 Amazon EC2，否则该请求将不被接受。<br /> 示例：`AKIAIOSFODNN7EXAMPLE` | 是 | 
|  `Expires`  | 请求中包含的签名到期的日期和时间，格式为 YYYY-MM-DDThh:mm:ssZ。有关更多信息，请参阅 [ISO 8601](http://www.w3.org/TR/NOTE-datetime)。<br />示例：`2006-07-07T15:04:56Z` | 这是有条件的。请求必须包含Timestamp或之一Expires，但不能同时包含两者。 | 
|  `Timestamp`  | 签署请求的日期和时间，格式为 YYYY-MM-DDThh:mm:ssZ。有关更多信息，请参阅 [ISO 8601](http://www.w3.org/TR/NOTE-datetime)。<br />示例：`2006-07-07T15:04:56Z` | 这是有条件的。请求必须包含Timestamp或之一Expires，但不能同时包含两者。 | 
|  `Signature`  | 请求签名。<br />示例：`Qnpl4Qk/7tINHzfXCiT7VEXAMPLE` | 是 | 
|  `SignatureMethod`  | 用于创建请求签名的哈希算法。有效值：`HmacSHA256` \| `HmacSHA1`。<br />示例：`HmacSHA256` | 是 | 
|  `SignatureVersion`  | 对请求进行签名时使用的签名版本。将此值设置为 `2`。<br />示例：`2` | 是 | 
|  `DryRun`  | 检查您是否拥有操作所需的权限，而无需实际发出请求。如果您拥有所需的权限，则请求会返回`DryRunOperation`；否则，它会返回`UnauthorizedOperation`。 | 否 | 
|  `SecurityToken`  | 通过调用获得的临时安全令牌 AWS Security Token Service。<br />示例：`AQoEXAMPLEH4aoAH0gNCAPyJxz4BlCFFxWNE1OPTgk5TthT+FvwqnKwRcOIfrRh3c/L` | 否 | 

参数值必须为 URL-encoded。对于传递给 Amazon EC2 的任何查询参数，这都是如此，`Signature`参数中通常是必需的。有些客户会自动执行此操作，但这不是常态。