使用 Step Functions 调用 API Gateway - Amazon Step Functions
API Gateway 功能支持请求格式身份验证和授权服务集成模式输出格式错误处理
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅中国的 Amazon Web Services 服务入门。

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

使用 Step Functions 调用 API Gateway

Step Functions 可以控制某些Amazon直接来自亚马逊状态语言的服务。有关使用的更多信息Amazon Step Functions及其集成，请参阅以下内容：

优化的 API Gateway 集成与 API Gateway 有何不同AmazonSDK 集成

  • apigateway:invoke:没有等效的AmazonSDK 服务集成。相反，优化的 API Gateway 服务直接调用您的 API Gateway 终端节点。

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

注意

Step Functions 支持通过 API Gateway 调用 HTTP 端点的功能，但目前不支持调用通用 HTTP 终端节点的功能。

API Gateway 功能支持

Step Functions API Gateway 集成支持部分但不是所有 API Gateway 功能。有关支持功能的更详细的列表，请参阅以下内容。

  • 受 Step Functions API Gateway REST API 和 API Gateway HTTP API 集成的支持：

    • 授权方：IAM（使用 IAM）签名版本 4)、No Auth、Lambda 授权者（基于请求参数和基于令牌的自定义标题）

    • API 类型：区域性

    • API 管理：API Gateway API 域名、API 阶段、路径、查询参数、请求正文

  • 受 Step Functions API Gateway HTTP API 集成的支持，但不支持 Step Functions API Gateway REST API 集成：

    • 边缘优化的 API

  • Step Functions API Gateway 集成不支持：

    • 授权方：Amazon Cognito，原生开放 ID Connect /OAuth 2.0，基于令牌的 Lambda 授权者的授权标头

    • API 类型：私有

    • API 管理：自定义域名

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

请求格式

当你创建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 Gateway 中将 API 部署到的阶段的名称。对于任何使用$default阶段。

  • Path

    • 类型：String

    • 附加在 API 终端节点之后的路径参数。

  • QueryParameters

    • 类型：JSON

    • 查询字符串允许列出与同一键关联的值。

  • RequestBody

    • 类型：JSON 或 String

    • HTTP 请求正文。它的类型可以是JSON对象或String.RequestBody仅支持PATCH、POST, 和PUTHTTP 方法。

  • AllowNullValues

    • 类型：BOOLEAN

    • 设置AllowNullValues到true将允许你传递空值，如下所示：

      {
    "NewPet": {
        "type": "turtle",
        "price": 123,
        "name": null
    }
}

  • 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 Gateway 请求的状态机资源策略您的 API 的身份验证将被授予访问权限。

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

    3. 您要访问的资源，包括：

      • 这些区域有：领域.

      • 这些区域有：account-id在指定区域中。

      • 这些区域有：api-id.

      • 这些区域有：阶段名称.

      • 这些区域有：HTTP-动词（方法）。

      • 这些区域有：资源路径特定符.

    有关资源策略示例，请参阅。针对 Step Functions 和 API Gateway 的 IAM 策略.

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

    注意

    资源策略仅支持 REST API。

服务集成模式

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

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

  • 等待具有任务令牌的回调(.waitForTaskToken)，等待，直到使用有效负载返回任务令牌。使用.waitForTaskToken模式，将 .WaitforTaskToken 附加到资源如以下示例所示的任务定义字段所示：

    {
    "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 概念在 API Gateway 开发人员指南中。