# API Gateway 中 REST API 的参数映射
**注意**
如果您使用的是 HTTP API，请参阅[针对 API Gateway 中的 HTTP API 转换 API 请求和响应](http-api-parameter-mapping.md)。
在参数映射中，您可以映射请求或响应参数。您可以使用参数映射表达式或静态值来映射参数。有关映射表达式的列表，请参阅 [API Gateway 中 REST API 的参数映射源参考](rest-api-parameter-mapping-sources.md)。您可以在代理和非代理集成的集成请求中使用参数映射，但要将参数映射用于集成响应，则需要非代理集成。
例如，您可以将方法请求标头参数 `puppies` 映射到集成请求标头参数 `DogsAge0`。然后，如果客户端将标头 `puppies:true` 发送到您的 API，则集成请求会将请求标头 `DogsAge0:true` 发送到集成端点。下图显示了此示例的请求生命周期。
![\[请求的 API Gateway 参数映射示例图\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/parameter-mapping-example1.png)
要使用 API Gateway 创建此示例，请参阅[示例 1：将方法请求参数映射到集成请求参数](request-response-data-mappings.md#request-response-data-mappings-example-1)。
再举一个例子，您也可以将集成响应标头参数 `kittens` 映射到方法响应标头参数 `CatsAge0`。然后，如果集成端点返回 `kittens:false`，则客户端将收到标头 `CatsAge0:false`。下图显示了此示例的请求生命周期。
![\[响应的 API Gateway 参数映射示例图\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/parameter-mapping-example2.png)
**Topics**
+ [API Gateway 中 REST API 的参数映射示例](request-response-data-mappings.md)
+ [API Gateway 中 REST API 的参数映射源参考](rest-api-parameter-mapping-sources.md)
# API Gateway 中 REST API 的参数映射示例
以下示例显示如何使用 API Gateway 控制台、OpenAPI 和 CloudFormation 模板创建参数映射表达式。有关如何使用参数映射来创建所需 CORS 标头的示例，请参阅[针对 API Gateway 中的 REST API 的 CORS](how-to-cors.md)。
## 示例 1：将方法请求参数映射到集成请求参数
以下示例将方法请求标头参数 `puppies` 映射到集成请求标头参数 `DogsAge0`。
------
#### [ AWS 管理控制台 ]
**映射方法请求参数**
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 选择一个 REST API。
1. 选择方法。
您的方法必须具有非代理集成。
1. 对于**方法请求设置**，选择**编辑**。
1. 选择 **HTTP 请求标头**。
1. 选择**添加标头**。
1. 对于**名称**，请输入 **puppies**。
1. 选择**保存**。
1. 选择**集成请求**选项卡，然后对于**集成请求设置**，选择**编辑**。
AWS 管理控制台会自动为您添加从 `method.request.header.puppies ` 到 `puppies` 的参数映射，但您需要更改**名称**，以匹配集成端点所期望的请求标头参数。
1. 对于**名称**，请输入 **DogsAge0**。
1. 选择**保存**。
1. 重新部署 API 以使更改生效。
以下步骤向您展示如何验证参数映射是否成功。
**（可选）测试参数映射**
1. 选择**测试**选项卡。您可能需要选择右箭头按钮，以显示该选项卡。
1. 对于标头，输入 **puppies:true**。
1. 选择**测试**。
1. 在**日志**中，结果应该类似以下内容：
```
Tue Feb 04 00:28:36 UTC 2025 : Method request headers: {puppies=true}
Tue Feb 04 00:28:36 UTC 2025 : Method request body before transformations:
Tue Feb 04 00:28:36 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets
Tue Feb 04 00:28:36 UTC 2025 : Endpoint request headers: {DogsAge0=true, x-amzn-apigateway-api-id=abcd1234, Accept=application/json, User-Agent=AmazonAPIGateway_aaaaaaa, X-Amzn-Trace-Id=Root=1-abcd-12344}
```
请求标头参数已从 `puppies` 更改为 `DogsAge0`。
------
#### [ CloudFormation ]
在此示例中，您使用 [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) 属性将 OpenAPI 定义文件导入到 API Gateway。
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: ParameterMappingExample
version: "2025-02-04T00:30:41Z"
paths:
/pets:
get:
parameters:
- name: puppies
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.DogsAge0: method.request.header.puppies
passthroughBehavior: when_no_match
type: http
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "ParameterMappingExample",
"version" : "2025-02-04T00:30:41Z"
},
"paths" : {
"/pets" : {
"get" : {
"parameters" : [ {
"name" : "puppies",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.DogsAge0" : "method.request.header.puppies"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
}
}
```
------
## 示例 2：将多个方法请求参数映射到不同的集成请求参数
以下示例将多值方法请求查询字符串参数 `methodRequestQueryParam` 映射到集成请求查询字符串参数 `integrationQueryParam`，并将方法请求标头参数 `methodRequestHeaderParam` 映射到集成请求路径参数 `integrationPathParam`。
------
#### [ AWS 管理控制台 ]
**映射方法请求参数**
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 选择一个 REST API。
1. 选择方法。
您的方法必须具有非代理集成。
1. 对于**方法请求设置**，选择**编辑**。
1. 选择 **URL 查询字符串参数**。
1. 选择**添加查询字符串**。
1. 在**名称**中，输入 **methodRequestQueryParam**。
1. 选择 **HTTP 请求标头**。
1. 选择**添加标头**。
1. 对于**名称**，请输入 **methodRequestHeaderParam**。
1. 选择**保存**。
1. 选择**集成请求**选项卡，然后对于**集成请求设置**，选择**编辑**。
1. 选择 **URL 路径参数**。
1. 选择**添加路径参数**。
1. 对于**名称**，请输入 **integrationPathParam**。
1. 对于**映射自**，输入 **method.request.header.methodRequestHeaderParam**。
这会将您在方法请求中指定的方法请求标头映射到新的集成请求路径参数。
1. 选择 **URL 查询字符串参数**。
1. 选择**添加查询字符串**。
1. 在**名称**中，输入 **integrationQueryParam**。
1. 对于**映射自**，输入 **method.request.multivaluequerystring.methodRequestQueryParam**。
这会将多值查询字符串参数映射到新的单值集成请求查询字符串参数。
1. 选择**保存**。
1. 重新部署 API 以使更改生效。
------
#### [ CloudFormation ]
在此示例中，您使用 [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) 属性将 OpenAPI 定义文件导入到 API Gateway。
以下 OpenAPI 定义为 HTTP 集成创建以下参数映射：
+ 将方法请求的名为 `methodRequestHeaderParam` 的标头映射到名为 `integrationPathParam` 的集成请求路径参数
+ 将名为 `methodRequestQueryParam` 的多值方法请求查询字符串映射到名为 `integrationQueryParam` 的集成请求查询字符串
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example 2
version: "2025-01-15T19:12:31Z"
paths:
/:
post:
parameters:
- name: methodRequestQueryParam
in: query
schema:
type: string
- name: methodRequestHeaderParam
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.querystring.integrationQueryParam: method.request.multivaluequerystring.methodRequestQueryParam
integration.request.path.integrationPathParam: method.request.header.methodRequestHeaderParam
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
type: http
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
以下 OpenAPI 定义为 HTTP 集成创建以下参数映射：
+ 将方法请求的名为 `methodRequestHeaderParam` 的标头映射到名为 `integrationPathParam` 的集成请求路径参数
+ 将名为 `methodRequestQueryParam` 的多值方法请求查询字符串映射到名为 `integrationQueryParam` 的集成请求查询字符串
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example 2",
"version" : "2025-01-15T19:12:31Z"
},
"paths" : {
"/" : {
"post" : {
"parameters" : [ {
"name" : "methodRequestQueryParam",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "methodRequestHeaderParam",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.querystring.integrationQueryParam" : "method.request.multivaluequerystring.methodRequestQueryParam",
"integration.request.path.integrationPathParam" : "method.request.header.methodRequestHeaderParam"
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000,
"type" : "http"
}
}
}
}
}
```
------
## 示例 3：将 JSON 请求正文中的字段映射到集成请求参数
还可以使用 [JSONPath expression](http://goessner.net/articles/JsonPath/index.html#e2) 从 JSON 请求正文中的字段映射集成请求参数。以下示例将方法请求正文映射到名为 `body-header` 的集成请求标头，并将部分请求正文（由 JSON 表达式表示）映射到名为 `pet-price` 的集成请求标头。
要测试此示例，请提供包含价格类别的输入，如下所示：
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
}
]
```
------
#### [ AWS 管理控制台 ]
**映射方法请求参数**
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 选择一个 REST API。
1. 选择 `POST`、`PUT`、`PATCH` 或 `ANY` 方法。
您的方法必须具有非代理集成。
1. 对于**集成请求设置**，选择**编辑**。
1. 选择 **URL 请求标头参数**。
1. 选择**添加请求标头参数**。
1. 对于**名称**，请输入 **body-header**。
1. 对于**映射自**，输入 **method.request.body**。
这会将方法请求正文映射到新的集成请求标头参数。
1. 选择**添加请求标头参数**。
1. 对于**名称**，请输入 **pet-price**。
1. 对于**映射自**，输入 ** method.request.body[0].price**。
这会将方法请求正文的一部分映射到新的集成请求标头参数。
1. 选择**保存**。
1. 重新部署 API 以使更改生效。
------
#### [ CloudFormation ]
在此示例中，您使用 [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) 属性将 OpenAPI 定义文件导入到 API Gateway。
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example 3
version: "2025-01-15T19:19:14Z"
paths:
/:
post:
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.pet-price: method.request.body[0].price
integration.request.header.body-header: method.request.body
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
type: http
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
以下 OpenAPI 定义从 JSON 请求正文中的字段映射集成请求参数。
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example 3",
"version" : "2025-01-15T19:19:14Z"
},
"paths" : {
"/" : {
"post" : {
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.pet-price" : "method.request.body[0].price",
"integration.request.header.body-header" : "method.request.body"
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000,
"type" : "http"
}
}
}
}
}
```
------
## 示例 4：将集成响应映射到方法响应
还可以将集成响应映射到方法响应。以下示例将集成响应正文映射到名为 `location` 的方法响应标头，将集成响应标头 `x-app-id` 映射到方法响应标头 `id`，并将多值集成响应标头 `item` 映射到方法响应标头 `items`。
------
#### [ AWS 管理控制台 ]
**映射集成响应**
1. 通过以下网址登录到 Amazon API Gateway 控制台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。
1. 选择一个 REST API。
1. 选择方法。
您的方法必须具有非代理集成。
1. 选择**方法响应**选项卡，然后对于**响应 200** 选择**编辑**。
1. 对于**标头名称**，选择**添加标头**。
1. 创建三个名为 **id**、**item**、和 **location** 的标头。
1. 选择**保存**。
1. 选择**集成响应**选项卡，然后对于**默认 - 响应**，选择**编辑**。
1. 在**标头映射**下，输入以下内容。
1. 对于 **id**，输入 **integration.response.header.x-app-id**
1. 对于**项目**，输入 **integration.response.multivalueheader.item**
1. 对于**位置**，输入 **integration.response.body.redirect.url**
1. 选择**保存**。
1. 重新部署 API 以使更改生效。
------
#### [ CloudFormation ]
在此示例中，您使用 [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) 属性将 OpenAPI 定义文件导入到 API Gateway。
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example
version: "2025-01-15T19:21:35Z"
paths:
/:
post:
responses:
"200":
description: 200 response
headers:
item:
schema:
type: string
location:
schema:
type: string
id:
schema:
type: string
x-amazon-apigateway-integration:
type: http
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.id: integration.response.header.x-app-id
method.response.header.location: integration.response.body.redirect.url
method.response.header.item: integration.response.multivalueheader.item
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
以下 OpenAPI 定义将集成响应映射到方法响应。
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example",
"version" : "2025-01-15T19:21:35Z"
},
"paths" : {
"/" : {
"post" : {
"responses" : {
"200" : {
"description" : "200 response",
"headers" : {
"item" : {
"schema" : {
"type" : "string"
}
},
"location" : {
"schema" : {
"type" : "string"
}
},
"id" : {
"schema" : {
"type" : "string"
}
}
}
}
},
"x-amazon-apigateway-integration" : {
"type" : "http",
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200",
"responseParameters" : {
"method.response.header.id" : "integration.response.header.x-app-id",
"method.response.header.location" : "integration.response.body.redirect.url",
"method.response.header.item" : "integration.response.multivalueheader.item"
}
}
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000
}
}
}
}
}
```
------
# API Gateway 中 REST API 的参数映射源参考
创建参数映射时，可以指定要修改的方法请求或集成响应参数，并指定如何修改这些参数。
下表显示了可以映射的方法请求参数以及用于创建映射的表达式。在这些表达式中，*name* 是方法请求参数的名称。例如，要映射请求标头参数 `puppies`，请使用表达式 `method.request.header.puppies`。您的表达式必须与正则表达式 `'^[a-zA-Z0-9._$-]+$]'` 匹配。您可以在代理和非代理集成的集成请求中使用参数映射。
| **映射的数据来源** | **映射表达式** |
| --- | --- |
| 方法请求路径 | method.request.path.name |
| 方法请求查询字符串 | method.request.querystring.name |
| 多值方法请求查询字符串 | method.request.multivaluequerystring.name |
| 方法请求标头 | method.request.header.name |
| 多值方法请求标头 | method.request.multivalueheader.name |
| 方法请求正文 | method.request.body |
| 方法请求正文 (JsonPath) | `method.request.body.JSONPath_EXPRESSION`. *JSONPath\$1EXPRESSION* 是请求正文的 JSON 字段的 JSONPath 表达式。有关更多信息，请参阅 [JSONPath expression](http://goessner.net/articles/JsonPath/index.html#e2)。 |
| 阶段变量 | stageVariables.name |
| 上下文变量 | `context.name` 名称必须为[受支持的上下文变量](api-gateway-mapping-template-reference.md#context-variable-reference)之一。 |
| 静态值 | `'static_value'`. *static\$1value* 为字符串文本值，必须括在一对单引号内。例如 `'https://www.example.com'`。 |
下表显示了可以映射的集成响应参数以及用于创建映射的表达式。在这些表达式中，*name* 是集成响应参数的名称。您可以从任何集成响应标头或集成响应正文、\$1context 变量或静态值映射方法响应标头。要将参数映射用于集成响应，您需要使用非代理集成。
| 映射数据源 | 映射表达式 |
| --- | --- |
| 集成响应标头 | integration.response.header.name |
| 集成响应标头 | integration.response.multivalueheader.name |
| 集成响应正文 | integration.response.body |
| 集成响应正文 (JsonPath) | `integration.response.body.JSONPath_EXPRESSION` *JSONPath\$1EXPRESSION* 是响应正文的 JSON 字段的 JSONPath 表达式。有关更多信息，请参阅 [JSONPath expression](http://goessner.net/articles/JsonPath/index.html#e2)。 |
| 阶段变量 | stageVariables.name |
| 上下文变量 | `context.name` 名称必须为[受支持的上下文变量](api-gateway-mapping-template-reference.md#context-variable-reference)之一。 |
| 静态值 | ` 'static_value'` *static\$1value* 为字符串文本值，必须括在一对单引号内。例如 `'https://www.example.com'`。 |