Amazon API Gateway
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

使用映射模板覆盖 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} 是可在运行时获取数字的路径参数。

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

  1. 通过 https://console.amazonaws.cn/apigateway 登录 API Gateway 控制台。

  2. API 下,选择 PetStore API。

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

  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 的请求参数和标头

在本教程中,您将通过创建映射模板(此模板将 GET 映射到一个组合其他两个标头的新标头)来覆盖 $context.requestOverride.header.header_name 方法的请求标头。

  1. 通过 https://console.amazonaws.cn/apigateway 登录 API Gateway 控制台。

  2. API 下,选择 PetStore API。

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

  4. 选择方法请求

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

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

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

    3. Name (名称)下方,键入 header1

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

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

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

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

  8. 展开 HTTP Headers (HTTP 标头)。您将看到您创建的两个标头(即 header1header2)及其默认映射(在 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> 具有相同格式。

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