# 针对 API Gateway 中的 HTTP API 转换 API 请求和响应
<a name="http-api-parameter-mapping"></a>

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



## 转换 API 请求
<a name="http-api-mapping-request-parameters"></a>

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

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

下表显示了支持的键。


| 类型 | 语法 | 
| --- | --- | 
| 标头 | append\$1overwrite\$1remove:header.headername | 
| 查询字符串 | append\$1overwrite\$1remove:querystring.querystring-name | 
| 路径 | overwrite:path | 

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


| 类型 | 语法 | 备注 | 
| --- | --- | --- | 
| 标头值 | \$1request.header.name 或 \$1\$1request.header.name\$1 | 标头名称不区分大小写。API Gateway 将多个标头值与逗号组合在一起，例如 "header1": "value1,value2"。保留一些标头。要了解更多信息，请参阅“[保留的标头](#http-api-mapping-reserved-headers)”。 | 
| 查询字符串值 | \$1request.querystring.name 或 \$1\$1request.querystring.name\$1 | 查询字符串名称区分大小写。API Gateway 将多个值与逗号组合在一起，例如 "querystring1" "Value1,Value2"。 | 
| 请求正文 | \$1request.body.name 或 \$1\$1request.body.name\$1 | JSON 路径表达式 不支持递归下降 (\$1request.body..name) 和筛选表达式 (?(expression))。 当您指定 JSON 路径时，API Gateway 会在请求正文的 100 KB 处将其截断，然后应用选择表达式。要发送大于 100 KB 的负载，请指定 `$request.body`。  | 
| 请求路径 | \$1request.path 或 \$1 \$1request.path\$1 | 请求路径，没有阶段名称。 | 
| 路径参数 | \$1request.path.name 或 \$1\$1request.path.name\$1 | 请求中路径参数的值。例如，如果路由为 /pets/\$1petId\$1，则可以从具有 petId 的请求中映射 \$1request.path.petId 参数。 | 
| 上下文变量 | \$1context.variableName 或 \$1\$1context.variableName\$1 | [上下文变量](http-api-logging-variables.md)的值。仅支持特殊字符 `.` 和 `_`。 | 
| 阶段变量 | \$1stageVariables.variableName 或 \$1\$1stageVariables.variableName\$1 | [阶段变量](http-api-stages.stage-variables.md)的值。 | 
| 静态值 | string | 常量值。 | 

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

## 转换 API 响应
<a name="http-api-mapping-response-parameters"></a>

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

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

下表显示了支持的键。


| 类型 | 语法 | 
| --- | --- | 
| 标头 | append\$1overwrite\$1remove:header.headername | 
| 状态代码 | overwrite:statuscode | 

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


| 类型 | 语法 | 备注 | 
| --- | --- | --- | 
| 标头值 | \$1response.header.name 或 \$1\$1response.header.name\$1 | 标头名称不区分大小写。API Gateway 将多个标头值与逗号组合在一起，例如 "header1": "value1,value2"。保留一些标头。要了解更多信息，请参阅“[保留的标头](#http-api-mapping-reserved-headers)”。 | 
| 响应正文 | \$1response.body.name 或 \$1\$1response.body.name\$1 | JSON 路径表达式。不支持递归下降 (\$1response.body..name) 和筛选表达式 (?(expression))。 当您指定 JSON 路径时，API Gateway 会在响应正文的 100 KB 处将其截断，然后应用选择表达式。要发送大于 100 KB 的负载，请指定 `$response.body`。  | 
| 上下文变量 | \$1context.variableName 或 \$1\$1context.variableName\$1 | 受支持的[上下文变量](http-api-logging-variables.md)的值。 | 
| 阶段变量 | \$1stageVariables.variableName 或 \$1\$1stageVariables.variableName\$1 | [阶段变量](http-api-stages.stage-variables.md)的值。 | 
| 静态值 | string | 常量值。 | 

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

## 保留的标头
<a name="http-api-mapping-reserved-headers"></a>

保留以下标头。您无法为这些标头配置请求或响应映射。
+ access-control-\$1
+ apigw-\$1
+ 授权
+ Connection
+ Content-Encoding
+ 内容长度
+ Content-Location
+ 已转发
+ Keep-Alive
+ Origin
+ Proxy-Authenticate
+ Proxy-Authorization
+ TE
+ Trailers 
+ Transfer-Encoding
+ 升级
+ x-amz-\$1
+ x-amzn-\$1
+ X-Forwarded-For
+ X-Forwarded-Host
+ X-Forwarded-Proto
+ Via

## 示例
<a name="http-api-parameter-mapping-examples"></a>

以下 AWS CLI 示例会配置参数映射。如需示例 CloudFormation 模板，请参阅 [GitHub](https://github.com/awsdocs/amazon-api-gateway-developer-guide/tree/main/cloudformation-templates)。

### 向 API 请求添加标头
<a name="http-api-parameter-mapping-examples-request-header"></a>

以下 [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) 命令在 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" }'
```

### 重命名请求标头
<a name="http-api-parameter-mapping-examples-response"></a>

以下 [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) 命令将请求标头从 `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": "''"}'
```

### 更改集成的响应
<a name="http-api-parameter-mapping-examples-response"></a>

以下 [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) 命令为集成配置响应参数。当集成返回 500 状态码时，API Gateway 会将状态码更改为 403，然后在响应中添加 `header1`1。当集成返回 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"}  }'
```

### 删除配置的参数映射
<a name="http-api-parameter-mapping-examples-remove"></a>

以下 [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) 命令删除以前为 `append:header.header1` 配置的请求参数。它还删除了先前为 200 状态码配置的响应参数。

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