本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # API Gateway 中 REST API 的承載壓縮 API Gateway 可讓您的用戶端對使用其中一個[支援的內容編碼](api-gateway-enable-compression.md#api-gateway-supported-content-encodings)壓縮的承載呼叫 API。API Gateway 預設支援方法請求承載的解壓縮功能。不過，您必須設定 API，才能啟用方法回應承載的壓縮功能。 若要啟用 [https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) 的壓縮功能，請在建立 API 時，或在建立 API 之後，將 [https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#minimumCompressionSize](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#minimumCompressionSize) 屬性設定為介於 0 到 10485760 (一千萬個位元組) 之間的非負整數。若要停用 API 的壓縮功能，請將 `minimumCompressionSize` 設定為 Null 或將其完全移除。您可以使用 API Gateway 主控台、 或 API Gateway REST API AWS CLI來啟用或停用 API 的壓縮。 如果您想要對任何大小的承載套用壓縮功能，請將 `minimumCompressionSize` 值設定為零。不過，壓縮大小很小的資料實際上可能會增加最終資料大小。此外，在 API Gateway 壓縮與在用戶端解壓縮可能會增加整體延遲，而需要更多的運算時間。您應該對 API 執行測試案例來決定最佳值。 用戶端可以提交已壓縮承載並具有適當 `Content-Encoding` 標頭的 API 請求，讓 API Gateway 解壓縮並套用適用的對應範本，再將請求傳遞到整合端點。啟用壓縮功能並部署 API 之後，若在方法請求中指定適當的 `Accept-Encoding` 標頭，用戶端就會收到已壓縮承載的 API 回應。 當整合端點預期並傳回未壓縮的 JSON 承載時，針對未壓縮 JSON 承載設定的任何對應範本都適用於壓縮的承載。對於壓縮的方法請求承載，API Gateway 會解壓縮承載、套用對應範本，然後將對應的請求傳遞到整合端點。對於未壓縮的整合回應承載，API Gateway 會套用對應範本、壓縮對應的承載，然後將壓縮的承載傳回用戶端。 **Topics** + [在 API Gateway 中啟用 API 的承載壓縮功能](api-gateway-enable-compression.md) + [在 API Gateway 中使用壓縮的承載呼叫 API 方法](api-gateway-make-request-with-compressed-payload.md) + [在 API Gateway 中使用壓縮的承載接收 API 回應](api-gateway-receive-response-with-compressed-payload.md) # 在 API Gateway 中啟用 API 的承載壓縮功能 您可以使用 API Gateway 主控台 AWS CLI、 或 SDK 啟用 API 的 AWS 壓縮。 針對現有的 API，您必須在啟用壓縮後部署 API，以使變更生效。針對新的 API，您可以在 API 設定完成後部署 API。 **注意** 優先順序最高的內容編碼必須是 API Gateway 支援的項目，否則系統不會將壓縮功能套用至回應承載。 **Topics** + [使用 API Gateway 主控台啟用 API 的承載壓縮功能](#api-gateway-enable-compression-console) + [使用 啟用 API 的承載壓縮 AWS CLI](#api-gateway-enable-compression-cli) + [API Gateway 支援的內容編碼](#api-gateway-supported-content-encodings) ## 使用 API Gateway 主控台啟用 API 的承載壓縮功能 下列程序說明如何啟用 API 的承載壓縮功能。 **使用 API Gateway 主控台來啟用承載壓縮功能** 1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。 1. 選擇現有的 API 或建立新的 API。 1. 在主導覽窗格中，選擇 **API 設定**。 1. 在 **API 詳細資訊**區段中，選擇**編輯**。 1. 開啟**內容編碼**以啟用承載壓縮。針對**內文大小下限**，輸入代表壓縮大小下限的數字 (位元組)。若要關閉壓縮，請關閉**內容編碼**選項。 1. 選擇**儲存變更**。 ## 使用 啟用 API 的承載壓縮 AWS CLI 以下 [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html) 命令會建立具有承載壓縮的 API： ``` aws apigateway create-rest-api \ --name "My test API" \ --minimum-compression-size 0 ``` 以下 [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) 命令會啟用現有 API 的承載壓縮： ``` aws apigateway update-rest-api \ --rest-api-id 1234567890 \ --patch-operations op=replace,path=/minimumCompressionSize,value=0 ``` `minimumCompressionSize` 屬性擁有介於 0 和 10485760 的非負數整數值 (1 千萬個位元組)。它可衡量壓縮閾值。如果承載大小小於這個值，則不會對承載進行壓縮或解壓縮。因此，請將此值設為零以允許任何承載大小使用壓縮功能。 以下 [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) 命令會關閉承載壓縮： ``` aws apigateway update-rest-api \ --rest-api-id 1234567890 \ --patch-operations op=replace,path=/minimumCompressionSize,value= ``` 您也可以將 `value` 設定為空白字串 `""`，或在先前的呼叫中徹底省略 `value` 屬性。 ## API Gateway 支援的內容編碼 API Gateway 支援下列內容編碼： + `deflate` + `gzip` + `identity` 根據 [RFC 7231](https://datatracker.ietf.org/doc/html/rfc7231#section-5.3.4) 規格，API Gateway 也支援下列 `Accept-Encoding` 標頭格式： + `Accept-Encoding:deflate,gzip` + `Accept-Encoding:` + `Accept-Encoding:*` + `Accept-Encoding:deflate;q=0.5,gzip;q=1.0` + `Accept-Encoding:gzip;q=1.0,identity;q=0.5,*;q=0` # 在 API Gateway 中使用壓縮的承載呼叫 API 方法 若要提出已壓縮承載的 API 請求，用戶端必須使用其中一個[支援的內容編碼](api-gateway-enable-compression.md#api-gateway-supported-content-encodings)來設定 `Content-Encoding` 標頭。 假設您是 API 用戶端並想要呼叫 PetStore API 方法 (`POST /pets`)。請勿使用下列 JSON 輸出呼叫方法： ``` POST /pets Host: {petstore-api-id}.execute-api.{region}.amazonaws.com Content-Length: ... { "type": "dog", "price": 249.99 } ``` 您可以改為對使用 GZIP 編碼壓縮的相同承載呼叫方法： ``` POST /pets Host: {petstore-api-id}.execute-api.{region}.amazonaws.com Content-Encoding:gzip Content-Length: ... ���RPP*�,HU�RPJ�OW��e&���L,�,-y�j ``` 當 API Gateway 收到請求時，它會確認指定的內容編碼是否受到支援。然後，它會嘗試使用指定的內容編碼解壓縮承載。如果解壓縮成功，則會將請求發送到整合端點。如果指定的編碼不受支援或提供的承載未使用指定的編碼壓縮，API Gateway 會傳回 `415 Unsupported Media Type` 錯誤回應。如果在識別 API 與階段之前的解壓縮階段初期發生錯誤，該錯誤不會記錄到 CloudWatch Logs。 # 在 API Gateway 中使用壓縮的承載接收 API 回應 對已啟用壓縮功能的 API 提出請求時，用戶端可以透過指定 `Accept-Encoding` 標頭與[支援的內容編碼](api-gateway-enable-compression.md#api-gateway-supported-content-encodings)，選擇接收特定格式的壓縮回應承載。 只有符合下列條件時，API Gateway 才會壓縮回應承載： + 傳入請求具有 `Accept-Encoding` 標頭以及支援的內容編碼與格式。 **注意** 如果未設定標頭，預設值為 `*`，如 [RFC 7231](https://datatracker.ietf.org/doc/html/rfc7231#section-5.3.4) 中所定義。在此情況下，API Gateway 不會壓縮承載。某些瀏覽器或用戶端可能會自動將 `Accept-Encoding` (例如 `Accept-Encoding:gzip, deflate, br`) 新增至已啟用壓縮功能的請求。這會開啟 API Gateway 中的承載壓縮功能。若未明確指定支援的 `Accept-Encoding` 標頭值，API Gateway 就不會壓縮承載。 + 在 API 上設定 `minimumCompressionSize` 以啟用壓縮功能。 + 整合回應沒有 `Content-Encoding` 標頭。 + 整合回應承載的大小在套用適用的映射範本之後，大於或等於指定的 `minimumCompressionSize` 值。 API Gateway 會套用針對整合回應設定的任何對應範本，再壓縮承載。如果整合回應包含 `Content-Encoding` 標頭，API Gateway 會假設整合回應承載已壓縮並略過壓縮處理。 以 PetStore API 為例，其請求如下： ``` GET /pets Host: {petstore-api-id}.execute-api.{region}.amazonaws.com Accept: application/json ``` 後端會以類似如下的未壓縮 JSON 承載來回應請求： ``` 200 OK [ { "id": 1, "type": "dog", "price": 249.99 }, { "id": 2, "type": "cat", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ] ``` 若要接收此輸出作為壓縮的承載，您的 API 用戶端可以提交請求，如下所示： ``` GET /pets Host: {petstore-api-id}.execute-api.{region}.amazonaws.com Accept-Encoding:gzip ``` 用戶端會收到具有 `Content-Encoding` 標頭與 GZIP 編碼承載的回應，如下所示： ``` 200 OK Content-Encoding:gzip ... ���RP� J�)JV �:P^IeA*������+(�L �X�YZ�ku0L0B7!9��C#�&����Y��a���^�X ``` 壓縮回應承載之後，只有壓縮的資料大小會計入數據傳輸費。