您可以在客户端 API 请求到达后端集成之前修改它们。您还可以在 API Gateway 将响应返回给客户端之前更改集成的响应。您可以使用参数映射修改 HTTP API 的 API 请求和响应。要使用参数映射，您需要指定要修改的 API 请求或响应参数，并指定如何修改这些参数。
转换 API 请求
在请求到达后端集成之前，您可以使用请求参数更改请求。您可以修改标头、查询字符串或请求路径。
请求参数是键值映射。键用于标识要更改的请求参数的位置以及如何更改它。值指定参数的新数据。
下表显示了支持的键。
| 类型 | 语法 |
|---|---|
| 标头 | append|overwrite|remove:header. |
| 查询字符串 | append|overwrite|remove:querystring. |
| 路径 | 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.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. |
| 状态代码 | 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 的负载，请指定 |
| 上下文变量 | $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
示例
以下 AWS CLI 示例会配置参数映射。如需示例 AWS CloudFormation 模板，请参阅 GitHub
向 API 请求添加标头
以下 create-integration 命令在 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" }'
重命名请求标头
以下 create-integration 命令将请求标头从 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": "''"}'
更改集成的响应
以下 create-integration 命令为集成配置响应参数。当集成返回 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"} }'
删除配置的参数映射
以下 update-integration 命令删除以前为 append:header.header1 配置的请求参数。它还删除了先前为 200 状态码配置的响应参数。
aws apigatewayv2 update-integration \ --api-id abcdef123 \ --integration-id hijk456 \ --request-parameters '{"append:header.header1" : ""}' \ --response-parameters '{"200" : {}}'
