转换 API 请求和响应 - Amazon API Gateway
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

转换 API 请求和响应

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

转换 API 请求

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

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

下表显示了支持的键。

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

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

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

当您指定 JSON 路径时,API Gateway 会在请求正文的 100 KB 处将其截断,然后应用选择表达式。要发送大于 100 KB 的负载,请指定 $request.body

请求路径 $request.path 请求路径,没有阶段名称。
路径参数 $request.path.name 请求中路径参数的值。例如,如果路由为 /pets/{petId},则可以从具有 $request.path.petId 的请求中映射 petId 参数。
上下文变量 $context.variableName 上下文变量的值。
阶段变量 $stageVariables.variableName 阶段变量的值。
静态值 string 常量值。

转换 API 响应

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

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

下表显示了支持的键。

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

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

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

当您指定 JSON 路径时,API Gateway 会在响应正文的 100 KB 处将其截断,然后应用选择表达式。要发送大于 100 KB 的负载,请指定 $response.body

上下文变量 $context.variableName 受支持的上下文变量的值。
阶段变量 $stageVariables.variableName 阶段变量的值。
静态值 string 常量值。

保留的标头

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

  • 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

示例

以下 AWS CLI 示例配置参数映射。例如 AWS 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-type HTTP_PROXY \ --payload-format-version 1.0 \ --integration-uri 'https://api.example.com' \ --integration-method ANY \ --request-parameters {"append:header.header1" : ""} \ --response-parameters {"200" : {}}