WebSocket API のデータ変換の設定

API Gateway では、API のメソッドリクエストは、バックエンドで必要となる、該当する統合リクエストペイロードとは異なる形式のペイロードを受け取ることができます。同様に、バックエンドは、フロントエンドで予期されるメソッドレスポンスペイロードとは異なる統合レスポンスペイロードを返す場合があります。

API Gateway では、マッピングテンプレートを使用して、ペイロードをメソッドリクエストから該当する統合リクエストにマッピングしたり、統合レスポンスから該当するメソッドレスポンスにマッピングしたりできます。テンプレート選択式を指定して、必要なデータ変換の実行に使用するテンプレートを決定します。

データマッピングを使用して、ルートリクエストからバックエンド統合にデータをマッピングできます。詳細については、「WebSocket API のデータマッピングの設定」を参照してください。

テンプレートとモデルのマッピング

マッピングテンプレートは、Velocity Template Language (VTL) で表現されるスクリプトであり、JSONPath 式を使用してペイロードに適用されます。API Gateway マッピングテンプレートの詳細については、「マッピングテンプレートについて」を参照してください。

ペイロードでは、JSON スキーマのドラフト 4 に基づくデータモデルを使用できます。マッピングテンプレートを作成するためにモデルを定義する必要はありません。ただし、API Gateway では指定されたモデルに基づいてテンプレート設計図が生成されるため、モデルはテンプレートの作成に役立ちます。API Gateway モデルの詳細については、「データモデルを理解する」を参照してください。

テンプレート選択式

マッピングテンプレートを使用してペイロードを変換するには、統合リクエストまたは統合レスポンスで WebSocket API テンプレート選択式を指定します。この式の評価により、(入力テンプレートを介して) リクエストボディを統合リクエストボディに変換するか、(出力テンプレートを介して) 統合レスポンスボディをルートレスポンスボディに変換するために使用される入力または出力テンプレート (存在する場合) が決定されます。

Integration.TemplateSelectionExpression は、${request.body.jsonPath} および静的な値をサポートします。

IntegrationResponse.TemplateSelectionExpression は、${request.body.jsonPath}、${integration.response.statuscode}、${integration.response.header.headerName}、${integration.response.multivalueheader.headerName} および静的な値をサポートします。

統合レスポンスの選択式

WebSocket API に対して統合レスポンスを設定するときは、オプションで統合レスポンスの選択式を指定できます。この式により、統合が返されるときに選択する IntegrationResponse が決定されます。現在、この式の値は以下に定義するように、API Gateway によって制限されています。この式は非プロキシ統合に対してのみ適用されることに注意してください。プロキシ統合は、モデル化または変更なしに、単純にレスポンスペイロードを呼び出し元に渡すだけです。

上記に示した他の選択式とは異なり、この式はパターンマッチング形式を現在サポートしています。式はスラッシュで囲む必要があります。

現在、値は integrationType に応じて固定されています。

• Lambda ベースの統合の場合は、$integration.response.body.errorMessage です。

• HTTP および MOCK 統合の場合、その値は $integration.response.statuscode です。

• HTTP_PROXY と AWS_PROXY の場合、式は利用されません。これは、呼び出し元へのペイロードのパススルーをリクエストしているためです。