使用 Step Functions 调用 API Gateway - AWS Step Functions

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

使用 Step Functions 调用 API Gateway

Step Functions 可以直接从 Amazon States Language (ASL) 控制某些 AWS 服务。要了解更多信息,请参阅使用其他服务将参数传递给服务 API

优化后的 API Gateway 集成与 API Gateway AWS SDK 集成有何不同
  • apigateway:invoke:在 AWS SDK 服务集成中没有等效项。相反,优化的 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

    • 类型:JSONString

    • HTTP 请求正文。其类型可以是 JSON 对象或 StringRequestBody 仅支持PATCHPOSTPUT HTTP 方法。

  • AllowNullValues

    • 类型:BOOLEAN-默认值:false

    • 在默认设置下,任何处于请求输入状态的值都不会发送到您的 API。在以下示例中,除非在状态机定义中将其设置AllowNullValues为,否则该category字段不会包含true在请求中。

      { "NewPet": { "type": "turtle", "price": 123, "category": null } }
      注意

      默认情况下,请求输入状态为空值的字段不会发送到您的 API。通过true在状态机定义中设置为,可以强制将空值发送AllowNullValues到您的 API。

  • AuthType

    • 类型:JSON

    • 身份验证方法。默认方法是 NO_AUTH。容许值为:

      • NO_AUTH

      • IAM_ROLE

      • RESOURCE_POLICY

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

注意

出于安全考虑,目前不允许使用以下 HTTP 标头密钥:

  • 任何以 X-ForwardedX-AmzX-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" } }

输出格式

提供以下输出参数:

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

响应示例:

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

错误处理

发生错误时,会返回 errorcause 如下:

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

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

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

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

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

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

有关更多信息,请参阅:

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