在 Step Functions 工作流中调用 HTTPS API

HTTP Task 是一种 Task 工作流程状态状态，可用于在工作流中调用 HTTPS API。API 可以是公开的，例如 Stripe 或 Salesforce 等第三方 SaaS 应用程序所提供的 API。您也可以调用私有 API，例如 Amazon Virtual Private Cloud 中基于 HTTPS 的应用程序所提供的 API。

为了进行授权和网络连接，HTTP Task 需要 EventBridge 连接。

要调用 HTTPS API，请配合使用 Task 状态与 arn:aws:states:::http:invoke 资源。然后，提供 API 端点配置详细信息，例如 API URL、您要使用的方法和连接详细信息。

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

HTTP Task 的连接性

HTTP 任务需要 EventBridge 连接，该连接可以安全地管理 API 提供程序的身份验证凭证。连接定义了在连接到给定 API 时使用的授权方法和凭证。如果要连接到私有 API [如 Amazon Virtual Private Cloud（Amazon VPC）中的私有 API]，则还可以使用该连接来定义安全的点对点网络连接。使用连接可以帮助您避免将密钥（例如 API 密钥）硬编码到状态机定义中。EventBridge 连接支持基本授权、OAuth 授权和 API 密钥授权方案。

创建 EventBridge 连接时，您需要提供授权和网络连接详细信息。您还可以包含授权 API 所需的标头、正文和查询参数。您必须在调用 HTTPS API 的任何 HTTP Task 中包含连接 ARN。

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

下图显示了 Step Functions 如何使用 EventBridge 连接处理 HTTPS API 调用的授权。EventBridge 连接管理 HTTPS API 提供程序的凭证。EventBridge 在 Secrets Manager 中创建密钥，从而以加密形式存储连接和授权参数。如果是私有 API，EventBridge 还会存储网络连接配置。

HTTP 任务定义

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

"Call HTTPS API": {
  "Type": "Task",
  "Resource": "arn:aws:states:::http:invoke",
  "Parameters": {
    "ApiEndpoint": "https://api.stripe.com/v1/customers",
    "Authentication": {
      "ConnectionArn": "arn:aws:events:region:account-id:connection/Stripe/81210c42-8af1-456b-9c4a-6ff02fc664ac"
    },
    "Method": "GET"
  },
  "End": true
}

HTTP 任务字段

HTTP 任务的定义中包括以下字段。

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

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

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

以下列表说明了在调用 HTTPS 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:region:account-id: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 发送到 HTTPS 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|region

{"Job":"Software Engineer","Company":"AnyCompany","BodyParam":"connection_body_param"}

在请求正文上应用 URL 编码

默认情况下，Step Functions 会将请求正文作为 JSON 数据发送到 API 端点。如果您的 HTTPS API 提供程序需要 form-urlencoded 请求正文，则您必须为请求正文指定 URL 编码。Step Functions 然后会根据您选择的 URL 编码选项自动对请求正文进行 URL 编码。

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

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

运行 HTTP 任务的 IAM 权限

您的状态机执行角色必须具有以下权限，HTTP Task 才能调用 HTTPS API。

下面的 IAM 策略示例授予状态机角色调用 Stripe API 所需的最低权限。此外，此 IAM 策略还向状态机角色授予访问特定 EventBridge 连接的权限，包括访问存储在 Secrets Manager 中的该连接的密钥。

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:region:account-id: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|region

description=Monthly%20subscription&metadata%5Border_details%5D=monthly%20report%20data&customer=1234567890

测试 HTTP 任务

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

不支持的 HTTP 任务响应

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

连接错误

如果 EventBridge 在工作流执行期间连接到指定 API 时遇到问题，Step Functions 会在您的工作流中引发错误。连接错误的前缀为 Events.ConnectionResource.。

这些错误包括：