轉換API閘道HTTPAPIs中的API要求和回應 - Amazon API Gateway
轉換API請求轉換API回應預留的標頭範例

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

轉換API閘道HTTPAPIs中的API要求和回應

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

轉換API請求

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

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

下表顯示支援的金鑰。

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

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

Type 語法 備註
標頭值 $ 請求. 頭。name 或 $ {請求。頭。name} 網域名稱需區分大小寫。API例如，閘道將多個標頭值與逗號結合在一起"header1": "value1,value2"。有些標頭為預留。如需進一步了解，請參閱 預留的標頭。
查詢字串值 $ 請求. 查詢字符串。name 或 $ {請求. 查詢字符串。name} 查詢字串名稱區分大小寫。API例如，閘道會將多個值與逗號結合在一起"querystring1" "Value1,Value2"。
請求內文 $ 請求. 體。name 或 $ {請求. 體。name} JSON路徑運算式。不支援遞迴下降 ($request.body..name)) 和篩選表達式 (?(expression))。
注意

當您指定JSON路徑時，APIGateway 會以 100 KB 截斷要求主體，然後套用選取項目運算式。若要傳送大於 100 KB 的承載，請指定 $request.body。
請求路徑。 $request.path 或 ${request.path} 請求路徑，不含階段名稱。
路徑參數 $ 請求. 路徑。name 或 $ {請求. 路徑。name} 請求中的路徑參數值。例如，如果路由為 /pets/{petId}，您可以透過 $request.path.petId 從請求映射 petId 參數。
環境變數 $ 上下文。variableName 或 $ {上下文。variableName} 內容變數的值。
注意

僅支援特殊字元 . 和 _。
階段變數 $stageVariables.variableName 或 $ {stageVariables.variableName} 階段變數的值。
靜態值 string 常數值。
注意

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

轉換API回應

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

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

下表顯示支援的金鑰。

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

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

Type 語法 備註
標頭值 $ 響應頭。name 或 $ {響應。頭。name} 網域名稱需區分大小寫。API例如，閘道將多個標頭值與逗號結合在一起"header1": "value1,value2"。有些標頭為預留。如需進一步了解，請參閱 預留的標頭。
回應內文 $ 回應. 身體。name 或 $ {響應. 身體。name} JSON路徑運算式。不支援遞迴下降 ($response.body..name) 和篩選表達式 (?(expression))。
注意

當您指定JSON路徑時，API閘道會以 100 KB 截斷回應主體，然後套用選取項運算式。若要傳送大於 100 KB 的承載，請指定 $response.body。
環境變數 $ 上下文。variableName 或 $ {上下文。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閘道填入要求識別碼的標頭。

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閘道會將狀態碼變更為 403，並在回應中加上 header1 1。當整合傳回 404 狀態碼時，API閘道會在回應中新增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" : {}}'