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

# 向 Amazon SWF 发出 HTTP 请求
<a name="UsingJSON-swf"></a>

如果您不使用其中一个 AWS SDKs，则可以使用 POST 请求方法通过 HTTP 执行亚马逊简单工作流服务 (Amazon SWF) 操作。POST 方法要求您在请求标头中指定操作并在请求正文中以 JSON 格式提供操作数据。

## HTTP 标头内容
<a name="HTTPHeader"></a>

Amazon SWF 要求在 HTTP 请求标头中包含以下信息：
+ `host` Amazon SWF 端点。
+ `x-amz-date`您必须在 HTTP `Date` 标头或 AWS `x-amz-date header`（某些 HTTP 客户端库不允许您设置`Date`标头）中提供时间戳。当 `x-amz-date` 标头呈现时，系统在验证请求身份时会忽略任何 `Date` 标头。

  必须利用以下三种格式中的一种来指定数据，如 HTTP/1.1 RFC 中所规定：
  + 格林威治时间 1994 年 11 月 6 日，星期日 08:49:37（RFC 822，由 RFC 1123 更新）
  + 格林威治时间 1994 年 11 月 6 日，星期日 08:49:37（RFC 850，由 RFC 1036 废弃）
  + 1994 年 11 月 6 日 08:49:37，星期日（ANSI C 的 asctime() 格式）
+ `x-amzn-authorization`已签名的请求参数格式如下：

  ```
  AWS3 AWSAccessKeyId=####,Algorithm=HmacSHA256, [,SignedHeaders=Header1;Header2;...]
  Signature=S(StringToSign)
  ```

  `AWS3`— 这是一个 AWS 特定于实现的标签，表示用于签署请求的身份验证版本（目前，对于 Amazon SWF，此值始终为）。`AWS3`

  `AWSAccessKeyId`— 您的 AWS 访问密钥 ID。

  `Algorithm`— 用于创建的 HMAC-SHA 值的算法 string-to-sign，例如或。`HmacSHA256` `HmacSHA1`

  `Signature`— Base64（算法 ( StringToSign, SigningKey )）。有关详细信息，请参阅 [计算 Amazon SWF 的 HMAC-SHA 签名](HMACAuth-swf.md)

  `SignedHeaders`—（可选）如果存在，则必须包含规范 HttpHeaders 化计算中使用的所有 HTTP 标头的列表。必须用一个分号字符 (;)（ASCII 字符 59）分隔列表值。
+  `x-amz-target` – 请求的目标服务和数据操作，格式如下：

  ` com.amazonaws.swf.service.model.SimpleWorkflowService. + <action> `

   例如，`com.amazonaws.swf.service.model.SimpleWorkflowService.RegisterDomain`
+ `content-type` – 类型需要将 JSON 和字符集指定为 `application/json; charset=UTF-8`

 以下示例为创建域所用的 HTTP 请求的标头。

```
POST http://swf.us-east-1.amazonaws.com/ HTTP/1.1
Host: swf.us-east-1.amazonaws.com
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 6.1; en-US; rv:1.9.2.25) Gecko/20111212 Firefox/3.6.25 ( .NET CLR 3.5.30729; .NET4.0E)
Accept: application/json, text/javascript, */*
Accept-Language: en-us,en;q=0.5
Accept-Encoding: gzip,deflate
Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7
Keep-Alive: 115
Connection: keep-alive
Content-Type: application/json; charset=UTF-8
X-Requested-With: XMLHttpRequest
X-Amz-Date: Fri, 13 Jan 2012 18:42:12 GMT
X-Amz-Target: com.amazonaws.swf.service.model.SimpleWorkflowService.RegisterDomain
Content-Encoding: amz-1.0
X-Amzn-Authorization: AWS3 AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE,Algorithm=HmacSHA256,SignedHeaders=Host;X-Amz-Date;X-Amz-Target;Content-Encoding,Signature=tzjkF55lxAxPhzp/BRGFYQRQRq6CqrM254dTDE/EncI=
Referer: http://swf.us-east-1.amazonaws.com/explorer/index.html
Content-Length: 91
Pragma: no-cache
Cache-Control: no-cache

{"name": "867530902",
 "description": "music",
 "workflowExecutionRetentionPeriodInDays": "60"}
```

此处为对应 HTTP 响应的示例。

```
HTTP/1.1 200 OK
Content-Length: 0
Content-Type: application/json
x-amzn-RequestId: 4ec4ac3f-3e16-11e1-9b11-7182192d0b57
```

## HTTP 正文内容
<a name="JSONschema"></a>

HTTP 请求的正文包含 HTTP 请求标头中指定的操作数据。使用 JSON 数据格式可以同时传递数据值和数据结构。元素可通过括号嵌套在其它元素内。例如，下面显示了一个请求，该请求使用 Unix 时间注释列出在两个指定时间点之间开始的所有工作流执行。

```
{
 "domain": "867530901",
 "startTimeFilter":
 {
   "oldestDate": 1325376070,
	 "latestDate": 1356998399
 },
 "tagFilter":
 {
   "tag": "music purchase"
 }
}
```

## Amazon SWF JSON 请求和响应示例
<a name="JSONMajorExample"></a>

下面的示例显示了一个对 Amazon SWF 的请求，用于获取对我们在前面创建的域的描述。然后，它显示了 Amazon SWF 响应。

### HTTP POST 请求
<a name="http-post-request"></a>

```
POST http://swf.us-east-1.amazonaws.com/ HTTP/1.1
Host: swf.us-east-1.amazonaws.com
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 6.1; en-US; rv:1.9.2.25) Gecko/20111212 Firefox/3.6.25 ( .NET CLR 3.5.30729; .NET4.0E)
Accept: application/json, text/javascript, */*
Accept-Language: en-us,en;q=0.5
Accept-Encoding: gzip,deflate
Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7
Keep-Alive: 115
Connection: keep-alive
Content-Type: application/json; charset=UTF-8
X-Requested-With: XMLHttpRequest
X-Amz-Date: Sun, 15 Jan 2012 03:13:33 GMT
X-Amz-Target: com.amazonaws.swf.service.model.SimpleWorkflowService.DescribeDomain
Content-Encoding: amz-1.0
X-Amzn-Authorization: AWS3 AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE,Algorithm=HmacSHA256,SignedHeaders=Host;X-Amz-Date;X-Amz-Target;Content-Encoding,Signature=IFJtq3M366CHqMlTpyqYqd9z0ChCoKDC5SCJBsLifu4=
Referer: http://swf.us-east-1.amazonaws.com/explorer/index.html
Content-Length: 21
Pragma: no-cache
Cache-Control: no-cache

{"name": "867530901"}
```

### Amazon SWF 响应
<a name="swf-response"></a>

```
HTTP/1.1 200 OK
Content-Length: 137
Content-Type: application/json
x-amzn-RequestId: e86a6779-3f26-11e1-9a27-0760db01a4a8

{"configuration":
  {"workflowExecutionRetentionPeriodInDays": "60"},
 "domainInfo":
  {"description": "music",
   "name": "867530901",
   "status": "REGISTERED"}
}
```

注意协议 (`HTTP/1.1`) 后面有一个状态代码 (`200`)。`200` 的代码值表示操作成功。

Amazon SWF 不对空值执行序列化操作。如果您的 JSON 分析程序设置为对请求的空值执行序列化，则 Amazon SWF 会忽略这些值。

# 计算 Amazon SWF 的 HMAC-SHA 签名
<a name="HMACAuth-swf"></a>

发给 Amazon SWF 的每个请求都必须进行身份验证。会 AWS SDKs 自动签署您的请求并管理基于令牌的身份验证。但是，如果要写入自己的 HTTP `POST` 请求，在对请求进行身份验证时，您需要为 HTTP `POST Header` 内容创建 `x-amzn-authorization` 值。

有关对标头进行格式设置的详细信息，请参阅 [HTTP 标头内容](UsingJSON-swf.md#HTTPHeader)。有关 AWS 版本 3 签名的 适用于 Java 的 AWS SDK 实现，请参阅 [ AWSSigner.java](https://github.com/aws/aws-sdk-java/blob/master/aws-java-sdk-core/src/main/java/com/amazonaws/auth/AWS3Signer.java) 类。

## 创建请求签名
<a name="AuthProcess"></a>

在创建 HMAC-SHA 请求签名之前，必须获取 AWS 凭证（访问密钥 ID 和私有密钥）。

**重要**  
您可以使用 SHA1 或 SHA256 来签署您的请求。但是，请务必在整个签名过程中使用同一方法。您选择的方法必须与 HTTP 标头中的 `Algorithm` 名称的值匹配。

### 创建请求签名
<a name="swf-create-request-signature-steps"></a>

1. 创建一个标准化的 HTTP 请求标头。HTTP 标头规范形式包括以下内容：
   + `host`
   + 以 `x-amz-` 为开头的任何标头元素

   有关所包含的标头的详细信息，请参阅 [HTTP 标头内容](UsingJSON-swf.md#HTTPHeader)。

   1. 对于每一个标头名值对，将标头名称转换为小写字母 (但不是标头值)。

   1. 将标头名称映射到逗号分隔的标头值。

      ```
      x-amz-example: value1
      x-amz-example: value2  =>  x-amz-example:value1,value2
      ```

      有关更多信息，请参阅 [RFC 2616 的第 4.2 节](http://tools.ietf.org/html/rfc2616)。

   1. 对于每个标头名称-值对，将其转换成 `headerName:headerValue` 格式的字符串。从 `headerName` 和 `headerValue` 的开头和结尾删除所有空白，冒号两边不留空格。

      ```
      x-amz-example1:value1,value2
      x-amz-example2:value3
      ```

   1. 在转换好的每一个字符串 (包括最后一个字符串) 后插入一个换行符 (`U+000A`)。

   1. 按照字母顺序用标头名称给转换好的字符串集合分类。

1. 创建包含以下项目的 string-to-sign值：
   + 第 `1` 行：HTTP 方法 (`POST`)，其后是换行符。
   + 第 `2` 行：请求 URI (`/`)，其后是换行符。
   + 第 `3` 行：空字符串，其后是换行符。
**注意**  
通常，这里会显示查询字符串，但 Amazon SWF 不使用查询字符串。
   + 第 `4–n` 行：表示步骤 1 中计算的规范请求标头的字符串，后跟换行符。该换行符在 HTTP 请求的标头与正文之间创建一个空白行。有关更多信息，请参见 [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html)。
   + 请求正文，*不* 跟换行符。

1. 计算 string-to-sign值的 SHA256 或 SHA1 摘要。在整个过程中采用同一种 SHA 方法。

1. 使用 API 操作使用上一步生成的值和来自 AWS 安全令牌服务的临时私有访问密钥的 SHA1 摘要（取决于您使用的方法）计算并对 HMAC-SHA 进行编码。 SHA256 `[GetSessionToken](https://docs.aws.amazon.com/STS/latest/UsingSTS/CreatingSessionTokens.html)`
**注意**  
Amazon SWF 希望在进行 Base64 编码的 HMAC-SHA 值末尾添加一个等号 (`=`)。如果 Base64 编码程序不包括附加等号，请在值的结尾附加一个等号。

   有关在 Amazon SWF 和其他 AWS 服务中使用临时安全证书的更多信息，请参阅 IAM *用户*指南中的[与 IAM 配合使用的AWS 服务](https://docs.aws.amazon.com/STS/latest/UsingSTS/UsingTokens.html)。

1. 将生成的值作为 `Signature` 名称的值放入向 Amazon SWF 发送的 HTTP 请求的 `x-amzn-authorization` 标头中。

1. Amazon SWF 会验证该请求并执行指定操作。