Amazon API Gateway
開発者ガイド

マッピングテンプレートを使用して、API のリクエストおよびレスポンスパラメータとステータスコードをオーバーライドする

標準 API Gateway パラメータとレスポンスコードのマッピングテンプレートを使用して、パラメータの 1 対 1 のマッピング、および統合レスポンスステータスコードの一群 (正規表現と一致する) を単一のレスポンスステータスコードにマッピングすることができます。マッピングテンプレートオーバーライドにより多対 1 のマッピングを実行する柔軟性が提供されます。標準 API Gateway マッピング後のパラメータのオーバーライドが適用されます。条件付きでマップパラメータは本文の内容または他のパラメータ値に基づきます。プログラムによってオンザフライで新しいパラメータを作成し、統合エンドポイントによりオーバーライドステータスコードが返されます。あらゆるタイプのリクエストパラメータ、レスポンスヘッダー、またはレスポンスステータスコードはオーバーライドされます。

マッピングテンプレートオーバーライドの使用例を以下に示します。

  • 2 つのパラメータを連結した新しいヘッダーを作成する (または既存のヘッダーをオーバライドする) には

  • 本文の内容に基づく成功または失敗コードにレスポンスコードをオーバーライドするには

  • パラメータまたはその他のパラメータの内容に基づいて、条件付きでパラメータを再マッピングするには

  • JSON 本文の内容を反復処理し、ヘッダーやクエリ文字列にキーと値のペアを再マッピングするには

マッピングテンプレートオーバーライドを作成するには、マッピングテンプレート$context 変数を 1 つ以上使用します。

リクエスト本文マッピングテンプレート レスポンス本文マッピングテンプレート
$context.requestOverride.header.header_name $context.responseOverride.header.header_name
$context.requestOverride.path.path_name $context.responseOverride.status
$context.requestOverride.querystring.querystring_name

注記

マッピングテンプレートオーバーライドは、データマッピングが不足しているため、プロキシ統合エンドポイントで使用することはできません。統合の詳細については、API Gateway API 統合タイプを選択する を参照してください。

重要

オーバーライドが終了します。オーバーライドは各パラメータに一度だけ適用されます。同じパラメータを複数回オーバーライドしようとすると、Amazon API Gateway から 5XX レスポンスが発生します。テンプレート全体で同じパラメータを複数回オーバーライドする必要がある場合は、変数を作成してテンプレートの終了時にオーバーライドを適用することをお勧めします。テンプレートはテンプレート全体が解析された後にのみ適用されることに注意してください。「チュートリアル: API Gateway コンソールを使用して API のリクエストパラメータとヘッダーをオーバーライドする」を参照してください。

以下のチュートリアルでは、API Gateway コンソールでマッピングテンプレートオーバーライドを作成およびテストする方法を示します。これらのチュートリアルでは、開始点として PetStore サンプル API を使用します。両方のチュートリアルは、PetStore サンプル API がすでに作成されていることを前提としています。

チュートリアル: API Gateway コンソールを使用して、API の応答ステータスコードをオーバーライドする

PetStore サンプル API を使用してペットを取得するには、GET /pets/{petId} の API メソッドリクエストを使用します。{petId} は、実行時に数字をとることができるパスパラメータです。

このチュートリアルでは、エラー状態が検出された場合、$context.responseOverride.status400 にマッピングするマッピングテンプレートを作成することで、この GET メソッドのレスポンスコードをオーバーライドします。

  1. https://console.aws.amazon.com/apigateway で API Gateway コンソールにサインインします。

  2. [API] で、PetStore API を選択します。

  3. [Resources (リソース)] 列で、/{petId} の下の GET メソッドを選択します。

  4. [Client (クライアント)] ボックスで、[Test (テスト)] を選択します。

  5. [{petId}] に -1 を入力して、[Test (テスト)] を選択します。

    結果として、2 つのことが分かります。

    まず、[Response Body (レスポンス本文)] は範囲外エラーを示します。

    { "errors": [ { "key": "GetPetRequest.petId", "message": "The value is out of range." } ] }

    次に、[Logs (ログ)] ボックスの最後の行は、Method completed with status: 200 で終わります。

  6. [Method Execution] に戻ります。[Integration Response] を選択し、[200] の横にある矢印を選択します。

  7. [Mapping Templates (マッピングテンプレート)] セクションで、[Add mapping template (マッピングテンプレートの追加)] を選択します。

  8. [Content Type (コンテンツタイプ)] で [application/json] と入力し、チェックマークアイコンを選択して選択内容を保存します。

  9. テンプレートエリアに次のコードをコピーします。

    #set($inputRoot = $input.path('$')) $input.json("$") #if($inputRoot.toString().contains("error")) #set($context.responseOverride.status = 400) #end
  10. [Save] を選択します。

  11. [Method Execution (メソッドの実行)] に戻ります。

  12. [Client (クライアント)] ボックスで、[Test (テスト)] を選択します。

  13. [{petId}] に -1 を入力して、[Test (テスト)] を選択します。

    結果として、[Response Body (レスポンス本文)] は範囲外エラーを示します。

    { "errors": [ { "key": "GetPetRequest.petId", "message": "The value is out of range." } ] }

    ただし、[Logs (ログ)] ボックスの最後の行は、Method completed with status: 400 で終わるようになりました。

チュートリアル: API Gateway コンソールを使用して API のリクエストパラメータとヘッダーをオーバーライドする

このチュートリアルでは、$context.requestOverride.header.header_name を他の 2 つのヘッダーを組み合わせる新しいヘッダーにマッピングするマッピングテンプレートを作成することで、GET メソッドのリクエストヘッダーコードをオーバーライドします。

  1. https://console.aws.amazon.com/apigateway で API Gateway コンソールにサインインします。

  2. [API] で、PetStore API を選択します。

  3. [Resources (リソース)] 列で、/pets の下の GET メソッドを選択します。

  4. [Method Request] を選択します。

  5. 次のようにパラメータを作成します。

    1. [HTTP Request Headers (HTTP リクエストヘッダー)] を展開します。

    2. [Add header] を選択します。

    3. [Name (名前)] の下に、header1 と入力します。

    4. チェックマークアイコンを選択して、選択を保存します。

    この手順を繰り返して、header2 という 2 番目のヘッダーを作成します。

  6. [Method Execution (メソッドの実行)] に戻ります。

  7. [Integration Request] を選択します。

  8. [HTTP Headers (HTTP ヘッダー)] を展開します。作成した 2 つのヘッダー、header1header2 が、デフォルトのマッピング ([Mapped from (マッピング元)] の下) と共に表示されます。

  9. [マッピングテンプレート] を展開します。

  10. [Add mapping template] を選択します。

  11. [Content Type (コンテンツタイプ)] で [application/json] と入力し、チェックマークアイコンを選択して選択内容を保存します。

  12. [Note: This template can map headers and body. (注意: このテンプレートはヘッダーと本文をマッピングできます。)] というポップアップが表示されます。

    [Yes, secure this integration (はい、この統合を保護します)] を選択します。

  13. テンプレートエリアに次のコードをコピーします。

    #set($header1Override = "foo") #set($header3Value = "$input.params('header1')$input.params('header2')") $input.json("$") #set($context.requestOverride.header.header3 = $header3Value) #set($context.requestOverride.header.header1 = $header1Override)
  14. [Save] を選択します。

  15. [Method Execution (メソッドの実行)] に戻ります。

  16. [Client (クライアント)] ボックスで、[Test (テスト)] を選択します。

  17. [Headers (ヘッダー)] で、[{pets}] に、次のコードをコピーします。

    header1:header1Val header2:header2Val
  18. [Test] を選択します。

    ログに、このテキストを含むエントリが表示されます。

    Endpoint request headers: {header3=header1Valheader2Val, header2=header2Val, x-amzn-apigateway-api-id=<api-id>, header1=foo, Accept=application/json

例: API Gateway CLI を使用して API のリクエストパラメータとヘッダーをオーバーライドする

次の CLI の例では、put-integration コマンドを使用してレスポンスコードをオーバーライドする方法を示しています。

aws apigateway put-integration --rest-api-id <API_ID> --resource-id <PATH_TO_RESOURCE_ID> --http-method <METHOD> --type <INTEGRATION_TYPE> --request-templates <REQUEST_TEMPLATE_MAP>

ここで、<REQUEST_TEMPLATE_MAP> は、コンテンツタイプから適用されるテンプレートの文字列へのマッピングです。マッピングは以下のような構造になっています。

Content_type1=template_string,Content_type2=template_string

または、JSON 構文です。

{"content_type1": "template_string" ...}

次の例では、put-integration-response コマンドを使用して API レスポンスコードをオーバーライドする方法を示しています。

aws apigateway put-integration-response --rest-api-id <API_ID> --resource-id <PATH_TO_RESOURCE_ID> --http-method <METHOD> --status-code <STATUS_CODE> --response-templates <RESPONSE_TEMPLATE_MAP>

ここで、<RESPONSE_TEMPLATE_MAP> は、上記の <REQUEST_TEMPLATE_MAP> と同じ形式です。

例: SDK for JavaScript を使用して API のリクエストパラメータとヘッダーをオーバーライドする

次の例では、put-integration コマンドを使用してレスポンスコードをオーバーライドする方法を示しています。

リクエスト:

var params = { httpMethod: 'STRING_VALUE', /* required */ resourceId: 'STRING_VALUE', /* required */ restApiId: 'STRING_VALUE', /* required */ type: HTTP | AWS | MOCK | HTTP_PROXY | AWS_PROXY, /* required */ requestTemplates: { '<Content_type>': 'TEMPLATE_STRING', /* '<String>': ... */ }, }; apigateway.putIntegration(params, function(err, data) { if (err) console.log(err, err.stack); // an error occurred else console.log(data); // successful response });

レスポンス:

var params = { httpMethod: 'STRING_VALUE', /* required */ resourceId: 'STRING_VALUE', /* required */ restApiId: 'STRING_VALUE', /* required */ statusCode: 'STRING_VALUE', /* required */ responseTemplates: { '<Content_type>': 'TEMPLATE_STRING', /* '<String>': ... */ }, }; apigateway.putIntegrationResponse(params, function(err, data) { if (err) console.log(err, err.stack); // an error occurred else console.log(data); // successful response });