メニュー
Amazon API Gateway
開発者ガイド

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

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

注記

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

  1. [Resources] ペインで選択したメソッドの [Method Execution] ペインで [Integration Request] を選択します。

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

    1. [URL Path Parameters]、[URL Query String Parameters]、または [HTTP Headers] の横の各矢印を選択した後、[Add path]、[Add query string]、または [Add header] をそれぞれ選択します。

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

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

      • method.request.path.parameter-name: [Method Request] の定義に従って [parameter-name] と名付けられたパスパラメータの場合。

      • method.request.querystring.parameter-name: [Method Request] の定義に従って [parameter-name] と名付けられたクエリ文字列パラメータの場合。

      • method.request.header.parameter-name: [Method Request] の定義に従って [parameter-name] と名付けられたヘッダーパラメータの場合。

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

    4. [Create] を選択します (パスパラメータ、クエリ文字列パラメータ、またはヘッダーパラメータを削除するには、削除するパラメータの横の [Cancel] または [Remove] を選択します)。

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

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

      注記

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

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

      注記

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

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

      注記

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

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

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

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

    1. [Method Execution] ペインで [Integration Response] を選択します。[200] の横の矢印を選択してメソッドから 200 HTTP 応答コードの設定を指定するか、[Add integration response] を選択してメソッドからその他の任意の HTTP 応答ステータスコードの設定を指定します。

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

      注記

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

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

    3. 有効な場合は、[Method response status] で、[Method Response] ページで定義した HTTP 応答ステータスコードを選択します。

    4. [Header Mappings] で、[Method Response] ページの HTTP 応答ステータスコードで定義された各ヘッダーについて、[Edit] を選択してマッピング値を指定します。[Mapping value] の形式は、integration.response.header.header-name のようにします。header-name はバックエンドからの応答ヘッダーの名前です。たとえば、バックエンド応答の Date ヘッダーを API メソッドの応答の Timestamp ヘッダーとして返すには、[Response header] 列に [Timestamp] エントリを含め、関連する [Mapping value] は [integration.response.header.Date] に設定します。

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

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

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

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