Amazon API Gateway
開発者ガイド

API Gateway コンソールを使用したリクエストとレスポンスのデータマッピングのセットアップ

API Gateway コンソールを使用して API の統合リクエスト/応答を定義するには、以下の手順に従います。

注記

以下の手順は、「API Gateway コンソールを使用して API 統合リクエストを設定する」の手順をすでに完了していることを前提とします。

  1. [リソース] ペインで選択したメソッドの [メソッドの実行] ペインで [統合リクエスト] を選択します。

  2. HTTP プロキシまたは AWS サービスプロキシでは、統合リクエストに定義されたパスパラメータ、クエリ文字列パラメータ、またはヘッダーパラメータを対応する HTTP プロキシまたは AWS サービスプロキシのメソッドリクエスト内のパスパラメータ、クエリ文字列パラメータ、またはヘッダーパラメータに関連付けるため、以下の操作を行います。

    1. [URL パスパラメータ]、[URL クエリ文字列パラメータ]、または [HTTP ヘッダー] の横の各矢印を選択した後、[パスの追加]、[クエリ文字列の追加]、または [ヘッダーの追加] をそれぞれ選択します。

    2. [名前] に、HTTP プロキシまたは AWS サービスプロキシのパスパラメータ、クエリ文字列パラメータ、またはヘッダーパラメータの名前を入力します。

    3. [マッピング元] に、パスパラメータ、クエリ文字列パラメータ、またはヘッダーパラメータのマッピング値を入力します。以下のいずれかの形式を使用します。

      • [メソッドリクエスト] ページの定義に従って [parameter-name] と名付けられたパスパラメータ用の場合は、method.request.path.parameter-name

      • [メソッドリクエスト] の定義に従って [parameter-name] と名付けられたクエリ文字列パラメータの場合は、method.request.querystring.parameter-name

      • [メソッドリクエスト] の定義に従って [parameter-name] と名付けられた複数値のクエリ文字列パラメータの場合は、method.request.multivaluequerystring.parameter-name

      • [メソッドリクエスト] ページの定義に従って [parameter-name] と名付けられたヘッダーパラメータ用の場合は、method.request.header.parameter-name

        または、リテラル文字列値 (一重引用符のペアで囲まれた値) を統合ヘッダーに設定できます。

      • [メソッドリクエスト] の定義に従って [parameter-name] と名付けられた複数値のヘッダーパラメータの場合は、method.request.multivalueheader.parameter-name

    4. [作成] を選択します(パスパラメータ、クエリ文字列パラメータ、またはヘッダーパラメータを削除するには、削除するパラメータの横の [キャンセル] または [削除] を選択します)。

  3. [本文マッピングテンプレート] エリアで、[リクエストボディのパススルー] のオプションを選択し、マッピングされていないコンテンツタイプのメソッドリクエストボディが、変換されることなく統合リクエストを通じて Lambda 関数、HTTP プロキシ、または AWS サービスプロキシに渡される方法を設定します。3 つのオプションがあります。

    • 次のステップに定義されているように、メソッドリクエストのコンテンツタイプが、マッピングテンプレートに関連付けられたコンテンツタイプのいずれとも一致しないときに、統合リクエストをパススルーしてメソッドリクエストボディを変換せずにバックエンドに渡す場合は、[リクエストの Content-Type ヘッダーに一致するテンプレートがない場合] を選択します。

      注記

      API Gateway API を呼び出すときは、Integration リソースの passthroughBehavior プロパティの値として WHEN_NO_MATCH を設定して、このオプションを選択します。

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

      注記

      API Gateway API を呼び出すときは、Integration リソースの passthroughBehavior プロパティの値として WHEN_NO_TEMPLATE を設定して、このオプションを選択します。

    • メソッドリクエストのコンテンツタイプが、統合リクエストに定義されたマッピングテンプレートと関連付けられたコンテンツタイプと一致しないか、統合リクエストにマッピングテンプレートが定義されていない場合に、メソッドリクエストを渡さないようにするには、[なし] を選択します。マッピングされていないコンテンツタイプのメソッドリクエストは、HTTP 415 Unsupported Media Type レスポンスで拒否されます。

      注記

      API Gateway API を呼び出すときは、Integration リソースの passthroughBehavior プロパティの値として NEVER を設定して、このオプションを選択します。

    統合のパススルー動作の詳細については、「統合パススルーの動作」を参照してください。

  4. 入力リクエストのマッピングテンプレートを定義するには、[Content-Type] の [マッピングテンプレートの追加] を選択します。入力テキストボックスにコンテンツタイプ (例: application/json) を入力し、チェックマークアイコンを選択して、入力した内容を保存します。次に、手動でマッピングテンプレートを入力するか、[テンプレートの生成] を選択してモデルテンプレートからテンプレートを作成します。詳細については、「リクエストおよびレスポンスマッピングのモデルおよびマッピングテンプレートを作成する」を参照してください。

  5. バックエンドからの統合応答を、呼び出し元のアプリケーションへ返される API のメソッド応答とマッピングできます。これには、バックエンドの使用可能なヘッダーからクライアントが選択した応答ヘッダーへ戻り、バックエンドの応答ペイロードのデータ形式を API 指定の形式に変換します。このようなマッピングは、[メソッドの実行] ページの [メソッドレスポンス] および [統合レスポンス] を設定することで指定できます。

    1. [メソッドの実行] ペインで [統合レスポンス] を選択します。[200] の横の矢印を選択してメソッドから 200 HTTP 応答コードの設定を指定するか、[統合レスポンスの追加] を選択してメソッドからその他の任意の HTTP 応答ステータスコードの設定を指定します。

    2. [Lambda error regex](Lambda 関数の場合) または [HTTP status regex (HTTP ステータス正規表現)](HTTP プロキシまたは AWS サービスプロキシの場合) に、正規表現を入力し、どの Lambda 関数エラー文字列 (Lambda 関数の場合) または HTTP 応答ステータスコード (HTTP プロキシまたは AWS サービスプロキシの場合) をこの出力マッピングにマッピングするかを指定します。たとえば、すべての 2xx HTTP 応答ステータスコードを HTTP プロキシからこの出力マッピングにマッピングするには、[HTTP status regex (HTTP ステータス正規表現)] に「2\\d{2}」と入力します。「無効なリクエスト」を含むエラーメッセージを Lambda 関数から 400 Bad Request レスポンスに返すには、[Lambda error regex (Lambda エラー正規表現)] として「.*Invalid request.*」と入力します。一方、400 Bad Request を Lambda からのすべてのマッピングされていないエラーメッセージに返すには、[Lambda error regex (Lambda エラー正規表現)] に「(\n|.)+」と入力します。この最後の正規表現は、API のデフォルトのエラーのレスポンスに使用できます。

      注記

      API Gateway は、レスポンスマッピングに Java パターンスタイルの正規表現を使用します。詳細については、Oracle ドキュメントの「パターン」を参照してください。

      エラーパターンは Lambda レスポンスの errorMessage プロパティの文字列全体に対してマッチングされます。これは、Node.js の場合は callback(errorMessage)、Java の場合は throw new MyException(errorMessage) によって設定されます。また、エスケープ文字は正規表現が適用されるまではエスケープされません。

      '.+' を選択パターンとして使用してレスポンスをフィルタする場合は、改行 ('\n') 文字を含むレスポンスには一致しない可能性があることに注意してください。

    3. 有効な場合は、[メソッドレスポンスのステータス] で、[メソッドレスポンス] ページで定義した HTTP 応答ステータスコードを選択します。

    4. [ヘッダーマッピング] で、[メソッドレスポンス] ページの HTTP 応答ステータスコードで定義された各ヘッダーについて、[編集] を選択してマッピング値を指定します。[マッピングの値] で、以下のいずれかの形式を使用します。

      • integration.response.multivalueheaders.header-name のようにします。header-name はバックエンドからの複数値の応答ヘッダーの名前です。

        たとえば、バックエンド応答の Date ヘッダーを API メソッドの応答の Timestamp ヘッダーとして返すには、[レスポンスヘッダー] 列に [Timestamp (タイムスタンプ)] エントリを含め、関連する [マッピング値] は [integration.response.multivalueheaders.Date] に設定します。

      • integration.response.header.header-name のようにします。header-name はバックエンドからの単一値の応答ヘッダーの名前です。

        たとえば、バックエンド応答の Date ヘッダーを API メソッドの応答の Timestamp ヘッダーとして返すには、[レスポンスヘッダー] 列に [Timestamp (タイムスタンプ)] エントリを含め、関連する [マッピング値] は [integration.response.header.Date] に設定します。

    5. [テンプレートマッピング] エリアで、[コンテンツタイプ] の横の [追加] を選択します。[コンテンツタイプ] ボックスに、Lambda 関数、HTTP プロキシ、または AWS サービスプロキシからメソッドに渡されるデータのコンテンツタイプを入力します。[Update] を選択します。

    6. Lambda 関数、HTTP プロキシ、または AWS サービスプロキシからのデータをメソッドで受信しながらも変更しない場合は、[出力パススルー] を選択します。

    7. [出力パススルー] がオフの場合は、[出力マッピング] で、Lambda 関数、HTTP プロキシ、または AWS サービスプロキシがメソッドへのデータ送信に使用する出力マッピングテンプレートを指定します。手動でマッピングテンプレートを入力するか、[Generate template from model (モデルからテンプレートを生成)] からモデルを選択できます。

    8. [Save] を選択します。