在 Step Functions 工作流程APIs中致电第三方 - AWS Step Functions

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

在 Step Functions 工作流程APIs中致电第三方

HTTP任务是一种任务工作流状态状态,允许您在工作流程中致电任何公众API、第三方,例如 Salesforce 和 Stripe。要致电第三方API,请使用arn:aws:states:::http:invoke资源的 “任务” 状态。然后,提供API端点配置详细信息,例如您要使用的方法和身份验证详细信息。API URL

如果你使用 Workflow Studio 来构建包含HTTP任务的状态机,则 Workflow Studio 会自动生成一个执行角色 IAM HTTP任务的策略。有关更多信息,请参阅 在工作流工作室中测试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(必填)

包含ApiEndpointMethod、和ConnectionArn字段,提供有关API您要呼叫的第三方的信息。 Parameters还包含可选字段,例如HeadersQueryParameters

您可以像在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钥)硬编码到状态机定义中。在连接中,您还可以指定 HeadersQueryParametersRequestBody 参数。

创建 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-AgentRange、和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(可选)

包含 RequestBodyEncodingRequestEncodingOptions 字段。默认情况下,Step Functions 将请求正文作为JSON数据发送到API端点。

如果您的API提供程序接受form-urlencoded请求正文,请使用该Transform字段为请求正文指定 URL-encoding。您还必须将标content-type题指定为application/x-www-form-urlencoded。Step Functions 然后自动对你的请求正文进行 URL-编码。

RequestBodyEncoding

指定请求正文的URL编码。您可以指定以下值之一:NONEURL_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 的。有关更多信息 IAM 您的状态机访问 EventBridge 连接所需的权限,请参阅IAM运行HTTP任务的权限

下图显示了操作方法 Step Functions 使用处理第三方呼API叫的身份验证 EventBridge 连接。这些区域有:EventBridge 用于管理第三方API提供商凭证的连接。EventBridge 在中创建了一个秘密 Secrets Manager 以加密形式存储连接和授权参数。

该图显示了 Step Functi EventBridge ons 如何使用连接调用HTTP端点。

合并 EventBridge 连接和HTTP任务定义数据

当你调用HTTP任务时,你可以在你的任务中指定数据 EventBridge 连接和您的HTTP任务定义。此数据包括 HeadersQueryParametersRequestBody 参数。在调用第三方之前API,Step Functions 会在所有情况下将请求正文与连接正文参数合并,除非您的请求正文为字符串且连接正文参数为非空。在这种情况下,HTTP任务因States.Runtime错误而失败。

如果在HTTP任务定义中指定了任何重复的密钥,EventBridge 连接,Step Functions 用连接中的值覆盖HTTP任务中的值。

以下列表描述了如何 Step Functions 在致电第三方API之前合并数据:

  • 标题 — Step Functions 将您在连接中指定的任何标题添加到HTTP任务Headers字段的标题中。如果标头键之间存在冲突,Step Functions 使用连接中为这些标头指定的值。例如,如果您在HTTP任务定义和任务定义中都指定了content-type标题 EventBridge 连接,Step Functions 使用连接中指定的content-type标头值。

  • 查询参数 — Step Functions 将您在连接中指定的任何查询参数添加到HTTP任务QueryParameters字段的查询参数中。如果查询参数键之间存在冲突,Step Functions 使用连接中为这些查询参数指定的值。例如,如果您在HTTP任务定义和任务定义中都指定了maxItems查询参数 EventBridge 连接,Step Functions 使用连接中指定的maxItems查询参数值。

  • 主体参数

    • Step Functions 将连接中指定的任何请求正文值添加到HTTP任务RequestBody字段的请求正文中。如果请求正文密钥之间存在冲突,Step Functions 使用连接中为请求正文指定的值。例如,假设您在任务定义和 “HTTP任务” 定义RequestBody中都指定了一个Mode字段 EventBridge 连接。Step Functions 使用您在连接中指定的Mode字段值。

    • 如果您将请求正文指定为字符串而不是JSON对象,并且 EventBridge 连接还包含请求正文,Step Functions 无法合并在这两个地方指定的请求正文。它因States.Runtime错误而使HTTP任务失败。

    Step Functions 在请求正文完成合并后,应用所有转换并序列化请求正文。

以下示例在HTTP任务和中设置HeadersQueryParameters、和RequestBody字段 EventBridge 连接。

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任务中的值。以下代码片段显示了以下HTTP请求 Step Functions 发送给第三方API。

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:InvokeHTTPEndpointevents:RetrieveConnectionCredentialssecretsmanager: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任务示例

以下状态机定义显示了包含HeadersQueryParametersTransform、和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" }

以下示例显示了以下HTTP请求 Step Functions 发送到 Stripe 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任务。以下过程描述了如何在 TestState API中使用 Step Functions console。您可以迭代测试API请求、响应和身份验证的详细信息,直到您的HTTP任务按预期运行。

在以下位置测试HTTP任务状态 Step Functions Console
  1. 打开 Step Functions 控制台

  2. 选择 “创建状态机” 开始创建状态机,或者选择包含HTTP任务的现有状态机。

    如果您要在现有状态机中测试任务,请参阅步骤 4。

  3. 在 Workflow Studio 中,直观地配置HTTP任务。设计模式或者选择代码模式,从本地开发环境中复制粘贴状态机定义。

  4. 在设计模式下,从 Workflow Studio 的 “检查器” 面板 面板中选择测试状态

  5. 测试状态对话框中,执行以下操作:

    1. 对于执行角色,选择一个执行角色来测试状态。如果您的角色没有足够的权限HTTP执行任务在工作流工作室中测试HTTP任务的角色,请参阅创建角色。

    2. (可选)提供所选州测试所需的任何JSON输入。

    3. 对于检查级别,保留默认选择INFO。此级别显示API呼叫的状态和状态输出。这对于快速检查API响应很有用。

    4. 选择开始测试

    5. 如果测试成功,则状态输出会显示在测试状态对话框的右侧。如果测试失败,系统会显示错误。

      在对话框的 “州详细信息” 选项卡中,您可以看到状态定义和指向 EventBridge 连接

    6. 检查级别更改为TRACE。此级别显示原始HTTP请求和响应,对于验证标头、查询参数和其他API特定详细信息非常有用。

    7. 选中显示密钥复选框。结合使用此设置 TRACE,您可以查看敏感数据 EventBridge 连接插件,例如API密钥。这些区域有:IAM 用于访问控制台的用户身份必须具有执行states:RevealSecrets操作的权限。如果没有此许可,Step Functions 开始测试时会抛出拒绝访问错误。举个例子 IAM 设置states:RevealSecrets权限的策略,请参阅IAM 使用权限 TestState API

      下图显示了成功HTTP完成的任务的测试。此状态的检查级别设置为TRACE。下图中的 “HTTP请求和响应” 选项卡显示了第三方API调用的结果。

      通过TRACE关卡测试的选定状态的输出。
    8. 选择开始测试

    9. 如果测试成功,您可以在 “HTTP请求和响应” 选项卡下看到您的HTTP详细信息。

不支持的HTTP任务响应

如果返回的响应符合以下条件之一,则HTTP任务将失败并States.Runtime出现错误:

  • 响应包含 application/octet-streamimage/*video/*audio/* Content-Type 标头。

  • 响应无法读取为有效字符串。例如,二进制数据或图像数据。