Step APIs を呼び出す

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

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

HTTPS API を呼び出すには、 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 での認可に必要なヘッダー、本文、およびクエリパラメータを含めることもできます。HTTPS API を呼び出す HTTP タスクには、接続 ARN を含める必要があります。

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

次の図は、 が EventBridge接続を使用して HTTPS API コールの認可Step Functionsを処理する方法を示しています。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 タスクと 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: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 タスクの値を接続の値で上書きします。次のコードスニペットは、 が HTTPS API Step Functionsに送信する 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 エンコードします。

URL エンコードは Transform を使用してフィールドを指定します。このフィールドには、リクエスト本文に URL エンコードを適用するかどうかを指定する RequestBodyEncoding フィールドが含まれます。RequestBodyEncoding フィールドを指定すると、 は HTTPS API を呼び出す前に JSON リクエスト本文をform-urlencodedリクエスト本文Step Functionsに変換します。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 接続にアクセスするアクセス許可をステートマシンのロールに付与します。

{
    "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/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: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 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|us-east-1

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.。

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