使用 Step Functions 调用 API Gateway - Amazon Step Functions
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

    • 类型:JSONString

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

  • AllowNullValues

    • 类型:BOOLEAN

    • 设置AllowNullValuestrue将允许你传递空值,如下所示:

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

    • 类型:JSON

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

      • NO_AUTH

      • IAM_ROLE

      • RESOURCE_POLICY

      请参阅身份验证和授权有关.

注意

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

  • 任何内容作为前缀X-ForwardedX-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_AUTH" } }

输出格式

提供了以下输出参数:

名称 类型 描述
ResponseBody JSON 或者 String 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表示成功,不会返回错误。所有其他状态代码或抛出的异常都将导致错误。

有关更多信息,请参阅:

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