使用映射模板覆盖 API 的请求和响应参数以及状态代码

利用标准 API Gateway 参数和响应代码映射模板，您可以一对一地映射参数，并将一系列集成响应状态代码（由正则表达式匹配）映射到单个响应状态代码。映射模板覆盖使您能够灵活地执行多对一参数映射；在应用标准 API Gateway 映射后覆盖参数；根据正文内容或其他参数值有条件地映射参数；通过编程方式动态地创建新的参数；并覆盖由集成终端节点返回的状态代码。可覆盖任何类型的请求参数、响应标头或响应状态代码。

以下是用于映射模板覆盖的示例：

• 创建新的标头（或覆盖现有标头）作为两个参数的联接

• 根据正文内容覆盖响应代码以获得成功或失败代码

• 根据一个参数的内容或其他参数的内容有条件地重新映射该参数

• 循环访问 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} 是可在运行时获取数字的路径参数。

在本教程中，您将通过创建映射模板（此模板在检测到错误条件时，将 $context.responseOverride.status 映射到 400）来覆盖此 GET 方法的响应代码。

1. 通过以下网址登录到 Amazon API Gateway 控制台：https://console.aws.amazon.com/apigateway。

2. 在 API 下，选择 PetStore API。

3. 在 Resources (资源) 列中，选择 GET 下的 /{petId} 方法。

4. 在 Client (客户端) 框中，选择 Test (测试)。

5. 为 {petId} 键入 -1，并选择 Test (测试)。

   在结果中，您会发现两件事：

   首先，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. 对于内容类型，键入 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 映射到一个组合其他两个标头的新标头）来覆盖 GET 方法的请求标头。

1. 通过以下网址登录到 Amazon API Gateway 控制台：https://console.aws.amazon.com/apigateway。

2. 在 API 下，选择 PetStore API。

3. 在 Resources (资源) 列中，选择 GET 下的 /pets 方法。

4. 选择 Method Request (方法请求)。

5. 创建如下所示的参数：

   1. 展开 HTTP Request Headers (HTTP 请求标头)。

   2. 选择 Add header (添加标头)。

   3. 在 Name (名称)下方，键入 header1。

   4. 选择对勾图标以保存您的选择。

   重复此过程以创建名为 header2 的第二个标题。

6. 返回到 Method Execution (方法执行)。

7. 选择 Integration Request (集成请求)。

8. 展开 HTTP Headers (HTTP 标头)。您将看到您创建的两个标头（即 header1 和 header2）及其默认映射（在 Mapped from (映射自)下）。

9. 展开 Mapping Templates (映射模板)。

10. 选择 Add mapping template (添加映射模板)。

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. 选择 Save。

15. 返回到 Method Execution (方法执行)。

16. 在 Client (客户端) 框中，选择 Test (测试)。

17. 在 {pets} 的 Headers (标头) 下，复制以下代码：

    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> 具有相同格式。

示例：使用适用于 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
});