在 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任务的定义中包括以下字段。

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以加密形式存储连接和授权参数。

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

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

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

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

以下示例在HTTP任务和EventBridge连接中设置HeadersQueryParameters、和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 提供以下数组编码选项。

IAM运行HTTP任务的权限

您的状态机执行角色必须具有states:InvokeHTTPEndpoint、events: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任务示例

以下状态机定义显示了包含Headers、QueryParametersTransform、和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任务按预期运行。

不支持的HTTP任务响应

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