API网关功能支持请求格式身份验证和授权服务集成模式输出格式错误处理 IAM政策

使用 Step Funct REST APIs ions 创建API网关

了解如何使用 Amazon API Gateway 创建、发布、维护HTTP和监控以及如何使用 Step F REST APIs unctions。要与 API Gateway 集成，您可以在 Step Functions 中定义一种Task状态，该状态可以直接调用API网API关HTTP或网关REST端点，无需编写代码或依赖其他基础架构。Task状态定义包括API呼叫的所有必要信息。您也可以选择不同的授权方法。

要了解如何与集成 AWS Step Functions 中的服务，参见集成服务和。在 Step Functions API 中向服务传递参数

优化的API网关集成的主要功能

apigateway:invoke:里面没有对应的 AWS SDK服务集成。相反，优化API网关服务会直接调用您的API网关终端节点。

API网关功能支持

Step Functi API ons Gateway 集成支持部分但不是全部 API Gateway 功能。有关支持特征的详细信息，请参阅以下内容。

Step Functions API 网关RESTAPI和API网关HTTPAPI集成均支持：
- 授权方：IAM（使用签名版本 4）、无身份验证、Lambda 授权者（基于请求参数，基于令牌，带有自定义标头）
- API类型：区域
- API管理：API网关API域名、API阶段、路径、查询参数、请求正文
由 Step Functions API 网关HTTPAPI集成提供支持。不支持提供边缘优化选项的 Step Functions APIs G API ateway REST API 集成。
Step Functions API 网关集成不支持：
- 授权方：亚马逊 Cognito、Native Open ID Connect OAuth /2.0、基于令牌的 Lambda 授权者的授权标头
- API类型：私人
- API管理：自定义域名

有关 API Gateway 及其HTTP和的更多信息 RESTAPIs，请参阅以下内容。

Amazon API Gateway 概念页面。
在 API Gateway 开发者指南RESTAPIs中选择 “HTTPAPIs和”。

请求格式

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

必需请求参数

ApiEndpoint
- 类型：String
- API网关的主机名URL。格式为 <API ID>.execute-api.<region>.amazonaws.com。
  
  APIID 只能包含以下字母数字字符的组合：0123456789abcdefghijklmnopqrstuvwxyz
Method
- 类型：Enum
- 该HTTP方法必须是以下方法之一：
  - GET
  - POST
  - PUT
  - DELETE
  - PATCH
  - HEAD
  - OPTIONS

可选请求参数

Headers
- 类型：JSON
- HTTP标头允许列出与同一个键关联的值。
Stage
- 类型：String
- 在 Gate API w API ay 中部署到的阶段的名称。对于任何使用$default舞台的人来说 HTTPAPI，它是可选的。
Path
- 类型：String
- 附加在API端点之后的路径参数。
QueryParameters
- 类型：JSON
- 查询字符串仅允许列出与相同键关联的值。
RequestBody
- 类型：JSON 或 String
- HTTP请求正文。它的类型可以是JSON对象或String。 RequestBody仅支持PATCHPOST、和PUTHTTP方法。
AllowNullValues
- 类型：BOOLEAN-默认值：false
- 使用默认设置时，任何处于请求输入状态的空值都不会发送给您的API。在以下示例中，除非在状态机定义中将其设置AllowNullValues为，否则该category字段不会包含true在请求中。
```
{
    "NewPet": {
        "type": "turtle",
        "price": 123,
        "category": null
    }
}
```
  注意
  默认情况下，在请求输入状态下为空值的字段不会发送给您的API。API通过在状态机定义true中设置为，可以强制AllowNullValues将空值发送给您。
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网关。


{
    "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将被授予访问权限。
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网API关开发者指南》API中的在 Gateway 中执行权限的资源格式。

注意
仅支持资源策略RESTAPI。

服务集成模式

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

请求响应，这是默认的集成模式。它允许 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"
    } 
}

输出格式

提供以下输出参数：

名称	Type	描述
`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 表示成功，不会返回任何错误。所有其他状态代码或抛出的异常都将导致错误。

IAM调用 Amazon API Gateway 的政策

以下示例模板演示了如何操作 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