Step Functions ワークフローで HTTPS API を呼び出す

HTTP タスクは Task ワークフロー状態 ステートの一種で、ワークフロー内から HTTPS API を呼び出す際に使用できます。API は、Stripe や Salesforce などのサードパーティ SaaS アプリのようなパブリック API でもかまいません。また、Amazon Virtual Private Cloud 内の HTTPS ベースのアプリケーションなど、プライベート API を呼び出すこともできます。

認可とネットワーク接続のために、HTTP タスクでは EventBridge 接続が必要です。

HTTPS API を呼び出すには、Task ステートと arn:aws:states:::http:invoke リソースを使用します。次に、API の URL、使用するメソッド、接続の詳細など、API エンドポイント設定の詳細を指定します。

Workflow Studio を使用して HTTP タスクを含むステートマシンを構築すると、Workflow Studio は HTTP タスクの IAM ポリシーを含む実行ロールを自動的に生成します。詳細については、「Workflow Studio で HTTP タスクをテストするためのロール」を参照してください。

HTTP タスクの接続

HTTP タスクには、API プロバイダーの認証情報を安全に管理する EventBridge 接続が必要です。接続は、特定の API に接続する際に使用する認可方法と認証情報を定義します。Amazon Virtual Private Cloud (Amazon VPC) のプライベート API などのプライベート API に接続する場合は、接続を使用して安全な point-to-point ネットワーク接続を定義することもできます。接続を使用すると、API キーなどのシークレットをステートマシン定義にハードコーディングすることを避けることができます。EventBridge 接続は、Basic、OAuth、API キーの各認可スキームをサポートしています。

EventBridge 接続を作成するときは、認可情報とネットワーク接続の詳細を指定します。API での認可に必要なヘッダー、本文、およびクエリパラメータを含めることもできます。HTTP API を呼び出す HTTP タスクには、接続 ARN を含める必要があります。

接続を作成すると、EventBridge は AWS Secrets Manager にシークレットを作成します。このシークレットでは、EventBridge は接続パラメータと認可パラメータを暗号化された形式で保存します。接続を正常に作成または更新するには、Secrets Manager を使用するアクセス許可を持つ AWS アカウント を使用する必要があります。ステートマシンが EventBridge 接続にアクセスするために必要な IAM アクセス許可の詳細については、「HTTP タスクを実行するための IAM アクセス許可」を参照してください。

次の図では、Step Functions が EventBridge 接続を使用して HTTPS API コールの認可を処理する方法を示しています。EventBridge 接続では、HTTPS API プロバイダーの認証情報を管理します。EventBridge は、Secrets Manager にシークレットを作成し、接続と認可のパラメータを暗号化して保存します。プライベート API の場合、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:region:account-id:connection/Stripe/81210c42-8af1-456b-9c4a-6ff02fc664ac"
    },
    "Method": "GET"
  },
  "End": true
}

HTTP タスクフィールド

HTTP タスクの定義には以下のフィールドが含まれます。

EventBridge 接続データと HTTP タスク定義データをマージする

HTTP タスクを呼び出すと、EventBridge 接続と HTTP タスク定義のデータを指定できます。このデータには Headers、QueryParameters、および RequestBody パラメータが含まれます。Step Functions は、リクエスト本文が文字列で接続本文のパラメータが空でない場合を除き、HTTPS API を呼び出す前に、リクエスト本文と接続本文パラメータをマージします。この場合、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 エンコードします。

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

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

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

ステートマシンの実行ロールには、HTTP タスクが HTTPS API を呼び出すために、次のアクセス許可が必要です。

次のIAMポリシーの例では、Stripe APIを呼び出すために必要な最小特権をステートマシンのロールに付与しています。このIAMポリシーは、Secrets Manager に保存されているこの接続のシークレットを含め、特定のEventBridge 接続にアクセスするアクセス許可をステートマシンのロールに付与します。

HTTP タスク例

次のステートマシン定義は Headers、QueryParameters、Transform、および RequestBody パラメータを含む HTTP タスクを示しています。HTTP タスクは Stripe API (https://api.stripe.com/v1/invoices) を呼び出して請求書を生成します。HTTP タスクでは、INDICES エンコーディングオプションを使用してリクエスト本文の URL エンコーディングも指定します。

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

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

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

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

返された応答が次のいずれかの条件に当てはまる場合、HTTP タスクは States.Runtime エラーで失敗します。

接続エラー

ワークフロー実行の進行中、指定された API への接続時に EventBridge で問題が発生した場合、Step Functions はワークフローでエラーをスローします。接続エラーには Events.ConnectionResource. というプレフィックスが付きます。

これらのエラーには以下が含まれます。