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

# 使用 Step Functions 创建 API 网关 REST APIs
<a name="connect-api-gateway"></a>

学习如何使用 Amazon API Gateway 通过 Step Functions 创建、发布、维护和监控 HTTP 和 REST APIs 。要与 API Gateway 集成，您可以在步骤功能中定义一个 `Task` 状态，直接调用 API Gateway HTTP 或 API Gateway REST 端点，而无需编写代码或依赖其他基础架构。`Task` 状态定义包括 API 调用的所有必要信息。您也可以选择不同的授权方法。

要了解如何在 Step Functions 中与 AWS 服务集成，请参阅[集成 服务](integrate-services.md)和[在 Step Functions 中将参数传递给服务 API](connect-parameters.md)。

**经优化的 API Gateway 集成的主要功能**  
`apigateway:invoke:`在 AWS SDK 服务集成中没有等效项。相反，优化的 API Gateway 服务可以直接调用您的 API Gateway 端点。

## API Gateway 特征支持
<a name="connect-api-gateway-support"></a>

Step Functions API Gateway 集成支持部分 API 特征，而非全部。有关支持特征的详细信息，请参阅以下内容。
+ Step Functions API Gateway REST API 和 API Gateway HTTP API 集成都支持：
  + **授权方**：IAM（使用[签名版本 4](https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html)）、No Auth、Lambda 授权方（基于请求参数和基于令牌，带有自定义标头）
  + **API 类型**：区域性
  + **API 管理**：API Gateway API 域名、API 阶段、路径、查询参数、请求正文
+ 由 Step Functions API Gateway HTTP API 集成支持。不支持提供边缘优化选项的 Step Functions API Gate APIs way REST API 集成。
+ Step Functions API Gateway 集成不支持：
  +  **授权方**：亚马逊 Cognito、Native Open ID Connect OAuth /2.0、基于令牌的 Lambda 授权者的授权标头 
  +  **API 类型**：私有 
  +  **API 管理**：自定义域名 

有关 API Gateway 及其 HTTP 和 REST 的更多信息 APIs，请参阅以下内容。
+  [Amazon API Gateway 概念](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-basic-concept.html)页面。
+  在 API Gateway 开发者指南 APIs中在 [HTTP APIs 和 REST 之间进行选择](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-vs-rest.html)。

## 请求格式
<a name="connect-api-gateway-requests"></a>

在创建 `Task` 状态定义时，Step Functions 会验证参数，构建执行调用所需的 URL，然后调用 API。响应包括 HTTP 状态代码、标头和响应正文。请求格式包括必需和可选参数。

### 必需请求参数
<a name="connect-api-gateway-requests-required"></a>
+ `ApiEndpoint`
  + 类型：`String`
  + API Gateway URL 的主机名。格式为 `<API ID>.execute-api.region.amazonaws.com`。

    API ID 只能包含以下字母数字字符的组合：`0123456789abcdefghijklmnopqrstuvwxyz`
+ `Method`
  + 类型：`Enum`
  + HTTP 方法，必须是以下方法之一：
    + `GET`
    + `POST`
    + `PUT`
    + `DELETE`
    + `PATCH`
    + `HEAD`
    + `OPTIONS`

### 可选请求参数
<a name="connect-api-gateway-requests-optional"></a>
+ `Headers`
  + 类型：`JSON`
  + HTTP 标头允许列出与同一密钥关联的值。
+ `Stage`
  + 类型：`String`
  + API 部署到 API Gateway 的阶段名称。对于使用 `$default` 阶段的任何 HTTP API 来说，它都是可选选项。
+ `Path`
  + 类型：`String`
  + 附加在 API 端点之后的路径参数。
+ `QueryParameters`
  + 类型：`JSON`
  + 查询字符串仅允许列出与相同键关联的值。
+ `RequestBody`
  + 类型：`JSON` 或 `String`
  + HTTP 请求正文。其类型可以是 `JSON` 对象或 `String`。 `RequestBody` 仅支持`PATCH`、`POST` 和 `PUT` HTTP 方法。
+ `AllowNullValues`
  + 类型：`BOOLEAN` - 默认值：`false`
  + 在默认设置下，任何处于请求输入状态的 **null** 值都**不会**发送到您的 API。在以下示例中，`category` 字段将**不会**包含在请求中，除非在状态机定义中将 `AllowNullValues` 设置为 `true`。

    ```
    {
        "NewPet": {
            "type": "turtle",
            "price": 123,
            "category": null
        }
    }
    ```
**注意**  
默认情况下，请求输入状态中具有 **null** 值的字段**不会**发送到您的 API。通过在状态机定义中将 `AllowNullValues` 设置为 `true`，可以强制将 null 值发送到您的 API。
+ `AuthType`
  + 类型：`JSON`
  + 身份验证方法。默认方法是 `NO_AUTH`。允许的许值为：
    + `NO_AUTH`
    + `IAM_ROLE`
    + `RESOURCE_POLICY`

    有关更多信息，请参阅**身份验证和授权**。

**注意**  
出于安全考虑，目前不允许使用以下 HTTP 标头密钥：  
任何以 `X-Forwarded`、`X-Amz` 或 `X-Amzn` 为前缀的标头密钥。
`Authorization`
`Connection`
`Content-md5`
`Expect`
`Host`
`Max-Forwards`
`Proxy-Authenticate`
`Server`
`TE`
`Transfer-Encoding`
`Trailer`
`Upgrade`
`Via`
`Www-Authenticate`

下面的代码示例展示了如何使用 Step Functions 调用 API Gateway。

```
{
    "Type": "Task", 
    "Resource":"arn:aws:states:::apigateway:invoke", 
    "Arguments": {
        "ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com",
        "Method": "GET", 
        "Headers": { 
            "key": ["value1", "value2"] 
        },
        "Stage": "prod",
        "Path": "bills",
        "QueryParameters": {
            "billId": ["123456"]
        },
        "RequestBody": {},
        "AuthType": "NO_AUTH"
    } 
}
```

## 身份验证和授权
<a name="connect-api-gateway-auth"></a>

您可以使用以下验证方法：
+ **无授权**：直接调用 API，无需授权方法。
+ **IAM 角色**：使用此方法，Step Functions 将扮演状态机的角色，使用[签名版本 4](https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html) (Sigv4) 对请求进行签名，然后调用 API。
+ **资源策略**：Step Functions 对请求进行身份验证，然后调用 API。您必须将资源策略附加到 API，其中指定以下内容：

  1. 将调用 API Gateway 的状态机。
**重要**  
必须指定状态机，用于能限制对它的访问。如果不这样做，那么任何使用**资源策略**身份验证对 API 进行 API Gateway 请求验证的状态机都将被允许访问。

  1. 该 Step Functions 就是调用 API Gateway 的服务：`"Service": "states.amazonaws.com"`。

  1. 要访问的资源，包括：
     + *region*。
     + 指定区域*account-id*中的。
     + *api-id*。
     + *stage-name*。
     + *HTTP-VERB*（方法）。
     + *resource-path-specifier*。

  有关资源策略的示例，请参阅 [Step Functions 和 API Gateway 的 IAM 策略](#api-gateway-iam)。

  有关资源格式的更多信息，请参阅 API Gateway 开发人员指南中的[在 API Gateway 中执行 API 的权限的资源格式](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-control-access-using-iam-policies-to-invoke-api.html#api-gateway-iam-policy-resource-format-for-executing-api)。
**注意**  
只有 REST API 支持资源策略。

## 服务集成模式
<a name="connect-api-gateway-patterns"></a>

API Gateway 集成支持两种服务集成模式：
+ [请求响应](connect-to-resource.md#connect-default)，这是默认的集成模式。它允许 Step Functions 在收到 HTTP 响应后立即进入下一步。
+ [等待具有任务令牌的回调](connect-to-resource.md#connect-wait-token) (`.waitForTaskToken`)，该模式会等到任务令牌与有效载荷一起返回。要使用该`.waitForTaskToken`模式，请附加。 waitForTask标记到任务定义的 “**资源**” 字段末尾，如以下示例所示：

  ```
  {
      "Type": "Task", 
      "Resource":"arn:aws:states:::apigateway:invoke.waitForTaskToken", 
      "Arguments": {
          "ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com",
          "Method": "POST", 
          "Headers": { 
              "TaskToken": "{% $states.context.Task.Token %}"
          },
          "Stage": "prod",
          "Path": "bills/add",
          "QueryParameters": {},
          "RequestBody": {
              "billId": "my-new-bill"
          },
          "AuthType": "IAM_ROLE"
      } 
  }
  ```

## 输出格式
<a name="connect-api-gateway-output"></a>

提供以下输出参数：


| Name | Type | 说明 | 
| --- | --- | --- | 
| ResponseBody | JSON 或 String | API 调用的响应正文。 | 
| Headers | JSON | 响应标头。 | 
| StatusCode | Integer | 响应的 HTTP 状态代码。 | 
| StatusText | String | 响应的状态文本。 | 

响应示例：

```
{
    "ResponseBody": {
        "myBills": []
    },
    "Headers": { 
        "key": ["value1", "value2"]
    }, 
    "StatusCode": 200,
    "StatusText": "OK" 
}
```

## 错误处理
<a name="connect-api-gateway-errors"></a>

发生错误时，会返回 `error` 和 `cause` 如下：
+ 如果 HTTP 状态码可用，则错误将以 `ApiGateway.<HTTP Status Code>` 格式返回。
+ 如果 HTTP 状态码不可用，则错误将以 `ApiGateway.<Exception>` 格式返回。

在这两种情况下，`cause` 都以字符串形式返回。

以下示例展示了发生错误时的响应：

```
{
    "error": "ApiGateway.403", 
    "cause": "{\"message\":\"Missing Authentication Token\"}"
}
```

**注意**  
状态码为 `2XX` 表示成功，不会返回任何错误。所有其他状态代码或抛出的异常都将导致错误。

## 用于调用 Amazon API Gateway 的 IAM 策略
<a name="api-gateway-iam"></a>

以下示例模板展示了如何根据状态机定义中的资源 AWS Step Functions 生成 IAM 策略。有关更多信息，请参阅[Step Functions 如何为集成服务生成 IAM 策略](service-integration-iam-templates.md)和[探索 Step Functions 中的服务集成模式](connect-to-resource.md)。

*资源：*

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Action": [
                "execute-api:Invoke"
            ],
            "Resource": [
                "arn:aws:execute-api:us-east-1:123456789012:ENDPOINT/STAGE/GET/pets",
                "arn:aws:execute-api:us-east-1:123456789012:ENDPOINT/STAGE/POST/pets"
            ],
            "Effect": "Allow"
        }
    ]
}
```

以下代码示例显示了调用 API Gateway 的资源策略。

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "states.amazonaws.com"
            },
            "Action": "execute-api:Invoke",
            "Resource": "arn:aws:execute-api:us-east-1:123456789012:myApi-id/stage-name/HTTP-VERB/resource-path-specifier",
            "Condition": {
                "StringEquals": {
                    "aws:SourceArn": [
                        "<SourceStateMachineArn>"
                    ]
                }
            }
        }
    ]
}
```