在 Step Functions 工作流程 APIs 中调用 HT

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

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

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

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

HTTP 任务的连接性

HTTP 任务需要EventBridge连接，该连接可以安全地管理 API 提供商的身份验证凭证。连接定义了用于连接给定 API 的授权方法和证书。如果您要连接私有 API，例如亚马逊虚拟私有云 (Amazon VPC) 中的私有 API，则也可以使用该连接来定义安全的 point-to-point网络连接。使用连接可以帮助您避免将密钥（例如 API 密钥）硬编码到状态机定义中。 EventBridge 连接支持基本 OAuth、和 API 密钥授权方案。

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

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

下图显示了操作方法 Step Functions 使用处理对 HTTPS API 调用的授权 EventBridge 连接。这些区域有：EventBridge 连接管理 HTTPS API 提供商的凭证。EventBridge 在中创建了一个秘密 Secrets Manager 以加密形式存储连接和授权参数。如果是私有的 APIs， EventBridge 还会存储网络连接配置。

HTTP 任务定义

ASL 定义表示具有 http:invoke 资源的 HTTP 任务。以下 HTTP 任务定义调用了一个公共 Stripe API，该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:us-east-2:123456789012: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 任务中的值。

以下列表描述了操作方法 Step Functions 在调用 HTTPS API 之前合并数据：

以下示例在 HTTP 任务和 HTTP 任务中设置QueryParameters、和RequestBody字段 Headers 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 发送到 HTTPS 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 端点。如果您的 HTTPS API 提供商需要form-urlencoded请求正文，则必须为请求正文指定 URL 编码。Step Functions 然后根据您选择的 URL 编码选项自动对请求正文进行网址编码。

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

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

运行 HTTP 任务的 IAM 权限

您的状态机执行角色必须具有以下权限才能让 HTTP 任务调用 HTTPS 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 任务调用 Stripe API（ https://api.stripe.com/v1/发票）来生成发票。该 HTTP 任务还使用 INDICES 编码选项为请求正文指定 URL 编码。

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

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

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

不支持的 HTTP 任务响应

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

连接错误

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

这些错误包括：