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

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

Step Functions を使用して API Gateway を呼び出し

Step Functions は、Amazon States Language から、AWS の特定のサービスを直接制御することができます。AWS Step Functions との協働および統合の詳細については、以下を参照してください。

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

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

注記

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

API Gateway 特徴のサポート

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

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

    • オーソライザー: IAM (を使用して署名バージョン 4)、認証なし、Lambda Authorizers (カスタムヘッダーを使用したリクエストパラメータベースおよびトークンベース)

    • 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 および REST 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 がデプロイされるステージの名前。$default ステージを使用する HTTP API のオプションとなっています。

  • Path

    • タイプ: String

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

  • QueryParameters

    • タイプ: JSON

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

  • RequestBody

    • タイプ: JSON または String

    • HTTP リクエストボディ。そのタイプは、JSON オブジェクトまたは String です。RequestBody は、PATCHPOST、および PUT HTTP メソッドに対してのみサポートされています。

  • AllowNullValues

    • タイプ: BOOLEAN

    • AllowNullValuestrue に設定すると、次のように、ヌル値を渡す許可がでます。

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

    • タイプ: JSON

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

      • NO_AUTH

      • IAM_ROLE

      • RESOURCE_POLICY

      詳細は、認証と認可を参照してください。

注記

セキュリティを考慮して、以下の HTTP ヘッダーキーは現在、許可されていません。

  • X-ForwardedX-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 へのリソースポリシー認証を使って API Gateway リクエストを認証するステートマシンにアクセスが付与されます。

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

    3. アクセス対象のリソースには、以下が含まれます。

      • region

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

      • api-id

      • stage-name

      • HTTP-VERB (メソッド)。

      • resource-path-specifier

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

    リソース形式の詳細については、API Gateway デベロッパーガイドの API Gateway における API 実行許可のリソース形式を参照してください。

    注記

    リソースポリシーは REST API の場合に限り、サポートされます。

サービス統合パターン

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

  • レスポンスのリクエスト。デフォルトの統合パターンです。このおかげで、TTP レスポンスを受信した直後に Step Functions が H次のステップに進むことができます。

  • タスクトークンのコールバックまで待機する (.waitForTaskToken) は、タスクトークンがペイロードとともに返されるまで待機します。以下の例に示す通り、.waitForTaskToken パターンを使うため、タスク定義の [Resource] (リソース) フィールドの末尾に .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_ROLE" } }

出力形式

次の出力パラメータが提供されます。

[Name] (名前) 説明
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 のステータスコードは成功を示し、エラーは返されません。他のすべてのステータスコードまたはスローされた例外は、エラーになります。

詳細については、以下を参照してください。

API Gateway デベロッパーガイドの Amazon API Gateway の概念