本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
在 Step Functions 工作流程APIs中致电第三方
HTTP任务是一种任务工作流状态状态,允许您在工作流程中致电任何公众API、第三方,例如 Salesforce 和 Stripe。要致电第三方API,请使用arn:aws:states:::http:invoke
资源的 “任务” 状态。然后,提供API端点配置详细信息,例如您要使用的方法和身份验证详细信息。API URL
如果您使用 Workflow Studio 来构建包含HTTP任务的状态机,则 Workflow Studio 会自动生成一个带有HTTP任务IAM策略的执行角色。有关更多信息,请参阅 在工作流工作室中测试HTTP任务的角色。
主题
HTTP任务定义
该ASL定义表示具有http:invoke
资源的HTTP任务。以下HTTP任务定义调用返回所有客户列表API的 Stripe。
"Call third-party API": {
"Type": "Task",
"Resource": "arn:aws:states:::http:invoke",
"Parameters": {
"ApiEndpoint": "https://api.stripe.com/v1/customers",
"Authentication": {
"ConnectionArn": "arn:aws:events:us-east-2
:123456789012
:connection/Stripe/81210c42-8af1-456b-9c4a-6ff02fc664ac"
},
"Method": "GET"
},
"End": true
}
HTTP任务字段
HTTP任务的定义中包括以下字段。
Resource
(必填)-
要指定任务类型,请在
Resource
字段ARN中提供其类型。对于HTTP任务,您可以按如下方式指定该Resource
字段。"Resource": "arn:aws:states:::http:invoke"
Parameters
(必填)-
包含
ApiEndpoint
Method
、和ConnectionArn
字段,提供有关API您要呼叫的第三方的信息。Parameters
还包含可选字段,例如Headers
和QueryParameters
。您可以像在
Parameters
字段Parameters
中一样指定静态JSON和JsonPath语法的组合。有关更多信息,请参阅 在 Step Functions API 中向服务传递参数。 ApiEndpoint
(必需)-
指定API您要呼叫URL的第三方。要将查询参数附加到URL,请使用字段。
QueryParameters
以下示例显示了如何调用 Stripe API 来获取所有客户的列表。"ApiEndpoint":"https://api.stripe.com/v1/customers"
您也可以使用JsonPath
语法指定参考路径来选择包含第三方的JSON节点APIURL。例如,假设你想APIs使用特定的客户 ID 拨打某个 Stripe 的电话。想象一下,您已提供以下状态输入。 { "customer_id": "1234567890", "name": "John Doe" }
要使用 Stripe 检索此客户 ID 的详细信息API,请指定,
ApiEndpoint
如以下示例所示。此示例使用了内置函数和参考路径。"ApiEndpoint.$":"States.Format('https://api.stripe.com/v1/customers/{}', $.customer_id)"
在运行时,Step Functions 解析
ApiEndpoint
的值,如下所示。https://api.stripe.com/v1/customers/
1234567890
Method
(必需)-
指定要用于呼叫第三方HTTP的方法API。您可以在HTTP任务中指定以下方法之一:GET、POST、PUT、DELETE、PATCHOPTIONS、或HEAD。
例如,要使用该GET方法,请按如下方式指定该
Method
字段。"Method": "GET"
您也可以在运行时使用参考路径来指定方法。例如,
"Method.$": "$.myHTTPMethod"
。 Authentication
(必需)-
包含指定如何对第三方API呼叫进行身份验证的
ConnectionArn
字段。 Step Functions支持ApiEndpoint
使用连接资源对指定的进行身份验证Amazon EventBridge。ConnectionArn
(必需)-
指定EventBridge连接ARN。
HTTP任务需要EventBridge 连接,该连接可以安全地管理API提供商的身份验证凭据。连接指定用于授权第三方API的授权类型和凭据。使用连接可以帮助您避免将密钥(例如密API钥)硬编码到状态机定义中。在连接中,您还可以指定
Headers
、QueryParameters
和RequestBody
参数。创建 EventBridge 连接时,您需要提供身份验证详细信息。有关HTTP任务的身份验证工作原理的更多信息,请参阅HTTP任务的身份验证。
以下示例说明如何在HTTP任务定义中指定
Authentication
字段。"Authentication": { "ConnectionArn": "arn:aws:events:us-east-2:
123456789012
:connection/Stripe/81210c42-8af1-456b-9c4a-6ff02fc664ac" } Headers
(可选)-
为API端点提供额外的上下文和元数据。您可以将标题指定为字符串或JSON数组。
您可以在EventBridge连接中指定标题,在HTTP任务中指定
Headers
字段。我们建议您不要在Headers
字段中向API提供商提供身份验证详细信息。建议您将这些详细信息包含在 EventBridge 连接中。Step Functions将您在EventBridge连接中指定的标题添加到您在HTTP任务定义中指定的标题中。如果定义和连接中存在相同的标头键,则 Step Functions 会使用 EventBridge 连接中为这些标头指定的相应值。有关 Step Functions 如何执行数据合并的更多信息,请参阅合并EventBridge连接和HTTP任务定义数据。
以下示例指定了将包含在第三方API调用中的标头:
content-type
."Headers": { "content-type": "application/json" }
您也可以在运行时使用参考路径来指定标头。例如,
"Headers.$": "$.myHTTPHeaders"
。Step Functions设置
User-Agent
Range
、和Host
标题。 Step Functions根据API您正在调用的设置Host
标头的值。以下是这些标头的一个示例。User-Agent: Amazon|StepFunctions|HttpInvoke|
us-east-1
, Range: bytes=0-262144, Host: api.stripe.com您不能在HTTP任务定义中使用以下标题。如果您使用这些标头,则HTTP任务将失败并显示
States.Runtime
错误。-
A-IM
-
Accept-Charset
-
Accept-Datetime
-
Accept-Encoding
-
Cache-Control
-
Connection
-
Content-Encoding
-
内容-MD5
-
Date
-
Expect
-
Forwarded
-
From
-
Host
-
HTTP2-设置
-
If-Match
-
If-Modified-Since
-
If-None-Match
-
If-Range
-
If-Unmodified-Since
-
Max-Forwards
-
Origin
-
Pragma
-
Proxy-Authorization
-
Referer
-
Server
-
TE
-
Trailer
-
Transfer-Encoding
-
Upgrade
-
Via
-
Warning
-
x-forwarded-*
-
x-amz-*
-
x-amzn-*
-
QueryParameters
(可选)-
在 a 的末尾插入键值对。API URL您可以将查询参数指定为字符串、JSON数组或JSON对象。 Step Functions当它调URL用第三方时,它会自动对查询参数进行编码。API
例如,假设您想致电 Stripe API 来搜索以美元进行交易的客户 (USD)。想象一下,您已提供以下
QueryParameters
作为状态输入。"QueryParameters": { "currency": "usd" }
在运行时,Step Functions 会按APIURL如下方式将附加
QueryParameters
到。https://api.stripe.com/v1/customers/search?currency=usd
您也可以在运行时使用参考路径来指定查询参数。例如,
"QueryParameters.$": "$.myQueryParameters"
。如果您在EventBridge连接中指定了查询参数,则Step Functions会将这些查询参数添加到您在HTTP任务定义中指定的查询参数中。如果定义和连接中存在相同的查询参数键,则 Step Functions 会使用 EventBridge 连接中为这些标头指定的相应值。有关 Step Functions 如何执行数据合并的更多信息,请参阅合并EventBridge连接和HTTP任务定义数据。
Transform
(可选)-
包含
RequestBodyEncoding
和RequestEncodingOptions
字段。默认情况下,Step Functions将请求正文作为JSON数据发送到API端点。如果您的API提供程序接受
form-urlencoded
请求正文,请使用该Transform
字段为请求正文指定 URL-encoding。您还必须将标content-type
题指定为application/x-www-form-urlencoded
。 Step Functions然后自动对你的请求正文进行 URL-编码。RequestBodyEncoding
-
指定请求正文的URL编码。您可以指定以下值之一:
NONE
或URL_ENCODED
。-
NONE
— HTTP 请求正文将是该RequestBody
字段的序列JSON化内容。这是默认值。 -
URL_ENCODED
— HTTP 请求正文将是该字段URL经过编码的表单数据。RequestBody
-
RequestEncodingOptions
-
用于确定在您将
RequestBodyEncoding
设置为URL_ENCODED
的情况下,要为请求正文中的数组使用的编码选项。Step Functions 支持以下数组编码选项。有关这些选项的更多信息及其示例,请参阅在请求正文上应用 URL-编码。
-
INDICES
:使用数组元素的索引值对数组进行编码。Step Functions 默认使用此编码选项。 -
REPEAT
:针对数组中的每个项重复使用一个键。 -
COMMAS
:将键中的所有值编码为以逗号分隔的值列表。 -
BRACKETS
:针对数组中的每个项重复使用一个键,并为该键附加一个方括号 [],以表示它是一个数组。
-
以下示例为请求正文数据URL设置-encoding。它还指定在请求正文中为数组使用
COMMAS
编码选项。"Transform": { "RequestBodyEncoding": "URL_ENCODED", "RequestEncodingOptions": { "ArrayFormat": "COMMAS" } }
RequestBody
(可选)-
接受您在状态输入中提供的JSON数据。在中
RequestBody
,您可以指定静态JSON和JsonPath语法的组合。例如,假设您提供以下状态输入: { "CardNumber": "1234567890", "ExpiryDate": "09/25" }
要在运行时
ExpiryDate
在请求正文中使用CardNumber
和的这些值,您可以在请求正文中指定以下JSON数据。"RequestBody": { "Card": { "Number.$": "$.CardNumber", "Expiry.$": "$.ExpiryDate", "Name": "John Doe", "Address": "123 Any Street, Any Town, USA" } }
API如果您要调用的第三方需要
form-urlencoded
请求正文,则必须为请求正文数据指定 URL-encoding。有关更多信息,请参阅 在请求正文上应用 URL-编码。
HTTP任务的身份验证
HTTP任务需要EventBridge 连接,该连接可以安全地管理API提供商的身份验证凭据。连接指定用于授权第三方API的授权类型和凭据。使用连接可以帮助您避免将密钥(例如密API钥)硬编码到状态机定义中。 EventBridge 连接支持基本OAuth、和API密钥授权方案。
创建 EventBridge 连接时,您需要提供身份验证详细信息。您还可以将授权所需的标头、正文和查询参数包含在中API。您必须将该连接包含ARN在任何调用第三方的HTTP任务中API。
当您创建连接并添加授权参数时, EventBridge 会在中创建密钥 AWS Secrets Manager。在此密钥中,以加密形式 EventBridge 存储连接和授权参数。要成功创建或更新连接,必须使用有权使用 S AWS 账户 ecrets Manager 的。有关状态机访问 EventBridge 连接所需的IAM权限的更多信息,请参阅IAM运行HTTP任务的权限。
下图显示了如何使用EventBridge连接Step Functions处理第三方API呼叫的身份验证。管理第三方API提供商凭证的EventBridge连接。 EventBridge在中创建密钥,Secrets Manager以加密形式存储连接和授权参数。
![该图显示了 Step Functi EventBridge ons 如何使用连接调用HTTP端点。](images/http-task-how-auth-works.png)
合并EventBridge连接和HTTP任务定义数据
调用HTTP任务时,可以在EventBridge连接和HTTP任务定义中指定数据。此数据包括 Headers
、QueryParameters
和 RequestBody
参数。在调用第三方之前API,Step Functions 会在所有情况下将请求正文与连接正文参数合并,除非您的请求正文为字符串且连接正文参数为非空。在这种情况下,HTTP任务因States.Runtime
错误而失败。
如果在HTTP任务定义和连接中指定了任何重复的密钥,则使用EventBridge连接中的值Step Functions覆盖HTTP任务中的值。
以下列表描述了在致电第三方API之前如何Step Functions合并数据:
-
标题 — Step Functions 将您在连接中指定的任何标题添加到HTTP任务
Headers
字段的标题中。如果标头键之间存在冲突,Step Functions 会使用连接中为这些标头指定的值。例如,如果您在HTTP任务定义和EventBridge连接中都指定了content-type
标题,则Step Functions使用连接中指定的content-type
标题值。 -
查询参数-Step Functions 将您在连接中指定的任何查询参数添加到HTTP任务
QueryParameters
字段的查询参数中。如果查询参数键之间存在冲突,Step Functions 会使用连接中为这些查询参数指定的值。例如,如果您在HTTP任务定义和EventBridge连接中都指定了maxItems
查询参数,则Step Functions使用连接中指定的maxItems
查询参数值。 -
主体参数
-
Step Functions将连接中指定的任何请求正文值添加到HTTP任务
RequestBody
字段的请求正文中。如果请求正文键之间存在冲突,Step Functions 会使用连接中为请求正文指定的值。例如,假设您在HTTP任务定义和EventBridge连接RequestBody
中都指定了一个Mode
字段。 Step Functions使用您在连接中指定的Mode
字段值。 -
如果您将请求正文指定为字符串而不是JSON对象,并且EventBridge连接还包含请求正文,则Step Functions无法合并在这两个位置指定的请求正文。它因
States.Runtime
错误而使HTTP任务失败。
在请求正文完成合并后,Step Functions 会应用所有转换并将请求正文序列化。
-
以下示例在HTTP任务和EventBridge连接中设置Headers
QueryParameters
、和RequestBody
字段。
HTTP任务定义
{ "Comment": "Data merging example for HTTP Task and EventBridge connection", "StartAt": "ListCustomers", "States": { "ListCustomers": { "Type": "Task", "Resource": "arn:aws:states:::http:invoke", "Parameters": { "Authentication": { "ConnectionArn": "arn:aws:events:us-east-1:
123456789012
:connection/Example/81210c42-8af1-456b-9c4a-6ff02fc664ac
" }, "ApiEndpoint": "https:/example.com/path
", "Method": "GET", "Headers": {"Request-Id": "my_request_id", "Header-Param": "state_machine_header_param"
}, "RequestBody": {"Job": "Software Engineer", "Company": "AnyCompany", "BodyParam": "state_machine_body_param"
}, "QueryParameters": {"QueryParam": "state_machine_query_param"
} } } } }
EventBridge 连接
{ "AuthorizationType": "
API_KEY
", "AuthParameters": { "ApiKeyAuthParameters": { "ApiKeyName": "ApiKey
", "ApiKeyValue": "key_value
" }, "InvocationHttpParameters": { "BodyParameters": [ {"Key": "BodyParam", "Value": "connection_body_param"
} ], "HeaderParameters": [ {"Key": "Header-Param", "Value": "connection_header_param"
} ], "QueryStringParameters": [ {"Key": "QueryParam", "Value": "connection_query_param"
} ] } } }
在此示例中,在HTTP任务和EventBridge连接中指定了重复的密钥。因此,使用连接中的值Step Functions覆盖HTTP任务中的值。以下代码片段显示了Step Functions发送给第三方API的HTTP请求。
POST /path?QueryParam=connection_query_param HTTP/1.1
Apikey: key_value
Content-Length: 79
Content-Type: application/json; charset=UTF-8
Header-Param: connection_header_param
Host: example.com
Range: bytes=0-262144
Request-Id: my_request_id
User-Agent: Amazon|StepFunctions|HttpInvoke|us-east-1
{"Job":"Software Engineer","Company":"AnyCompany","BodyParam":"connection_body_param"}
在请求正文上应用 URL-编码
默认情况下,Step Functions将请求正文作为JSON数据发送到API端点。如果您的第三方API提供程序需要form-urlencoded
请求正文,则必须为请求正文指定 URL-encoding。 Step Functions然后根据您选择的 URL-encod URL ing 选项自动对请求正文进行编码。
您可以使用Transform
字段指定 URL-encoding。此RequestBodyEncoding
字段包含指定您是否要对请求正文应用 URL-encoding 的字段。当您指定该RequestBodyEncoding
字段时,会在调用第三方之前Step Functions将您的JSONform-urlencoded
请求正文转换为请求正文API。您还必须将标content-type
头指定application/x-www-form-urlencoded
为APIs,因为接受URL编码的数据需要标头。content-type
为对请求正文中的数组进行编码,Step Functions 提供以下数组编码选项。
-
INDICES
:针对数组中的每个项重复使用一个键,并为该键附加一个方括号 [],以表示它是一个数组。此方括号包含数组元素的索引。添加索引可帮助您指定数组元素的顺序。Step Functions 默认使用此编码选项。例如,如果您的请求正文包含以下数组。
{"array": ["a","b","c","d"]}
Step Functions 会将此数组编码为以下字符串。
array[0]=a&array[1]=b&array[2]=c&array[3]=d
-
REPEAT
:针对数组中的每个项重复使用一个键。例如,如果您的请求正文包含以下数组。
{"array": ["a","b","c","d"]}
Step Functions 会将此数组编码为以下字符串。
array=a&array=b&array=c&array=d
-
COMMAS
:将键中的所有值编码为以逗号分隔的值列表。例如,如果您的请求正文包含以下数组。
{"array": ["a","b","c","d"]}
Step Functions 会将此数组编码为以下字符串。
array=a,b,c,d
-
BRACKETS
:针对数组中的每个项重复使用一个键,并为该键附加一个方括号 [],以表示它是一个数组。例如,如果您的请求正文包含以下数组。
{"array": ["a","b","c","d"]}
Step Functions 会将此数组编码为以下字符串。
array[]=a&array[]=b&array[]=c&array[]=d
IAM运行HTTP任务的权限
您的状态机执行角色必须具有states:InvokeHTTPEndpoint
、events:RetrieveConnectionCredentials
secretsmanager:GetSecretValue
、和secretsmanager:DescribeSecret
权限,HTTP任务才能调用第三方API。以下IAM策略示例授予您的状态机角色调用 Stripe 所需的最低权限APIs。此IAM策略还向状态机角色授予访问特定 EventBridge 连接的权限,包括存储在 Secrets Manager 中的此连接的密钥。
{ "Version": "2012-10-17", "Statement": [ { "Sid": "Statement1", "Effect": "Allow", "Action": "states:InvokeHTTPEndpoint", "Resource": "arn:aws:states:us-east-2:
123456789012
:stateMachine:myStateMachine
", "Condition": { "StringEquals": { "states:HTTPMethod": "GET" }, "StringLike": { "states:HTTPEndpoint": "https://api.stripe.com/*" } } }, { "Sid": "Statement2", "Effect": "Allow", "Action": [ "events:RetrieveConnectionCredentials", ], "Resource": "arn:aws:events:us-east-2:123456789012
:connection/oauth_connection/aeabd89e-d39c-4181-9486-9fe03e6f286a
" }, { "Sid": "Statement3", "Effect": "Allow", "Action": [ "secretsmanager:GetSecretValue", "secretsmanager:DescribeSecret" ], "Resource": "arn:aws:secretsmanager:*:*:secret:events!connection/*" } ] }
HTTP任务示例
以下状态机定义显示了包含Headers
、QueryParameters
Transform
、和RequestBody
参数的HTTP任务。该HTTP任务调用 Strip API e( https://api.stripe.com/v1/发票)来生成发票。该HTTP任务还使用URLINDICES
编码选项为请求正文指定-encoding。
确保您已创建 EventBridge 连接。以下示例显示了使用BASIC身份验证类型创建的连接。
{
"Type": "BASIC",
"AuthParameters": {
"BasicAuthParameters": {
"Password": "myPassword",
"Username": "myUsername"
},
}
}
记得更换 italicized
包含您的资源特定信息的文本。
{ "Comment": "A state machine that uses HTTP Task", "StartAt": "CreateInvoiceAPI", "States": { "CreateInvoiceAPI": { "Type": "Task", "Resource": "arn:aws:states:::http:invoke", "Parameters": { "ApiEndpoint": "https://api.stripe.com/v1/invoices", "Method": "POST", "Authentication": { "ConnectionArn": ""arn:aws:events:
us-east-2
:123456789012
:connection/Stripe/81210c42-8af1-456b-9c4a-6ff02fc664ac" }, "Headers": { "Content-Type": "application/x-www-form-urlencoded" }, "RequestBody": { "customer.$": "$.customer_id", "description": "Monthly subscription", "metadata": { "order_details": "monthly report data" } }, "Transform": { "RequestBodyEncoding": "URL_ENCODED", "RequestEncodingOptions": { "ArrayFormat": "INDICES" } } }, "Retry": [ { "ErrorEquals": [ "States.Http.StatusCode.429", "States.Http.StatusCode.503", "States.Http.StatusCode.504", "States.Http.StatusCode.502" ], "BackoffRate": 2, "IntervalSeconds": 1, "MaxAttempts": 3, "JitterStrategy": "FULL" } ], "Catch": [ { "ErrorEquals": [ "States.Http.StatusCode.404", "States.Http.StatusCode.400", "States.Http.StatusCode.401", "States.Http.StatusCode.409", "States.Http.StatusCode.500" ], "Comment": "Handle all non 200 ", "Next": "HandleInvoiceFailure" } ], "End": true } } }
要运行此状态机,请提供客户 ID 作为输入,如以下示例所示:
{
"customer_id": "1234567890"
}
以下示例显示了Step Functions发送到 Stripe 的HTTP请求API。
POST /v1/invoices HTTP/1.1
Authorization: Basic <base64 of username and password>
Content-Type: application/x-www-form-urlencoded
Host: api.stripe.com
Range: bytes=0-262144
Transfer-Encoding: chunked
User-Agent: Amazon|StepFunctions|HttpInvoke|us-east-1
description=Monthly%20subscription&metadata%5Border_details%5D=monthly%20report%20data&customer=1234567890
测试HTTP任务
您可以TestStateAPI通过控制台使用SDK,或 AWS CLI 来测试HTTP任务。以下过程介绍如何在Step Functions控制台 TestState API中使用。您可以迭代测试API请求、响应和身份验证的详细信息,直到您的HTTP任务按预期运行。
在Step Functions控制台中测试HTTP任务状态
-
选择创建状态机开始创建状态机,或者选择包含HTTP任务的现有状态机。
如果您要在现有状态机中测试任务,请参阅步骤 4。
-
在 Workflow Studio 中,直观地配置HTTP任务。设计模式或者选择代码模式,从本地开发环境中复制粘贴状态机定义。
-
在设计模式下,从 Workflow Studio 的 “检查器” 面板 面板中选择测试状态。
-
在测试状态对话框中,执行以下操作:
-
对于执行角色,选择一个执行角色来测试状态。如果您的角色没有足够的权限HTTP执行任务在工作流工作室中测试HTTP任务的角色,请参阅创建角色。
-
(可选)提供所选州测试所需的任何JSON输入。
-
对于检查级别,保留默认选择INFO。此级别显示API呼叫状态和状态输出。这对于快速检查API响应很有用。
-
选择开始测试。
-
如果测试成功,则状态输出会显示在测试状态对话框的右侧。如果测试失败,系统会显示错误。
在对话框的状态详细信息选项卡中,您可以看到状态定义和指向 EventBridge 连接的链接。
-
将检查级别更改为TRACE。此级别显示原始HTTP请求和响应,对于验证标头、查询参数和其他API特定详细信息非常有用。
-
选中显示密钥复选框。结合使用此设置 TRACE,您可以查看EventBridge连接插入的敏感数据,例如API密钥。您用于访问控制台的 IAM 用户身份必须具有执行
states:RevealSecrets
操作的权限。如果没有此权限,则在您开始测试时 Step Functions 会抛出访问遭拒错误。有关设置states:RevealSecrets
权限的 IAM 策略示例,请参阅IAM使用权限 TestState API。下图显示了成功HTTP完成的任务的测试。此状态的检查级别设置为TRACE。下图中的 “HTTP请求和响应” 选项卡显示了第三方API调用的结果。
-
选择开始测试。
-
如果测试成功,您可以在 “HTTP请求和响应” 选项卡下看到您的HTTP详细信息。
-
不支持的HTTP任务响应
如果返回的响应符合以下条件之一,则HTTP任务将失败并States.Runtime
出现错误:
-
响应包含
application/octet-stream
、image/*
、video/*
或audio/*
Content-Type 标头。 -
响应无法读取为有效字符串。例如,二进制数据或图像数据。