# 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 (10M バイト) の間の負でない整数に設定します。API で圧縮を無効にするには、`minimumCompressionSize` を null に設定するか、または完全に削除します。API Gateway コンソール、AWS CLI、または API Gateway REST API を使用して、API の圧縮を有効または無効にすることができます。
任意のサイズのペイロードに圧縮を適用する場合は、`minimumCompressionSize` 値をゼロに設定します。ただし、小さいサイズのデータを圧縮すると、実際にはデータサイズが大きくなる可能性があります。さらに、API Gateway での圧縮とクライアントでの解凍は、全体のレイテンシーを増加させ、より多くの計算時間を必要とする可能性があります。API に対してテストケースを実行して、最適な値を決定する必要があります。
クライアントは、API Gateway に対して、圧縮ペイロードと適切な `Content-Encoding` ヘッダーを含む API リクエストを送信して、統合エンドポイントにリクエストを渡す前に、解凍して適用可能なマッピングテンプレートを適用できます。圧縮が有効になって 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、または AWS SDK を使用して、API の圧縮を有効にできます。
既存の API では、圧縮を有効にした後、API をデプロイして変更を有効にする必要があります。新しい API の場合、API のセットアップ完了後に API をデプロイします。
**注記**
最も優先順位の高いコンテンツのエンコードは、API Gateway によってサポートされている必要があります。サポートされていない場合は、レスポンスペイロードに圧縮が適用されません。
**Topics**
+ [API Gateway コンソールを使用して API のペイロードの圧縮を有効にする](#api-gateway-enable-compression-console)
+ [AWS CLI を使用して API のペイロードの圧縮を有効にする](#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. [**Save changes**] (変更の保存) をクリックします。
## AWS CLI を使用して API のペイロードの圧縮を有効にする
次の [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 (10M バイト) の間の負でない整数値があります。これは圧縮のしきい値を測定します。ペイロードサイズがこの値よりも小さい場合、圧縮または解凍はペイロードに適用されません。ゼロに設定すると、任意のペイロードサイズの圧縮を許可します。
次の [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`
API Gateway は [RFC 7231](https://datatracker.ietf.org/doc/html/rfc7231#section-5.3.4) 仕様に従って、次の `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 リクエストを行うには、クライアントは `Content-Encoding` ヘッダーを[サポートされているコンテンツコーディング](api-gateway-enable-compression.md#api-gateway-supported-content-encodings)の 1 つで設定する必要があります。
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 はペイロードを圧縮しません。
+ `minimumCompressionSize` は、圧縮を有効にするために API で設定されています。
+ 統合レスポンスには `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
```
レスポンスのペイロードが圧縮されると、圧縮されたデータサイズのみがデータ転送に対して課金されます。