API Gateway 特征支持请求格式身份验证和授权服务集成模式输出格式错误处理 IAM 策略

使用 Step Functions 创建 API 网关 REST APIs

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

要了解如何在 Step Functions 中与 AWS 服务集成，请参阅集成服务和在 Step Functions 中将参数传递给服务 API。

经优化的 API Gateway 集成的主要功能

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

API Gateway 特征支持

Step Functions API Gateway 集成支持部分 API 特征，而非全部。有关支持特征的详细信息，请参阅以下内容。

Step Functions API Gateway REST API 和 API Gateway HTTP API 集成都支持：
- 授权方：IAM（使用签名版本 4）、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 概念页面。
在 API Gateway 开发者指南 APIs中在 HTTP APIs 和 REST 之间进行选择。

请求格式

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

必需请求参数

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

可选请求参数

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", 
    "Parameters": {
        "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"
    } 
}

身份验证和授权

您可以使用以下验证方法：

无授权：直接调用 API，无需授权方法。
IAM 角色：使用此方法，Step Functions 将扮演状态机的角色，使用签名版本 4 (Sigv4) 对请求进行签名，然后调用 API。
资源策略：Step Functions 对请求进行身份验证，然后调用 API。您必须将资源策略附加到 API，其中指定以下内容：
1. 将调用 API Gateway 的状态机。
  
  重要
  必须指定状态机，用于能限制对它的访问。如果不这样做，那么任何使用资源策略身份验证对 API 进行 API Gateway 请求验证的状态机都将被允许访问。
2. 该 Step Functions 就是调用 API Gateway 的服务："Service": "states.amazonaws.com"。
3. 要访问的资源，包括：
  - region。
  - 指定区域account-id中的。
  - api-id。
  - stage-name。
  - HTTP-VERB（方法）。
  - resource-path-specifier。
有关资源策略的示例，请参阅 Step Functions 和 API Gateway 的 IAM 策略。

有关资源格式的更多信息，请参阅 API Gateway 开发人员指南中的在 API Gateway 中执行 API 的权限的资源格式。

注意
只有 REST API 支持资源策略。

服务集成模式

API Gateway 集成支持两种服务集成模式：

请求响应，这是默认的集成模式。它允许 Step Functions 在收到 HTTP 响应后立即进入下一步。

等待具有任务令牌的回调 (.waitForTaskToken)，该模式会等到任务令牌与有效载荷一起返回。要使用该.waitForTaskToken模式，请附加。 waitForTask标记到任务定义的 “资源” 字段末尾，如以下示例所示：


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

输出格式

提供以下输出参数：

名称	类型	描述
`ResponseBody`	`JSON` 或 `String`	API 调用的响应正文。
`Headers`	`JSON`	响应标头。
`StatusCode`	`Integer`	响应的 HTTP 状态代码。
`StatusText`	`String`	响应的状态文本。

响应示例：


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

错误处理

发生错误时，会返回 error 和 cause 如下：

如果 HTTP 状态码可用，则错误将以 ApiGateway.<HTTP Status Code> 格式返回。
如果 HTTP 状态码不可用，则错误将以 ApiGateway.<Exception> 格式返回。

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

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


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

注意

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

用于调用 Amazon API Gateway 的 IAM 策略

以下示例模板展示了如何根据状态机定义中的资源 AWS Step Functions 生成 IAM 策略。有关更多信息，请参阅Step Functions 如何为集成服务生成 IAM 策略和探索 Step Functions 中的服务集成模式。

资源：


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "execute-api:Invoke"
            ],
            "Resource": [
                "arn:[[region]]:[[accountId]]:*"
            ]
        }
    ]
}

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


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

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

集成优化的服务

Amazon Athena