轉換 API Gateway 中 HTTP API 的 API 要求和回應

您可以在用戶端到達後端整合之前修改 API 請求。您也可以在 API Gateway 將回應傳回給用戶端之前，變更來自整合變的回應。您可以使用參數映射，來修改 HTTP API 的 API 請求和回應。若要使用參數映射，請指定要修改的 API 請求或回應參數，並指定如何修改這些參數。

轉換 API 請求

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

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

下表顯示支援的金鑰。

參數映射金鑰
類型	語法
標頭	append|overwrite|remove:header.headername
查詢字串	append|overwrite|remove:querystring.querystring-name
路徑	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.body。
請求路徑。	$request.path 或 ${request.path}	請求路徑，不含階段名稱。
路徑參數	$request.path.name 或 ${request.path.name}	請求中的路徑參數值。例如，如果路由為 /pets/{petId}，您可以透過 $request.path.petId 從請求映射 petId 參數。
環境變數	$context.variableName 或 ${context.variableName}	內容變數的值。 注意 僅支援特殊字元 . 和 _。
階段變數	$stageVariables.variableName 或 ${stageVariables.variableName}	階段變數的值。
靜態值	string	常數值。

注意

要在選擇表達式中使用多個變數，請將變數括在括號內。例如：${request.path.name} ${request.path.id}。

轉換 API 回應

您可以使用回應參數，在將回應傳回給用戶端之前，從後端整合轉換 HTTP 回應。您可以在 API Gateway 將回應傳回給用戶端之前，修改標題或回應的狀態碼。

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

下表顯示支援的金鑰。

回應參數映射金鑰
類型	語法
標頭	append|overwrite|remove:header.headername
狀態碼	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 的承載，請指定 $response.body。
環境變數	$context.variableName 或 ${context.variableName}	支援的內容變數值。
階段變數	$stageVariables.variableName 或 ${stageVariables.variableName}	階段變數的值。
靜態值	string	常數值。

注意

要在選擇表達式中使用多個變數，請將變數括在括號內。例如：${request.path.name} ${request.path.id}。

預留的標頭

以下標題為預留。您無法設定這些標頭的請求或回應映射。

• access-control-*

• apigw-*

• Authorization

• Connection

• Content-Encoding

• Content-Length

• Content-Location

• Forwarded

• Keep-Alive

• Origin

• Proxy-Authenticate

• Proxy-Authorization

• TE

• Trailers

• Transfer-Encoding

• Upgrade

• x-amz-*

• x-amzn-*

• X-Forwarded-For

• X-Forwarded-Host

• X-Forwarded-Proto

• Via

範例

下列 AWS CLI 範例設定參數對映。如需範 AWS CloudFormation 本範本，請參閱GitHub。

將標頭新增至 API 請求

下列範例會在 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" }' 

重新命名請求標頭

下列範例會將請求標頭從 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": "''"}'

變更整合的回應

下列範例會設定整合的回應參數。若整合傳回 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"}  }'

移除已設定的參數映射

下列範例命令會移除之前設定的請求參數 append:header.header1。還會移除 200 狀態碼之前設定的回應參數。

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