在 Step Functions 工作流程中呼叫 HTTPS APIs

HTTP 任務是一種任務工作流程狀態狀態，可讓您在工作流程中呼叫 HTTPS API。API 可以是公有的，例如第三方 SaaS 應用程式，例如 Stripe 或 Salesforce。您也可以呼叫私有 API，例如 Amazon Virtual Private Cloud 中的 HTTPS 應用程式。

對於授權和網路連線，HTTP 任務需要 EventBridge 連線。

若要呼叫 HTTPS API，請將任務狀態與 arn:aws:states:::http:invoke 資源搭配使用。然後，提供 API 端點組態詳細資訊，例如 API URL、您要使用的方法，以及連線詳細資訊。

如果您使用 Workflow Studio 建置包含 HTTP 任務的狀態機器，Workflow Studio 會自動產生具有 HTTP 任務IAM政策的執行角色。如需詳細資訊，請參閱在 Workflow Studio 中測試 HTTP 任務的角色。

HTTP 任務的連線能力

HTTP 任務需要 EventBridge 連線，可安全地管理 API 提供者的身分驗證憑證。連線定義用於連線至指定 API 的授權方法和憑證。如果您要連線至私有 API，例如 Amazon Virtual Private Cloud (Amazon VPC) 中的私有 API，您也可以使用連線來定義安全的point-to-point網路連線。使用連線可協助您避免將 API 金鑰等硬式編碼秘密納入狀態機器定義。EventBridge 連線支援基本、OAuth 和 API 金鑰授權機制。

當您建立 EventBridge 連線時，請提供授權和網路連線詳細資訊。您也可以包含使用 API 授權所需的標頭、內文和查詢參數。您必須在呼叫 HTTPS API 的任何 HTTP 任務中包含連線 ARN。

當您建立連線時，EventBridge 會在 中建立秘密 AWS Secrets Manager。在此秘密中，EventBridge 會以加密形式存放連線和授權參數。若要成功建立或更新連線，您必須使用具有使用 Secrets Manager AWS 帳戶 許可的 。如需狀態機器存取 EventBridge 連線所需IAM許可的詳細資訊，請參閱 執行 HTTP 任務的 IAM 許可。

下圖顯示如何使用 EventBridge連線Step Functions處理 HTTPS API 呼叫的授權。EventBridge 連線會管理 HTTPS API 提供者的登入資料。 會在 中EventBridge建立秘密Secrets Manager，以加密的形式存放連線和授權參數。如果是私有 APIs，EventBridge 也會存放網路連線組態。

HTTP 任務定義

ASL 定義代表具有 http:invoke 資源的 HTTP 任務。下列 HTTP 任務定義會叫用公有 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: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 任務中的值。

下列清單說明在呼叫 HTTPS API Step Functions 之前如何合併資料：

下列範例會設定 HTTP Headers任務和EventBridge連線中的 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傳送至 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|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 編碼選項，自動對請求內文進行 URL 編碼。

您可以使用 Transform 欄位指定 URL 編碼。此欄位包含 RequestBodyEncoding 欄位，可指定是否要將 URL 編碼套用至請求內文。當您指定 RequestBodyEncoding 欄位時， 會在呼叫 HTTPS API 之前，將您的 JSON 請求內文Step Functions轉換為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 任務範例

下列狀態機器定義顯示 HTTP 任務，其中包含 Headers、Transform、 QueryParameters和 RequestBody 參數。HTTP 任務會呼叫 Stripe API，https：//https://api.stripe.com/v1/invoices 來產生發票。HTTP 任務也會使用編碼選項指定請求內文的 URL INDICES編碼。

請確定您已建立EventBridge連線。下列範例顯示使用 BASIC 驗證類型建立的連線。

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

您可以透過 主控台、 SDK 或 使用 TestState API AWS CLI 來測試 HTTP 任務。下列程序說明如何在 Step Functions主控台中使用 TestState API。您可以反覆測試 API 請求、回應和身分驗證詳細資訊，直到 HTTP 任務如預期般運作為止。

不支援的 HTTP 任務回應

如果傳回的回應符合下列其中一個條件，則 HTTP 任務會失敗並出現States.Runtime錯誤：

連線錯誤

如果在工作流程執行期間連線至指定的 API 時 EventBridge 遇到問題，Step Functions 會在工作流程中引發錯誤。連線錯誤字首為 Events.ConnectionResource.。

這些錯誤包括：