Step Functions を使用した API Gateway の呼び出し - AWS Step Functions

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

Step Functions を使用した API Gateway の呼び出し

Step Functions、特定のAWS『Amazon ステートメント言語』の「」を参照してください。の使用方法の詳細については、「」を参照してください。AWS Step Functionsとの統合に関する詳細については、以下を参照してください。

最適化 API Gateway の統合と API Gateway の違いAWSSDK統合
  • apigateway:invoke:には同等のものはありません。AWSSDK サービスの統合 代わりに、最適化 API Gateway サービスは API Gateway エンドポイントを直接呼び出します。

Amazon API Gateway を使用して、HTTP API と REST API を作成、発行、保守、モニタリングします。API Gateway と統合するには、TaskステートStep Functions。コードを書いたり、他のインフラストラクチャに依存したりすることなく、API Gateway HTTP または API Gateway REST エンドポイントを直接呼び出すことができます。ATask状態定義には、API 呼び出しに必要なすべての情報が含まれています。異なる認証方法を選択することもできます。

注記

Step Functions は、API Gateway を介して HTTP エンドポイントを呼び出す機能をサポートしていますが、現在、汎用 HTTP エンドポイントを呼び出す機能はサポートしていません。

API Gateway 機能のサポート

Step Functions API Gateway 統合は、一部の API Gateway 機能をサポートしていますが、一部の API ゲートウェイ機能をサポートしていません。サポートされている機能のより詳細なリストについては、以下を参照してください。

  • Step Functions API Gateway REST API と API Gateway HTTP API 統合の両方でサポートされています。

    • オーソライザー: IAM (署名バージョン 4)、認証なし、Lambda Authorizer(リクエストパラメータベースとカスタムヘッダー付きトークンベース)

    • API タイプ: リージョン別

    • API 管理: API Gateway API ドメイン名、API ステージ、パス、クエリパラメータ、リクエストボディ

  • Step Functions API Gateway HTTP API 統合でサポートされますが、Step Functions API Gateway REST API 統合はサポートされません。

    • エッジ最適化 API

  • Step Functions API Gateway 統合ではサポートされていません:

    • オーソライザー: Amazon Cognito、ネイティブオープン ID Connect/OAuth 2.0、トークンベースの Lambda 認証用の認証ヘッダー

    • API タイプ: プライベート

    • API 管理: カスタムドメイン名

API Gateway とその HTTP API API の詳細については、以下を参照してください。

リクエストの形式

作成すると、Task状態定義では、Step Functions はパラメーターを検証し、呼び出しを実行するのに必要な URL を構築してから API を呼び出します。レスポンスには、HTTP ステータスコード、ヘッダー、レスポンス本文が含まれます。リクエスト形式には、必須およびオプションの両方のパラメータがあります。

必須のリクエストパラメータ

  • ApiEndpoint

    • タイプ: String

    • API Gateway URL のホスト名。形式は <API ID>.execute-api.<region>.amazonaws.com です。

      API ID には、次の英数字の組み合わせのみを使用できます。0123456789abcdefghijklmnopqrstuvwxyz

  • Method

    • タイプ: Enum

    • HTTP メソッド。次のいずれかである必要があります。

      • GET

      • POST

      • PUT

      • DELETE

      • PATCH

      • HEAD

      • OPTIONS

任意指定のリクエストパラメータ

  • Headers

    • タイプ: JSON

    • HTTP ヘッダーは、同じキーに関連付けられた値のリストを許可します。

  • Stage

    • タイプ: String

    • API Gateway で API がデプロイされるステージの名前。使用する HTTP API ではオプションです。$defaultステージ。

  • Path

    • タイプ: String

    • API エンドポイントの後に付加されるパスパラメータ。

  • QueryParameters

    • タイプ: JSON

    • クエリ文字列では、同じキーに関連付けられた値のリストを使用できます。

  • RequestBody

    • 型: JSON または String

    • HTTP リクエスト本文。そのタイプは、いずれかです。JSONオブジェクトまたはStringRequestBodyでサポートされるのは、PATCH,POST, およびPUTHTTP メソッド。

  • AllowNullValues

    • タイプ: BOOLEAN

    • の設定AllowNullValuestrueを使用すると、次のようなnull値を渡すことができます。

      { "NewPet": { "type": "turtle", "price": 123, "name": null } }
  • AuthType

    • タイプ: JSON

    • 認証方法。デフォルトの方法はNO_AUTH。指定できる値は次のとおりです。

      • NO_AUTH

      • IAM_ROLE

      • RESOURCE_POLICY

      「」を参照してください。認証と認可詳細については.

注記

セキュリティ上の考慮事項として、次の HTTP ヘッダーキーは現在許可されていません。

  • 接頭辞が付くものX-Forwarded,X-AmzまたはX-Amzn

  • Authorization

  • Connection

  • Content-md5

  • Expect

  • Host

  • Max-Forwards

  • Proxy-Authenticate

  • Server

  • TE

  • Transfer-Encoding

  • Trailer

  • Upgrade

  • Via

  • Www-Authenticate

以下のコード例は、Step Functions を使用して API Gateway を呼び出す方法を示しています。

{ "Type": "Task", "Resource":"arn:aws:states:::apigateway:invoke", "Parameters": { "ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com", "Method": "GET", "Headers": { "key": ["value1", "value2"] }, "Stage": "prod", "Path": "bills", "QueryParameters": { "billId": ["123456"] }, "RequestBody": {}, "AuthType": "NO_AUTH" } }

認証と認可

次の認証方法を使用できます。

  • 許可なし: 認証メソッドなしで API を直接呼び出します。

  • IAM ロール: この方法では、Step Functions はステートマシンの役割を引き受け、署名バージョン 4(SigV4) を呼び出し、API を呼び出します。

  • リソースポリシー: Step Functions、リクエストを認証し、API を呼び出します。次の項目を指定する API にリソースポリシーをアタッチする必要があります。

    1. API Gateway を呼び出すステートマシン。

      重要

      ステートマシンへのアクセスを制限するには、ステートマシンを指定する必要があります。そうしないと、API Gateway リクエストを認証するステートマシンがリソースポリシー認証へのアクセスが許可されます。

    2. そのStep Functions、API Gatewayを呼び出すサービスです。"Service": "states.amazonaws.com"

    3. アクセス対象のリソースです。以下を含みます。

      • -リージョン

      • -account-id指定されたリージョンで。

      • -アピイド

      • -ステージ名

      • -HTTP-VERB(メソッド)。

      • -リソースパス指定子

    リソースポリシーの例については、「」を参照してください。Step Functions と API Gateway の IAM ポリシー

    リソースの形式の詳細については、「」を参照してください。API Gateway で API を実行するためのアクセス許可のリソース形式『API Gateway 開発者ガイド』を参照してください。

    注記

    リソースポリシーは REST API でのみサポートされます。

サービス統合パターン

API Gateway 統合では、次の 2 つのサービス統合パターンがサポートされます

  • リクエストレスポンスデフォルトの統合パターンです。これは、Step Functions、HTTPレスポンスを受け取った直後に次のステップに進むことができます。

  • タスクトークンのコールバックまで待機する(.waitForTaskToken)。これは、ペイロードとともにタストークンが返されるまで待機します。♪.waitForTaskTokenパターンの末尾に.WaitForTaskToken を追加します。リソースフィールドには、次の例のように、タスク定義の「」を参照してください。

    { "Type": "Task", "Resource":"arn:aws:states:::apigateway:invoke.waitForTaskToken", "Parameters": { "ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com", "Method": "POST", "Headers": { "TaskToken.$": "States.Array($$.Task.Token)" }, "Stage": "prod", "Path": "bills/add", "QueryParameters": {}, "RequestBody": { "billId": "my-new-bill" }, "AuthType": "IAM_AUTH" } }

出力形式

次の出力パラメータが用意されています。

名前 タイプ 説明
ResponseBody JSON 、、または String API コールのレスポンス本文。
Headers JSON レスポンスヘッダー。
StatusCode Integer レスポンスの HTTP ステータスコード。
StatusText String レスポンスのステータス・テキスト。

レスポンスの例:

{ "ResponseBody": { "myBills": [] }, "Headers": { "key": ["value1", "value2"] }, "StatusCode": 200, "StatusText": "OK" }

エラー処理

エラーが発生した場合、errorおよびcauseは次のように返されます。

  • HTTP ステータスコードが使用可能な場合、エラーはAPIGateway.<HTTP Status Code>

  • HTTP ステータスコードが使用できない場合、エラーはAPIGateway.<Exception>

いずれの場合もcauseは文字列として返されます。

次に、エラーが発生したレスポンスの例を示します。

{ "error": "APIGateway.403", "cause": "{\"message\":\"Missing Authentication Token\"}" }
注記

ステータスコード2XXは成功を示し、エラーは返されません。他のすべてのステータスコードまたはスローされた例外は、エラーになります。

詳しくは次を参照してください。

Amazon API Gateway の概念『API Gateway 開発者ガイド』を参照してください。