本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 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_tw/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_tw/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. 在以下網址登入 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 管理主控台 會自動`puppies`為您從 新增參數映射`method.request.header.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. 在以下網址登入 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 表達式](http://goessner.net/articles/JsonPath/index.html#e2)，從 JSON 請求內文中的欄位對應整合請求參數。下列範例會將方法請求內文對應至名為 `body-header` 的整合請求標頭，並將部分請求內文 (如 JSON 表達式所示) 對應至名為 `pet-price` 的整合請求標頭。
若要測試此範例，請提供包含價格類別的輸入，如下所示：
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
}
]
```
------
#### [ AWS 管理主控台 ]
**對應方法請求參數**
1. 在以下網址登入 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. 在以下網址登入 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. 針對 **item**，輸入 **integration.response.multivalueheader.item**
1. 針對 **location**，輸入 **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 表達式](http://goessner.net/articles/JsonPath/index.html#e2)。 |
| 階段變數 | stageVariables.name |
| 環境變數 | `context.name` 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 表達式](http://goessner.net/articles/JsonPath/index.html#e2)。 |
| 階段變數 | stageVariables.name |
| 環境變數 | `context.name` name 必須是[支援的環境變數](api-gateway-mapping-template-reference.md#context-variable-reference)之一。 |
| 靜態值 | ` 'static_value'` *static\$1value* 是字串常值，而且前後必須加上單引號。例如 `'https://www.example.com'`。 |