統合パススルーの動作 - Amazon API Gateway

統合パススルーの動作

非プロキシ統合の場合は、メソッドリクエストにペイロードが含まれ、Content-Type ヘッダーが、指定されたマッピングテンプレートに一致しないか、マッピングテンプレートが定義されていない場合は、クライアントで提供されたリクエストペイロードを、統合リクエストを通じて変換せずにバックエンドに渡す選択ができます。このプロセスは統合パススルーと呼ばれます。

プロキシ統合の場合は、API Gateway がリクエスト全体をバックエンドに渡します。パススルー動作を変更するオプションはありません。

入力リクエストの実際のパススルー動作は、統合リクエストの設定中に、指定されたマッピングテンプレートに選択したオプションと、クライアントが受信リクエストで設定する Content Type ヘッダーによって決まります。3 つのオプションがあります。

リクエストした Content-Type ヘッダーと一致するテンプレートがない場合

メソッドリクエストのコンテンツタイプが、マッピングテンプレートと関連付けられたコンテンツタイプに一致しない場合に、統合リクエストをパススルーしてメソッドリクエスト本文を変換せずにバックエンドに渡す場合は、このオプションを選択します。

API Gateway API を呼び出すときは、[統合] の passthroughBehavior プロパティの値として WHEN_NO_MATCH を設定して、このオプションを選択します。

テンプレートが定義されていない場合 (推奨)

統合リクエストでマッピングテンプレートが定義されていないときに、統合リクエストをパススルーしてメソッドリクエスト本文を変換せずにバックエンドに渡す場合は、このオプションを選択します。このオプションを選択したときにテンプレートが定義されている場合、マッピングされていないコンテンツタイプのメソッドリクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。

API Gateway API を呼び出すときは、[統合] の passthroughBehavior プロパティの値として WHEN_NO_TEMPLATES を設定して、このオプションを選択します。

なし

統合リクエストでマッピングテンプレートが定義されていないときに、統合リクエストをパススルーしてメソッドリクエストボディを変換せずにバックエンドに渡さない場合は、このオプションを選択します。このオプションを選択したときにテンプレートが定義されている場合、マッピングされていないコンテンツタイプのメソッドリクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。

API Gateway API を呼び出すときは、[統合] の passthroughBehavior プロパティの値として NEVER を設定して、このオプションを選択します。

次の例では、可能なパススルー動作について示します。

例 1: application/json コンテンツタイプで 1 つのマッピングテンプレートが統合リクエストで定義されている。

Content-Type ヘッダー\選択されたパススルーオプション WHEN_NO_MATCH WHEN_NO_TEMPLATES NEVER
なし (デフォルト: application/json) リクエストペイロードはテンプレートを使用して変換されます。 リクエストペイロードはテンプレートを使用して変換されます。 リクエストペイロードはテンプレートを使用して変換されます。
application/json リクエストペイロードはテンプレートを使用して変換されます。 リクエストペイロードはテンプレートを使用して変換されます。 リクエストペイロードはテンプレートを使用して変換されます。
application/xml リクエストペイロードは変換されず、そのままバックエンドに送信されます。 リクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。 リクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。

例 2: application/xml コンテンツタイプで 1 つのマッピングテンプレートが統合リクエストで定義されている。

Content-Type ヘッダー\選択されたパススルーオプション WHEN_NO_MATCH WHEN_NO_TEMPLATES NEVER
なし (デフォルト: application/json) リクエストペイロードは変換されず、そのままバックエンドに送信されます。 リクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。 リクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。
application/json リクエストペイロードは変換されず、そのままバックエンドに送信されます。 リクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。 リクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。
application/xml リクエストペイロードはテンプレートを使用して変換されます。 リクエストペイロードはテンプレートを使用して変換されます。 リクエストペイロードはテンプレートを使用して変換されます。