调用第三方 API

HTTP 任务是一种 Task 状态，可让您在工作流中调用任何公共第三方 API，例如 Salesforce 和 Stripe。要调用第三方 API，请配合使用 Task 状态与 arn:aws:states:::http:invoke 资源。然后，提供 API 端点配置详细信息，例如 API URL、您要使用的方法和身份验证详细信息。

如果您使用 Workflow Studio 构建包含 HTTP 任务的状态机，则 Workflow Studio 会自动为 HTTP 任务生成一个带 IAM 策略的执行角色。有关更多信息，请参阅在 Workflow Studio 中测试 HTTP 任务的角色。

HTTP 任务定义

ASL 定义表示具有 http:invoke 资源的 HTTP 任务。以下 HTTP 任务定义调用了一个会返回所有客户列表的 Stripe API。

"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 所需的标头、正文和查询参数。您必须在调用第三方 API 的任何 HTTP 任务中包含连接 ARN。

当您创建连接并添加授权参数时， EventBridge 会在中创建密钥 Amazon Secrets Manager。在此密钥中，以加密形式 EventBridge 存储连接和授权参数。要成功创建或更新连接，必须使用有权使用 S Amazon Web Services 账户 ecrets Manager 的。有关状态机访问 EventBridge 连接所需的IAM权限的更多信息，请参阅运行 HTTP 任务的 IAM 权限。

下图显示了 Step Functions 如何使用 EventBridge 连接处理第三方 API 调用的身份验证。

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

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

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

以下列表说明了在调用第三方 API 之前 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 编码。Step Functions 然后会根据您选择的 URL 编码选项自动对请求正文进行 URL 编码。

您可以使用 Transform 字段指定 URL 编码。此字段包含 RequestBodyEncoding 字段，后者用于指定您是否要为请求正文应用 URL 编码。当您指定 RequestBodyEncoding 字段时，Step Functions 会在调用第三方 API 之前，将您的 JSON 请求正文转换为 form-urlencoded 请求正文。您还必须将 content-type 标头指定为 application/x-www-form-urlencoded，因为接受 URL 编码数据的 API 需要 content-type 标头。

为对请求正文中的数组进行编码，Step Functions 提供以下数组编码选项。

运行 HTTP 任务的 IAM 权限

您的状态机执行角色必须具有 states:InvokeHTTPEndpoint、events:RetrieveConnectionCredentials、secretsmanager:GetSecretValue 和 secretsmanager:DescribeSecret 权限，HTTP 任务才能调用第三方 API。下面的 IAM 策略示例授予状态机角色调用 Stripe API 所需的最低权限。此 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 任务调用 Stripe API https://api.stripe.com/v1/invoices 来生成发票。该 HTTP 任务还使用 INDICES 编码选项为请求正文指定 URL 编码。

确保您已创建 EventBridge 连接。以下示例显示了使用基本授权类型创建的连接。

{
    "Type": "BASIC",
    "AuthParameters": { 
        "BasicAuthParameters": { 
            "Password": "myPassword",
            "Username": "myUsername"
         },
    }
}

切记用特定资源信息替换斜体文本。

{
  "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 API 的 HTTP 请求。

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 任务

您可以通过控制台、软件开发工具包或使用TestState该 API Amazon CLI 来测试 HTTP 任务。以下过程介绍如何在Step Functions控制台中使用 TestState API。您可以迭代测试 API 请求、响应和身份验证详细信息，直到 HTTP 任务按预期运行。

不支持的 HTTP 任务响应

如果返回的响应满足以下任意条件，则 HTTP 任务失败并显示 States.Runtime 错误：