Step Functions ワークフローAPIsでサードパーティーを呼び出す

HTTP タスクは、ワークフローで Salesforce や Stripe APIなどのパブリックでサードパーティーの を呼び出すことができるタスクワークフローの状態状態の一種です。サードパーティーの を呼び出すにはAPI、 arn:aws:states:::http:invokeリソースでタスク状態を使用します。次に、 、使用するメソッドAPIURL、認証の詳細など、APIエンドポイント設定の詳細を指定します。

Workflow Studio を使用してHTTPタスクを含むステートマシンを構築する場合、Workflow Studio はHTTPタスクのIAMポリシーを含む実行ロールを自動的に生成します。詳細については、「Workflow Studio で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 保存します。接続を正常に作成または更新するには、Secrets Manager を使用するアクセス許可 AWS アカウント を持つ を使用する必要があります。ステートマシンが EventBridge 接続にアクセスするために必要なアクセスIAM許可の詳細については、「」を参照してくださいIAM HTTPタスクを実行するための アクセス許可。

次の図は、 が EventBridge接続を使用してサードパーティーAPI呼び出しの認証Step Functionsを処理する方法を示しています。サードパーティーAPIプロバイダーの認証情報を管理するEventBridge接続。 EventBridgeは にシークレットを作成してSecrets Manager、接続パラメータと承認パラメータを暗号化された形式で保存します。

EventBridge 接続とHTTPタスク定義データのマージ

HTTP タスクを呼び出すときに、EventBridge接続とHTTPタスク定義でデータを指定できます。このデータには Headers、QueryParameters、および RequestBody パラメータが含まれます。サードパーティーの を呼び出す前にAPI、Step Functions はリクエストボディが文字列で、接続ボディパラメータが空でない場合を除き、すべてのケースでリクエストボディを接続ボディパラメータとマージします。この場合、HTTPタスクは States.Runtime エラーで失敗します。

HTTP タスク定義とEventBridge接続で重複するキーが指定されている場合、 はHTTPタスクの値を接続の値でStep Functions上書きします。

次のリストでは、サードパーティーの を呼び出す前に がデータをStep Functionsマージする方法について説明しますAPI。

次の例ではHeaders、HTTPタスクと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接続で重複するキーが指定されています。したがって、 は HTTP タスクの値を接続の値でStep Functions上書きします。次のコードスニペットは、 がサードパーティーの Step Functionsに送信するHTTPリクエストを示しています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エンコードを適用する

デフォルトでは、 はリクエスト本文をJSONデータとしてAPIエンドポイントStep Functionsに送信します。サードパーティーAPIプロバイダーがform-urlencodedリクエスト本文を必要とする場合は、リクエスト本文に URLエンコードを指定する必要があります。 Step Functions は、選択した URLエンコードオプションに基づいてリクエスト本文を自動的にURLエンコードします。

Transform フィールドを使用して URLエンコードを指定します。このフィールドには、リクエストボディに URLエンコードを適用するかどうかを指定する RequestBodyEncodingフィールドが含まれます。RequestBodyEncoding フィールドを指定すると、 はサードパーティーの を呼び出す前にJSONリクエストボディをform-urlencodedリクエストボディStep Functionsに変換しますAPI。また、 エンコードされたデータを受け入れる APIs は content-typeヘッダーを想定application/x-www-form-urlencodedしているため、 URLcontent-typeヘッダーを として指定する必要があります。

リクエスト本文の配列をエンコードするために、Step Functions では以下の配列エンコードオプションが用意されています。

IAM HTTPタスクを実行するための アクセス許可

ステートマシンの実行ロールにはstates:InvokeHTTPEndpoint、 HTTP タスクがサードパーティーの を呼び出すための events:RetrieveConnectionCredentialssecretsmanager:GetSecretValue、、、および アクセスsecretsmanager:DescribeSecret許可が必要ですAPI。次のIAMポリシー例では、Stripe を呼び出すために必要な最小限の権限をステートマシンロールに付与しますAPIs。このIAMポリシーは、Secrets Manager に保存されているこの EventBridge 接続のシークレットを含む、特定の接続にアクセスするアクセス許可をステートマシンロールに付与します。

{
    "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 タスクはストライプのAPI https://api.stripe.com/v1/請求書を呼び出して請求書を生成します。HTTP タスクでは、エンコードオプションを使用してリクエスト本文の URLINDICESエンコードも指定します。

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"
}

次の例は、 が Stripe Step Functionsに送信する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 タスクのテスト

コンソール、、SDKまたは TestStateAPIを使用してHTTPタスクを AWS CLI テストできます。次の手順では、 Step Functionsコンソールで TestState APIを使用する方法について説明します。HTTP タスクが期待どおりに動作するまで、APIリクエスト、レスポンス、認証の詳細を繰り返しテストできます。

サポートされていないHTTPタスクレスポンス

返されたレスポンスに対して次のいずれかの条件が true の場合、HTTPタスクは States.Runtime エラーで失敗します。