转换 API 请求和响应 - Amazon API Gateway
转换 API 请求转换 API 响应保留的标头示例
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

转换 API 请求和响应

您可以在客户端 API 请求到达后端集成之前修改它们。您还可以在 API Gateway 将响应返回给客户端之前更改集成的响应。您可以使用参数映射修改 HTTP API 的 API 请求和响应。要使用参数映射，您需要指定要修改的 API 请求或响应参数，并指定如何修改这些参数。

转换 API 请求

在请求到达后端集成之前，您可以使用请求参数更改请求。您可以修改标头、查询字符串或请求路径。

请求参数是键值映射。键用于标识要更改的请求参数的位置以及如何更改它。值指定参数的新数据。

下表显示了支持的键。

参数映射键
类型 语法
标头 append|overwrite|remove:header.headername
查询字符串 append|overwrite|remove:querystring.querystring-name
路径 overwrite:path

下表显示了可以映射到参数的支持值。

请求参数映射值
类型 语法 备注
标头值 $request.header.name 或 ${request.header.name} 标头名称不区分大小写。API Gateway 将多个标头值与逗号组合在一起，例如 "header1": "value1,value2"。保留一些标头。要了解更多信息，请参阅“保留的标头”。
查询字符串值 $request.querystring.name 或 ${request.querystring.name} 查询字符串名称区分大小写。API Gateway 将多个值与逗号组合在一起，例如 "querystring1" "Value1,Value2"。
请求正文 $request.body.name 或 ${request.body.name} JSON 路径表达式 不支持递归下降 ($request.body..name) 和筛选表达式 (?(expression))。
注意

当您指定 JSON 路径时，API Gateway 会在请求正文的 100 KB 处将其截断，然后应用选择表达式。要发送大于 100 KB 的负载，请指定 $request.body。
请求路径 $request.path 或 $ {request.path} 请求路径，没有阶段名称。
路径参数 $request.path.name 或 ${request.path.name} 请求中路径参数的值。例如，如果路由为 /pets/{petId}，则可以从具有 petId 的请求中映射 $request.path.petId 参数。
上下文变量 $context.variableName 或 ${context.variableName} 上下文变量的值。
注意

仅支持特殊字符 . 和 _。
阶段变量 $stageVariables.variableName 或 ${stageVariables.variableName} 阶段变量的值。
静态值 string 常量值。
注意

要在选择表达式中使用多个变量，请将该变量括在括号中。例如，${request.path.name} ${request.path.id}。

转换 API 响应

在将响应返回给客户端之前，您可以使用响应参数转换来自后端集成的 HTTP 响应。在 API Gateway 将响应返回给客户端之前，您可以修改响应的标头或状态码。

您可以为集成返回的每个状态代码配置响应参数。响应参数是键值映射。键用于标识要更改的请求参数的位置以及如何更改它。值指定参数的新数据。

下表显示了支持的键。

响应参数映射键
类型 语法
标头 append|overwrite|remove:header.headername
状态代码 overwrite:statuscode

下表显示了可以映射到参数的支持值。

响应参数映射值
类型 语法 备注
标头值 $response.header.name 或 ${response.header.name} 标头名称不区分大小写。API Gateway 将多个标头值与逗号组合在一起，例如 "header1": "value1,value2"。保留一些标头。要了解更多信息，请参阅“保留的标头”。
响应正文 $response.body.name 或 ${response.body.name} JSON 路径表达式。不支持递归下降 ($response.body..name) 和筛选表达式 (?(expression))。
注意

当您指定 JSON 路径时，API Gateway 会在响应正文的 100 KB 处将其截断，然后应用选择表达式。要发送大于 100 KB 的负载，请指定 $response.body。
上下文变量 $context.variableName 或 ${context.variableName} 受支持的上下文变量的值。
阶段变量 $stageVariables.variableName 或 ${stageVariables.variableName} 阶段变量的值。
静态值 string 常量值。
注意

要在选择表达式中使用多个变量，请将该变量括在括号中。例如，${request.path.name} ${request.path.id}。

保留的标头

保留以下标头。您无法为这些标头配置请求或响应映射。

  • access-control-*

  • apigw-*

  • 授权

  • Connection

  • Content-Encoding

  • 内容长度

  • Content-Location

  • 已转发

  • Keep-Alive

  • Origin

  • Proxy-Authenticate

  • Proxy-Authorization

  • TE

  • Trailers

  • Transfer-Encoding

  • 升级

  • x-amz-*

  • x-amzn-*

  • X-Forwarded-For

  • X-Forwarded-Host

  • X-Forwarded-Proto

  • Via

示例

以下 Amazon CLI 示例会配置参数映射。如需示例 Amazon CloudFormation 模板，请参阅 GitHub。

向 API 请求添加标头

以下示例在 API 请求到达后端集成之前将名为 header1 的标头添加到该请求中。API Gateway 使用请求 ID 填充标头。

aws apigatewayv2 create-integration \
    --api-id abcdef123 \
    --integration-type HTTP_PROXY \
    --payload-format-version 1.0 \
    --integration-uri 'https://api.example.com' \
    --integration-method ANY \
    --request-parameters '{ "append:header.header1": "$context.requestId" }'

重命名请求标头

以下示例将请求标头从 header1 重命名为 header2。

aws apigatewayv2 create-integration \
    --api-id abcdef123 \
    --integration-type HTTP_PROXY \
    --payload-format-version 1.0 \
    --integration-uri 'https://api.example.com' \
    --integration-method ANY \
    --request-parameters '{ "append:header.header2": "$request.header.header1",  "remove:header.header1": "''"}'

更改集成的响应

以下示例为集成配置响应参数。当集成返回 500 状态码时，API Gateway 会将状态码更改为 403，然后在响应中添加 header11。当集成返回 404 状态码时，API Gateway 会向响应添加 error 标头。

aws apigatewayv2 create-integration \
    --api-id abcdef123 \
    --integration-type HTTP_PROXY \
    --payload-format-version 1.0 \
    --integration-uri 'https://api.example.com' \
    --integration-method ANY \
    --response-parameters '{"500" : {"append:header.header1": "$context.requestId", "overwrite:statuscode" : "403"}, "404" : {"append:header.error" : "$stageVariables.environmentId"}  }'

删除配置的参数映射

以下示例命令删除以前为 append:header.header1 配置的请求参数。它还删除了先前为 200 状态码配置的响应参数。

aws apigatewayv2 update-integration \
    --api-id abcdef123 \
    --integration-id hijk456 \
    --request-parameters '{"append:header.header1" : ""}' \
    --response-parameters '{"200" : {}}'