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

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

使用 Step Functions 调用 API Gateway

Step Functions 可以直接从 Amazon States Language (ASL) 控制某些 Amazon 服务。有关使用 Amazon Step Functions 及其集成的更多信息，请参阅以下内容：

优化的 API Gateway 集成与 API Gateway Amazon 开发工具包集成有何不同

  • 在 Amazon 开发工具包服务集成中没有 apigateway:invoke: 等效项。相反，优化的 API Gateway 服务可以直接调用您的 API Gateway 端点。

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

注意

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

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 集成支持。不支持为边缘优化 API 提供选项的 Step Functions API Gateway REST API 集成。

  • Step Functions API Gateway 集成不支持：

    • 授权方：Amazon Cognito、Native Open 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 部署到 API Gateway 的阶段名称。对于使用 $default 阶段的任何 HTTP API 来说，它都是可选选项。

  • Path

    • 类型：String

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

  • QueryParameters

    • 类型：JSON

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

  • RequestBody

    • 类型：JSON 或 String

    • HTTP 请求正文。其类型可以是 JSON 对象或 String。 RequestBody 仅支持PATCH、POST 和 PUT HTTP 方法。

  • 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 进行 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 模式，请将.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 表示成功，不会返回任何错误。所有其他状态代码或抛出的异常都将导致错误。

有关更多信息，请参阅：

API Gateway 开发人员指南中的 Amazon API Gateway 概念。