本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
使用 Step Functions 调用 API Gateway
Step Functions 可以直接从 Amazon States Language (ASL) 控制某些 Amazon 服务。要了解更多信息,请参阅使用其他服务和将参数传递给服务 API。
优化后的 API Gateway 集成与 API Gateway Amazon SDK 集成有何不同
-
apigateway:invoke:
在 Amazon SDK 服务集成中没有等效项。相反,优化的 API Gateway 服务可以直接调用您的 API Gateway 端点。
您可以使用 Amazon API Gateway 创建、发布、维护和监控 HTTP 和 REST API。要与 API Gateway 集成,您可以在步骤功能中定义一个 Task
状态,直接调用 API Gateway HTTP 或 API Gateway REST 端点,而无需编写代码或依赖其他基础架构。Task
状态定义包括 API 调用的所有必要信息。您也可以选择不同的授权方法。
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 的更多信息,请参阅以下内容。
-
API Gateway 开发人员指南种的在 HTTP API 和 REST API 之间进行选择。
请求格式
在创建 Task
状态定义时,Step Functions 会验证参数,构建执行调用所需的 URL,然后调用 API。响应包括 HTTP 状态代码、标头和响应正文。请求格式包括必需和可选参数。
必需请求参数
-
ApiEndpoint
-
类型:
String
-
API Gateway URL 的主机名。格式为
。<API ID>
.execute-api.<region>
.amazonaws.comAPI 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
-默认值: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-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,其中指定以下内容:
-
将调用 API Gateway 的状态机。
重要
必须指定状态机,用于能限制对它的访问。如果不这样做,那么任何使用资源策略身份验证对 API 进行 API Gateway 请求验证的状态机都将被允许访问。
-
该 Step Functions 就是调用 API Gateway 的服务:
"Service": "states.amazonaws.com"
。 -
要访问的资源,包括:
-
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
模式,请在任务定义的 “资源” 字段末尾添加.wai ForTaskToken t,如以下示例所示:{ "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
表示成功,不会返回任何错误。所有其他状态代码或抛出的异常都将导致错误。
有关更多信息,请参阅:
-
API Gateway 开发人员指南中的 Amazon API Gateway 概念。
-
演示如何调用 API Gateway 的示例项目
API Gateway 开发人员指南中的 Amazon API Gateway 概念。