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

# 使用查询 API
<a name="ProgrammingGuide.QueryAPI"></a>

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

HTTP Query-based 请求是使用 HTTP 动词 GET 或 POST 以及名为的查询参数的 HTTP 请求`Action`。

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

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

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

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

下面介绍了对发送至 AWS的请求进行身份验证的基本步骤。这假设您已注册 AWS 并拥有访问密钥 ID 和私有访问密钥。

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

1. 发件人向构造一个请求。 AWS

1. 发送方计算请求签名，即带有 SHA-1 哈希函数的 Hash-based 消息身份验证码 (HMAC)，如本主题下一节所定义。 Keyed-Hashing 

1. 请求的发送者将请求数据、签名和访问密钥 ID（所使用的私有访问密钥的密钥标识符）发送到。 AWS

1. AWS 使用访问密钥 ID 来查找私有访问密钥。

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

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

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

**计算请求签名**

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

   1. 按参数名称按自然字节顺序对 UTF-8 查询字符串组件进行排序。参数可以来自 GET URI 或 POST 正文（何时 Content-Type 是 application/x-www-form-urlencoded）。

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

      1. 不对任何由 RFC 3986 定义的非预留字符进行 URL 编码。这些非保留字符是 a-z A-Z、0-9、连字符 (-)、下划线 (\_)、句点 (.) 和波浪号 (\~)。

      1. 用 %XY 对所有其他字符进行百分比编码，其中 X 和 Y 是十六进制字符 0-9 和大写。 A-F

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

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

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

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

1. 依照下列伪语法创建用以签名的字符串（“\\n”代表 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://elasticache.us-west-2.amazonaws.com/
    ?Action=DescribeCacheClusters
    &CacheClusterIdentifier=myCacheCluster
    &SignatureMethod=HmacSHA256
    &SignatureVersion=4
    &Version=2014-12-01
```

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

```
GET\n
    elasticache.amazonaws.com\n
    Action=DescribeCacheClusters
    &CacheClusterIdentifier=myCacheCluster
    &SignatureMethod=HmacSHA256
    &SignatureVersion=4
    &Version=2014-12-01
    &X-Amz-Algorithm=&AWS;4-HMAC-SHA256
    &X-Amz-Credential=AKIADQKE4SARGYLE%2F20140523%2Fus-west-2%2Felasticache%2Faws4_request
    &X-Amz-Date=20141201T223649Z
    &X-Amz-SignedHeaders=content-type%3Bhost%3Buser-agent%3Bx-amz-content-sha256%3Bx-amz-date
        content-type:
        host:elasticache.us-west-2.amazonaws.com
        user-agent:CacheServicesAPICommand_Client
    x-amz-content-sha256:
    x-amz-date:
```

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

```
https://elasticache.us-west-2.amazonaws.com/
    ?Action=DescribeCacheClusters
    &CacheClusterIdentifier=myCacheCluster
    &SignatureMethod=HmacSHA256
    &SignatureVersion=4
    &Version=2014-12-01
    &X-Amz-Algorithm=&AWS;4-HMAC-SHA256
    &X-Amz-Credential=AKIADQKE4SARGYLE/20141201/us-west-2/elasticache/aws4_request
    &X-Amz-Date=20141201T223649Z
    &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)及其副主题。