API Gateway コンソールを使用してリクエストとレスポンスのデータマッピングを設定する - Amazon API Gateway

API Gateway コンソールを使用してリクエストとレスポンスのデータマッピングを設定する

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

注記

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

  1. [リソース] ペインで、メソッドを選択します。

  2. [統合リクエスト] タブの [統合リクエストの設定] で、[編集] を選択します。

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

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

      注記

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

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

      注記

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

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

      注記

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

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

  4. 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. 別のパラメーターを追加するには、[追加] ボタンを選択します。

  5. マッピングテンプレートを追加するには、[マッピングテンプレート] を選択します。

  6. 入力リクエストのマッピングテンプレートを定義するには、[マッピングテンプレートの追加] を選択します。[コンテンツタイプ] にコンテンツタイプ (例: application/json) を入力します。次に、マッピングテンプレートを入力します。詳細については、「REST API のマッピングテンプレート」を参照してください。

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

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

    Lambda 関数、HTTP プロキシ、または AWS のサービスプロキシから返される HTTP ステータスコードに基づいてカスタムレスポンスデータ形式をメソッドで受け取るには、以下を実行します。

    1. [統合レスポンス] を選択します。[デフォルト - レスポンス] で [編集] を選択してメソッドから 200 HTTP レスポンスコードの設定を指定するか、[レスポンスを作成] を選択してメソッドからその他の任意の HTTP レスポンスステータスコードの設定を指定します。

    2. [Lambda エラーの正規表現] (Lambda 関数の場合) または [HTTP ステータスの正規表現] (HTTP プロキシまたは AWS のサービスプロキシの場合) に正規表現を入力し、どの Lambda 関数エラー文字列 (Lambda 関数の場合) または HTTP レスポンスステータスコード (HTTP プロキシまたは AWS のサービスプロキシの場合) をこの出力マッピングにマップするかを指定します。たとえば、すべての 2xx HTTP 応答ステータスコードを HTTP プロキシからこの出力マッピングにマッピングするには、[HTTP status regex (HTTP ステータス正規表現)] に「2\d{2}」と入力します。「Invalid Request」を含むエラーメッセージを Lambda 関数から 400 Bad Request レスポンスに返すには、[Lambda エラーの正規表現] として「.*Invalid request.*」と入力します。一方、すべてのマッピングされていないエラーメッセージで 400 Bad Request を Lambda から返すには、[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 のサービスプロキシからメソッドに渡すデータのコンテンツタイプを入力します。次に、マッピングテンプレートを入力します。詳細については、「REST API のマッピングテンプレート」を参照してください。

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