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

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

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

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

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

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

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

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

マッピングテンプレートオーバーライドを作成するには、マッピングテンプレートで以下のいずれかの $context 変数を使用します。

リクエストボディのマッピングテンプレート レスポンスボディのマッピングテンプレート
$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} は、実行時に数字をとることができるパスパラメータです。

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

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

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

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

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

  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. [メソッドの実行] に戻ります。[統合レスポンス] を選択し、[200] の横にある矢印を選択します。

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

  8. [コンテンツタイプ] に application/json と入力し、チェックマークアイコンを選択して選択項目を保存します。

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

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

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

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

  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 のリクエストパラメータとヘッダーをオーバーライドする

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

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

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

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

  4. [メソッドリクエスト] を選択します。

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

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

    2. [ヘッダーの追加] を選択します。

    3. [名前] で、「header1」と入力します。

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

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

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

  7. [Integration Request (統合リクエスト)] を選択します。

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

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

  10. [マッピングテンプレートの追加] を選択します。

  11. [コンテンツタイプ] に 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) #set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])
  14. [保存] を選択します。

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

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

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

    header1:header1Val header2:header2Val
  18. [Test (テスト)] を選択します。

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

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

例: 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 });