本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 在 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>

您可以使用請求參數，在請求到達後端整合之前變更請求。您可以修改標頭、查詢字串或請求路徑。

請求參數為金鑰-值映射。金鑰可確定要變更的請求參數的位置，以及變更方式。該值指定參數的新資料。

下表顯示支援的金鑰。


| Type | 語法 | 
| --- | --- | 
| 標頭 | append\$1overwrite\$1remove:header.headername | 
| 查詢字串 | append\$1overwrite\$1remove:querystring.querystring-name | 
| 路徑 | overwrite:path | 

下表顯示可映射至參數的支援值。


| Type | 語法 | 備註 | 
| --- | --- | --- | 
| 標頭值 | \$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，您可以透過 \$1request.path.petId 從請求映射 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 將回應傳回給用戶端之前，修改標題或回應的狀態碼。

您可以為整合傳回的每個狀態碼設定回應參數。回應參數為金鑰-值映射。金鑰可確定要變更的請求參數的位置，以及變更方式。該值指定參數的新資料。

下表顯示支援的金鑰。


| Type | 語法 | 
| --- | --- | 
| 標頭 | append\$1overwrite\$1remove:header.headername | 
| 狀態碼 | overwrite:statuscode | 

下表顯示可映射至參數的支援值。


| Type | 語法 | 備註 | 
| --- | --- | --- | 
| 標頭值 | \$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
+ Authorization
+ Connection
+ Content-Encoding
+ Content-Length
+ Content-Location
+ Forwarded
+ Keep-Alive
+ Origin
+ Proxy-Authenticate
+ Proxy-Authorization
+ TE
+ Trailers 
+ Transfer-Encoding
+ Upgrade
+ 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" : {}}'
```