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

# 使用查询 API
<a name="programmingguide.queryapi"></a>

## 查询参数
<a name="query-parameters"></a>

HTTP 基于查询的请求是指使用 HTTP 动作 GET 或 POST 的 HTTP 请求，查询参数的名称为 `Action`。

每个查询请求必须包括一些通用参数，以处理操作的身份验证和选择事宜。

有些操作会使用参数列表。这些列表都是使用 `param.n` 表示法指定的。*n* 值是从 1 开始的整数。

## 查询请求身份验证
<a name="query-authentication"></a>

您只可以通过 HTTP 发送查询请求，并且每个查询请求中必须包含您的签名。本部分描述了如何创建签名。以下过程中说明的方法称为*签名版本 4*。

下面介绍了对发送至 AWS 的请求进行身份验证的基本步骤。其中假定您注册了 AWS，并且有一个访问密钥 ID 和秘密访问密钥。

**查询身份验证流程**

1. 发件人构建一个将要发送至 AWS 的请求。

1. 发件人计算请求签名，即带有一个 SHA-1 哈希函数的键控式哈希信息验证码（HMAC），如本主题下一部分中所定义的那样。

1. 该请求的发件人将请求数据、签名和访问密钥 ID（即所使用的秘密访问密钥的密钥标识符）发送至 AWS。

1. AWS 使用访问密钥 ID 来查询秘密访问密钥。

1. AWS 使用与计算请求中签名所用的相同算法根据请求数据和秘密访问密钥生成一个签名。

1. 如果签名匹配，那么请求将被视为可信。如果比较签名这一操作失败，那么请求将被丢弃，同时 AWS 将返回错误响应。

**注意**  
如果请求包含一个 `Timestamp` 参数，那么针对请求计算的签名将在被赋予值后的 15 分钟失效。  
如果请求包含一个 `Expires` 参数，那么签名将在 `Expires` 参数指定的时间失效。

**计算请求签名**

1. 创建标准化的查询字符串，您在此过程的稍后部分需要用到它：

   1. 根据参数名称、按照自然字节排序对 UTF-8 查询字符串组成部分进行分类。参数可取自 GET URI 或 POST 正文（当内容类型为 application/x-www-form-urlencoded 时）。

   1. URL 根据以下规则对参数名称和值进行编码：

      1. 不对任何由 RFC 3986 定义的非预留字符进行 URL 编码。这些未预留字符是 A–Z、a–z、0–9、连字符（-）、下划线（\$1）、句点（.）和波形符（\$1）。

      1. 使用 %XY 对所有其他参数进行百分比编码，其中“X”和“Y”分别代表十六进制字符 0-9 和大写字母 A-F。

      1. 以 %XY%ZA... 格式对扩展的 UTF-8 字符进行百分号编码。

      1. 将空白字符百分号编码为 %20（不是普通编码方案中的 \$1）。

   1. 使用等号（ = ）（ASCII 字符 61）将编码的参数名称与它们的编码值分隔开，即使参数值为空，亦应如此。

   1. 使用“和”符号（&）（ASCII 代码 38）隔开名称/值对。

1. 依照下列伪语法创建用以签名的字符串（“\$1n”代表 ASCII 换行）。

   ```
   StringToSign = HTTPVerb + "\n" +
   ValueOfHostHeaderInLowercase + "\n" +
   HTTPRequestURI + "\n" +
   CanonicalizedQueryString <from the preceding step>
   ```

   HTTPRequestURI 组件是 URI 的 HTTP 绝对路径组件，但不包括查询字符串。如果 HTTPRequestURI 为空，则使用正斜杠（ / ）。

1. 利用您刚创建的字符串计算符合 RFC 2104 的 HMAC，将您的秘密访问密钥当作密钥，并将 SHA256 或 SHA1 作为哈希算法。

   有关更多信息，请参阅 [https://www.ietf.org/rfc/rfc2104.txt](https://www.ietf.org/rfc/rfc2104.txt)。

1. 将结果值转换为 base64。

1. 将此值作为请求中的 `Signature` 参数值。

例如，下面是一个示例请求（为清晰起见，添加了换行符）。

```
https://memory-db.us-east-1.amazonaws.com/
    ?Action=DescribeClusters
    &ClusterName=myCluster
    &SignatureMethod=HmacSHA256
    &SignatureVersion=4
    &Version=2021-01-01
```

对于前述的查询字符串，您将要计算下述字符串的 HMAC 签名。

```
GET\n
    memory-db.amazonaws.com\n
    Action=DescribeClusters
    &ClusterName=myCluster
    &SignatureMethod=HmacSHA256
    &SignatureVersion=4
    &Version=2021-01-01
    &X-Amz-Algorithm=Amazon4-HMAC-SHA256
    &X-Amz-Credential=AKIADQKE4SARGYLE%2F20140523%2Fus-east-1%2Fmemorydb%2Faws4_request
    &X-Amz-Date=20210801T223649Z
    &X-Amz-SignedHeaders=content-type%3Bhost%3Buser-agent%3Bx-amz-content-sha256%3Bx-amz-date
        content-type:
        host:memory-db.us-east-1.amazonaws.com
        user-agent:ServicesAPICommand_Client
    x-amz-content-sha256:
    x-amz-date:
```

结果是下面的已签名请求。

```
https://memory-db.us-east-1.amazonaws.com/
    ?Action=DescribeClusters
    &ClusterName=myCluster
    &SignatureMethod=HmacSHA256
    &SignatureVersion=4
    &Version=2021-01-01
    &X-Amz-Algorithm=Amazon4-HMAC-SHA256
    &X-Amz-Credential=AKIADQKE4SARGYLE/20141201/us-east-1/memorydb/aws4_request
    &X-Amz-Date=20210801T223649Z
    &X-Amz-SignedHeaders=content-type;host;user-agent;x-amz-content-sha256;x-amz-date
    &X-Amz-Signature=2877960fced9040b41b4feaca835fd5cfeb9264f768e6a0236c9143f915ffa56
```

有关签名流程和计算请求签名的详细信息，请参阅主题[签名版本 4 签名流程](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html)及其副主题。