本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
使用 Step Functions 调用 API Gateway
Step Functions 可以控制某些Amazon直接来自亚马逊状态语言的服务。有关使用的更多信息Amazon Step Functions及其集成,请参阅以下内容:
-
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 的更多信息,请参阅以下内容。
-
这些区域有:Amazon API Gateway 概念页.
-
在 HTTP API 和 REST API 之间进行选择在 API Gateway 开发人员指南中。
请求格式
当你创建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 Gateway 中将 API 部署到的阶段的名称。对于任何使用
$default
阶段。
-
-
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,该策略指定以下内容:
-
将调用 API Gateway 的状态机。
重要 您必须指定状态机才能限制对其的访问。如果你不这样做,那么任何用来验证其 API Gateway 请求的状态机资源策略您的 API 的身份验证将被授予访问权限。
-
该 Step Functions 就是调用 API Gateway 的服务:
"Service": "states.amazonaws.com"
. -
您要访问的资源,包括:
-
这些区域有:
领域
. -
这些区域有:
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 开发人员指南中。
-
针对 Step Functions 和Amazon API Gateway
-
一个示例项目,展示了如何致电 API Gateway
Amazon API Gateway 概念在 API Gateway 开发人员指南中。