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

使用映射模板覆盖 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. 资源树中,选择 /{petId} 下的 GET 方法。

  4. 选择测试选项卡。您可能需要选择右箭头按钮,以显示该选项卡。

  5. 对于 petId,输入 -1,然后选择测试

    在结果中,您会发现两件事:

    首先,响应正文指示超出范围错误:

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

    其次,日志框下的最后一行的结尾为:Method completed with status: 200

  6. 集成响应选项卡上,对于默认 - 响应,选择编辑

  7. 选择映射模板

  8. 选择添加映射模板

  9. 对于内容类型,输入 application/json

  10. 对于模板正文,输入以下内容:

    #set($inputRoot = $input.path('$')) $input.json("$") #if($inputRoot.toString().contains("error")) #set($context.responseOverride.status = 400) #end
  11. 选择保存

  12. 选择测试选项卡。

  13. 对于 petId,输入 -1

  14. 在结果中,响应正文表示超出范围错误:

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

    不过,日志框下的最后一行现在的结尾为: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. 资源树中,选择 /pet 下的 GET 方法。

  4. 方法请求选项卡上,对于方法请求设置,选择编辑

  5. 选择 HTTP 请求标头,然后选择添加标头

  6. 对于名称,请输入 header1

  7. 选择添加标头,然后创建第二个标头,名为 header2

  8. 选择保存

  9. 集成请求选项卡上,对于集成请求设置,选择编辑

  10. 对于请求正文传递,选择当未定义模板时(推荐)

  11. 选择映射模板,然后执行以下操作:

    1. 选择添加映射模板

    2. 对于内容类型,输入 application/json

    3. 对于模板正文,输入以下内容:

      #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])
  12. 选择保存

  13. 选择测试选项卡。

  14. {pets}标头下,复制以下代码:

    header1:header1Val header2:header2Val
  15. 选择测试

    在日志中,您应看到一个包含以下文本的条目:

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