# REST API のパフォーマンスを最適化する
API を呼び出せるようにしたら、応答性を向上させるために最適化する必要があることに気づくかもしれません。API Gateway には、レスポンスキャッシュやペイロード圧縮など、API を最適化するためのいくつかの戦略が用意されています。このセクションでは、これらの機能を有効にする方法を説明しています。
**Topics**
+ [API Gateway での REST API のキャッシュ設定](api-gateway-caching.md)
+ [API Gateway での REST API のペイロード圧縮](api-gateway-gzip-compression-decompression.md)
# API Gateway での REST API のキャッシュ設定
API Gateway で API キャッシュを有効にして、エンドポイントのレスポンスをキャッシュできます。キャッシュを有効にすると、エンドポイントへの呼び出しの数を減らすことができ、また、API へのリクエストのレイテンシーを短くすることもできます。
ステージに対してキャッシュを有効にすると、API Gateway は、秒単位で指定した有効期限 (TTL) が切れるまで、エンドポイントからのレスポンスをキャッシュします。その後、API Gateway は、エンドポイントへのリクエストを行う代わりに、キャッシュからのエンドポイントのレスポンスを調べます。API キャッシュのデフォルトの TTL 値は 300 秒です。最大の TTL 値は 3600 秒です。TTL=0 は、キャッシュが無効なことを意味します。
**注記**
キャッシュはベストエフォートです。Amazon CloudWatch の `CacheHitCount` および `CacheMissCount` メトリクスを使用して、API Gateway が API キャッシュから提供するリクエストをモニタリングできます。
キャッシュが可能なレスポンスの最大サイズは 1048576 バイトです。キャッシュデータの暗号化は、キャッシュされているときのレスポンスのサイズを増やす可能性があります。
これは HIPAA 対象サービスです。AWS、1996 年制定の医療保険の相互運用性と説明責任に関する法律 (HIPAA)、および AWS のサービスを使用した保護対象医療情報 (PHI) の処理、保存、転送に関する詳細については、[HIPAA の概要](https://aws.amazon.com/compliance/hipaa-compliance/)を参照してください。
**重要**
ステージに対してキャッシュを有効にすると、デフォルトでは`GET` メソッドのみでキャッシュが有効になります。これは、API の安全性と可用性を確保するのに役立ちます。[オーバーライドするメソッドの設定](#override-api-gateway-stage-cache-for-method-cache)により、他のメソッドのキャッシュを有効にできます。
**重要**
キャッシュでは、選択したキャッシュサイズに応じて、時間単価で料金が発生します。キャッシュは AWS 無料利用枠の対象ではありません。詳細については、「[API Gateway の料金](https://aws.amazon.com/api-gateway/pricing/)」を参照してください。
## Amazon API Gateway のキャッシュを有効にする
API Gateway では、ステージ別にキャッシュを有効にすることができます。
キャッシュを有効にするときは、キャッシュ容量を選択する必要があります。一般的に、容量を大きくすると、パフォーマンスは良くなりますが、コストは増えます。サポートされているキャッシュサイズについては、*API Gateway API リファレンス*の「[cacheClusterSize](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateStage.html#apigw-CreateStage-request-cacheClusterSize)」を参照してください。
API Gateway で、キャッシュを有効にするには、専用のキャッシュインスタンスを作成します。このプロセスには最長 4 分かかることがあります。
API Gateway で、キャッシュの容量を変更するには、既存のキャッシュインスタンスを削除してから、変更した容量でキャッシュインスタンスを作成します。既存のキャッシュされたデータはすべて削除されます。
**注記**
キャッシュ容量は、キャッシュインスタンスの CPU、メモリ、およびネットワーク帯域幅に影響を及ぼします。その結果、キャッシュ容量はキャッシュのパフォーマンスに影響を与える可能性があります。
API Gateway では、10 分のロードテストを実行して、キャッシュ容量がワークロードに適していることを確認することをお勧めします。ロードテスト中のトラフィックが本番トラフィックを反映していることを確認します。例えば、ランプアップ、一定のトラフィック、およびトラフィックのスパイクを含めます。ロードテストには、キャッシュから提供できるレスポンスと、キャッシュに項目を追加する一意のレスポンスを含める必要があります。ロードテスト中に、レイテンシー、4xx、5xx、キャッシュヒット、キャッシュミスメトリクスをモニタリングします。これらのメトリクスに基づいて、必要に応じてキャッシュ容量を調整します。負荷テストの詳細については、「[レート制限に達しないように、最適な Amazon API Gateway キャッシュ容量を選択するにはどうすればよいですか？](https://repost.aws/knowledge-center/api-gateway-cache-capacity)」を参照してください。
------
#### [ AWS マネジメントコンソール ]
API Gateway コンソールの **[ステージ]** ページで、キャッシュを設定します。ステージキャッシュをプロビジョニングし、デフォルトのメソッドレベルのキャッシュ設定を指定します。デフォルトのメソッドレベルのキャッシュをオンにすると、メソッドにメソッドオーバーライドがある場合を除き、ステージのすべての `GET` メソッドでメソッドレベルのキャッシュが有効になります。ステージにデプロイした追加の `GET` メソッドでは、メソッドレベルのキャッシュが有効になります。ステージの特定のメソッドに対してメソッドレベルのキャッシュ設定を構成するには、メソッドオーバーライドを使用できます。メソッドオーバーライドの詳細については、「[API Gateway のステージレベルのキャッシュをメソッドレベルのキャッシュで上書きする](#override-api-gateway-stage-cache-for-method-cache)」を参照してください。
**特定のステージの API キャッシュを設定するには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. [**ステージ**] を選択します。
1. API の [**ステージ**] リストで、ステージを選択します。
1. **[ステージの詳細]** セクションで、**[編集]** を選択します。
1. **[その他の設定]** の **[キャッシュ設定]** で、**[API キャッシュをプロビジョニング]** をオンにします。
これで、ステージのキャッシュクラスターがプロビジョニングされます。
1. ステージのキャッシュを有効にするには、**[デフォルトのメソッドレベルのキャッシュ]** をオンにします。
これにより、ステージのすべての `GET` メソッドに対してメソッドレベルのキャッシュが有効になります。このステージにデプロイした追加の `GET` メソッドでは、メソッドレベルのキャッシュが有効になります。
**注記**
メソッドレベルのキャッシュに関する既存の設定がある場合は、デフォルトのメソッドレベルのキャッシュ設定を変更しても、既存の設定には影響しません。
![\[API キャッシュのプロビジョニングとデフォルトのメソッドレベルのキャッシュをオンにします。\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/api-caching-stage-flow.png)
1. **[Save changes]** (変更の保存) をクリックします。
------
#### [ AWS CLI ]
次の [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) コマンドは、キャッシュをプロビジョニングし、ステージ上のすべての `GET` メソッドに対してメソッドレベルのキャッシュをオンにするようにステージを更新します。
```
aws apigateway update-stage \
--rest-api-id a1b2c3 \
--stage-name 'prod' \
--patch-operations file://patch.json
```
`patch.json` の内容は以下のとおりです。
```
[
{
"op": "replace",
"path": "/cacheClusterEnabled",
"value": "true"
},
{
"op": "replace",
"path": "/cacheClusterSize",
"value": "0.5"
},
{
"op": "replace",
"path": "/*/*/caching/enabled",
"value": "true"
}
]
```
**注記**
メソッドレベルのキャッシュに関する既存の設定がある場合は、デフォルトのメソッドレベルのキャッシュ設定を変更しても、既存の設定には影響しません。
------
**注記**
キャッシュの作成または削除は、API Gateway が完了するまで約 4 分かかります。
キャッシュを作成すると、**[キャッシュクラスター]**] の値は `Create in progress` から `Active` に変わります。キャッシュの削除が完了すると、**[キャッシュクラスター]** の値は `Delete in progress` から `Inactive` に変わります。
ステージのすべてのメソッドに対してメソッドレベルのキャッシュをオンにすると、**[デフォルトのメソッドレベルのキャッシュ]** の値は `Active` に変わります。ステージのすべてのメソッドに対してメソッドレベルのキャッシュをオフにすると、**[デフォルトのメソッドレベルのキャッシュ]** の値は `Inactive` に変わります。メソッドレベルのキャッシュに関する既存の設定がある場合は、キャッシュのステータスを変更しても、既存の設定には影響しません。
ステージの **[キャッシュ設定]** 内でキャッシュを有効にすると、`GET` メソッドのみがキャッシュされます。API の安全性と可用性を確保するため、この設定を変更しないことをお勧めします。ただし、[オーバーライドするメソッドの設定](#override-api-gateway-stage-cache-for-method-cache)により、他のメソッドのキャッシュを有効にできます。
キャッシュが想定どおり機能していることを確認するために、2 つの全般的なオプションがあります。
+ API とステージの **CacheHitCount** および **CacheMissCount** の CloudWatch メトリクスを調べる。
+ レスポンスにタイムスタンプを入力する。
**注記**
API が API Gateway キャッシュインスタンスから提供されているかどうかを判断するために、CloudFront レスポンスの `X-Cache` ヘッダーを使用しないでください。
## API Gateway のステージレベルのキャッシュをメソッドレベルのキャッシュで上書きする
特定のメソッドのキャッシュをオンまたはオフにすることで、ステージレベルのキャッシュ設定を上書きできます。TTL 期間を変更したり、キャッシュされたレスポンスの暗号化のオン/オフを切り替えたりすることもできます。
キャッシュするメソッドのレスポンスに機密データが含まれる可能性がある場合は、キャッシュデータを暗号化してください。これは、さまざまなコンプライアンスフレームワークに準拠するために必要になる場合があります。詳細については、*AWS Security Hub ユーザーガイド*の「[Amazon API Gateway のコントロール](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html)」を参照してください。
------
#### [ AWS マネジメントコンソール ]
**[ステージの詳細]** でデフォルトのメソッドレベルのキャッシュ設定を変更しても、オーバーライドが設定されたメソッドレベルのキャッシュ設定には影響しません。
キャッシュ中のメソッドがそのレスポンスで機密データを受け取ることが予想される場合は、[**キャッシュ設定**] で [**キャッシュデータを暗号化する**] を選択します。
**コンソールを使用してメソッド別の API キャッシュを設定するには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. [API] を選択します。
1. [**ステージ**] を選択します。
1. API の [**ステージ**] リストで、ステージを展開し、API のメソッドを選択します。
1. **[メソッドオーバーライド]** セクションで、**[編集]** を選択します。
1. **[メソッド設定]** セクションで、**[メソッドキャッシュを有効にする]** をオンまたはオフにするか、その他の必要なオプションをカスタマイズします。
**注記**
ステージのキャッシュクラスターをプロビジョニングするまで、キャッシュはアクティブになりません。
1. **[保存]** を選択します。
------
#### [ AWS CLI ]
次の [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) コマンドは、`GET /pets` メソッドのキャッシュのみをオフにします。
```
aws apigateway update-stage /
--rest-api-id a1b2c3 /
--stage-name 'prod' /
--patch-operations file://patch.json
```
`patch.json` の内容は以下のとおりです。
```
[{
"op": "replace",
"path": "/~1pets/GET/caching/enabled",
"value": "false"
}]
```
------
## メソッドパラメータまたは統合パラメータをキャッシュキーとして使用して、キャッシュされたレスポンスにインデックスを付ける
メソッドパラメータまたは統合パラメータをキャッシュキーとして使用して、キャッシュされたレスポンスにインデックスを付けることができます。これには、カスタムヘッダー、URL パス、またはクエリ文字列が含まれます。これらのパラメータの一部またはすべてをキャッシュキーとして指定できますが、少なくとも 1 つの値を指定する必要があります。キャッシュキーがある場合、API Gateway は (キャッシュキーが存在しないときも含め) 各キー値からのレスポンスを個別にキャッシュします。
**注記**
キャッシュキーはリソースにキャッシュを設定するときに必要です。
たとえば、以下の形式のリクエストがあるとします。
```
GET /users?type=... HTTP/1.1
host: example.com
...
```
このリクエストでは、`type` は `admin` または `regular` の値を受け取ることができます。キャッシュキーに `type` パラメータを含めた場合、`GET /users?type=admin` からのレスポンスと `GET /users?type=regular` からのレスポンスは別々にキャッシュされます。
メソッドリクエストまたは統合リクエストが複数のパラメータを受け取るときは、パラメータの一部またはすべてを含めてキャッシュキーを作成するように選択できます。たとえば、指定した順に TTL 期間内に行われる以下のリクエストに対して、キャッシュキーに `type` パラメータのみを含めることができます。
```
GET /users?type=admin&department=A HTTP/1.1
host: example.com
...
```
このリクエストからのレスポンスがキャッシュされ、以下のリクエストの処理に使用されます。
```
GET /users?type=admin&department=B HTTP/1.1
host: example.com
...
```
------
#### [ AWS マネジメントコンソール ]
API Gateway コンソールで、キャッシュキーにメソッドリクエストまたは統合リクエストのパラメータを含めるには、パラメータを追加した後に [**Caching (キャッシュ)**] を選択します。
![\[メソッドパラメータまたは統合パラメータをキャッシュキーとして含め、キャッシュされたレスポンスにインデックスを付ける\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/api-caching-including-parameter-as-cache-key-new-console.png)
------
#### [ AWS CLI ]
次の [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) コマンドは、`GET` メソッドを作成し、`type` クエリ文字列パラメータを必須とします。
```
aws apigateway put-method /
--rest-api-id a1b2c3 /
--resource-id aaa111 /
--http-method GET /
--authorization-type "NONE" /
--request-parameters "method.request.querystring.type=true"
```
次の [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) コマンドは、HTTP エンドポイントを使用する `GET` メソッドの統合を作成し、API Gateway が `type` メソッドリクエストパラメータをキャッシュするように指定します。
```
aws apigateway put-integration /
--rest-api-id a1b2c3 /
--resource-id aaa111 /
--http-method GET /
--type HTTP /
--integration-http-method GET /
--uri 'https://example.com' /
--cache-key-parameters "method.request.querystring.type"
```
API Gateway が統合リクエストパラメータをキャッシュするように指定するには、キャッシュキーパラメータとして `integration.request.location.name` を使用します。
------
## API Gateway で API ステージキャッシュをフラッシュする
API キャッシュが有効になったら、API ステージのキャッシュをフラッシュして、API のクライアントが統合エンドポイントから最新のレスポンスを取得できるようにします。
------
#### [ AWS マネジメントコンソール ]
**API ステージキャッシュをフラッシュするには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. キャッシュを含むステージがある API を選択します。
1. メインナビゲーションペインで、**[ステージ]** を選択し、キャッシュを含むステージを選択します。
1. **[ステージアクション]** メニューを選択した後、**[ステージキャッシュをフラッシュする]** を選択します。
------
#### [ AWS CLI ]
次の [flush-stage-cache](https://docs.aws.amazon.com/cli/latest/reference/apigateway/flush-stage-cache.html) コマンドは、ステージキャッシュをフラッシュします。
```
aws apigateway flush-stage-cache \
--rest-api-id a1b2c3 \
--stage-name prod
```
------
**注記**
キャッシュがフラッシュされると、再度キャッシュが作成されるまで、統合エンドポイントからレスポンスが処理されます。この間に、統合エンドポイントに送信されるリクエストの数が増加する場合があります。これにより、API のレイテンシー全体が一時的に増える可能性があります。
## API Gateway のキャッシュエントリの無効化
API のクライアントは既存のキャッシュエントリを無効化し、個別のリクエストに対して統合エンドポイントからそのエントリを再ロードできます。クライアントは、`Cache-Control: max-age=0` ヘッダーを含むリクエストを送信する必要があります。クライアントは、クライアントが許可されている場合、キャッシュの代わりに統合エンドポイントから直接レスポンスを受け取ります。これは既存のキャッシュエントリを、統合エンドポイントから取得される新しいレスポンスで置き換えます。
クライアントのアクセス許可を付与するには、次の形式のポリシーを、ユーザーの IAM 実行ロールにアタッチします。
**注記**
クロスアカウントのキャッシュ無効化はサポートされていません。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:InvalidateCache"
],
"Resource": [
"arn:aws:execute-api:us-east-1:111111111111:api-id/stage-name/GET/resource-path-specifier"
]
}
]
}
```
------
このポリシーでは、API Gateway 実行サービスが指定された 1 つまたは複数のリソースのリクエストに対してキャッシュを無効にします。対象リソースのグループを指定するには、`account-id`、`api-id`、および他のエントリの ARN 値 `Resource` に対してワイルドカード文字 (\$1) を使用します。API Gateway 実行サービスのアクセス許可の設定方法については、「[IAM アクセス許可を使用して REST API へのアクセスを制御する](permissions.md)」を参照してください。
`InvalidateCache` ポリシーを適用しない場合 (またはコンソールで [**認可が必要**] チェックボックスをオンにした場合)、すべてのクライアントが API キャッシュを無効にできます。すべてまたはほとんどのクライアントが API キャッシュを無効にする場合、API のレイテンシーが非常に大きくなる可能性があります。
ポリシーが設定されると、キャッシュが有効になり、承認が必要になります。
API Gateway で未認可リクエストを処理する方法は、次のオプションから選択することで指定できます。
**403 ステータスコードでリクエストを失敗させる**
API Gateway は `403 Unauthorized` レスポンスを返します。
API を使用してこのオプションを設定するには、`FAIL_WITH_403` を使用します。
**キャッシュコントロールヘッダーを無視する - レスポンスヘッダーに警告を追加する**
API Gateway はリクエストを処理し、レスポンスに警告ヘッダーを追加します。
API を使用してこのオプションを設定するには、`SUCCEED_WITH_RESPONSE_HEADER` を使用します。
**キャッシュコントロールヘッダーを無視する**
API Gateway はリクエストを処理し、レスポンスに警告ヘッダーを追加しません。
API を使用してこのオプションを設定するには、`SUCCEED_WITHOUT_RESPONSE_HEADER` を使用します。
未認可リクエストの処理動作は、API Gateway コンソールまたは AWS CLI を使用して設定できます。
------
#### [ AWS マネジメントコンソール ]
**未認可リクエストの処理方法を指定するには**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。
1. キャッシュを含むステージがある API を選択します。
1. メインナビゲーションペインで、**[ステージ]** を選択し、キャッシュを含むステージを選択します。
1. **[ステージの詳細]** で、**[編集]** を選択します。
1. **[未認可リクエストの処理]** でオプションを選択します。
1. [**続行**] をクリックしてください。
1. 変更内容を確認してから、**[変更を保存]** を選択します。
------
#### [ AWS CLI ]
次の [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) コマンドで、403 ステータスコードでリクエストを失敗させることで未認可リクエストを処理するようにステージを更新します。
```
aws apigateway update-stage /
--rest-api-id a1b2c3 /
--stage-name 'prod' /
--patch-operations 'op=replace,path=/*/*/caching/unauthorizedCacheControlHeaderStrategy,value="FAIL_WITH_403"'
```
------
## キャッシュを含むステージの CloudFormation の例
次の CloudFormation テンプレートは、API の例を作成し、`Prod` ステージに `0.5` GB のキャッシュをプロビジョニングし、すべての `GET` メソッドに対してメソッドレベルのキャッシングを有効にします。
**重要**
キャッシュでは、選択したキャッシュサイズに応じて、時間単価で料金が発生します。キャッシュは AWS 無料利用枠の対象ではありません。詳細については、「[API Gateway の料金](https://aws.amazon.com/api-gateway/pricing/)」を参照してください。
### CloudFormation テンプレートの例
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Name: cache-example
PetsResource:
Type: 'AWS::ApiGateway::Resource'
Properties:
RestApiId: !Ref Api
ParentId: !GetAtt Api.RootResourceId
PathPart: 'pets'
PetsMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: GET
ApiKeyRequired: true
AuthorizationType: NONE
Integration:
Type: HTTP_PROXY
IntegrationHttpMethod: GET
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
ApiDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn:
- PetsMethodGet
Properties:
RestApiId: !Ref Api
ApiStage:
Type: 'AWS::ApiGateway::Stage'
Properties:
StageName: Prod
Description: Prod Stage with a cache
RestApiId: !Ref Api
DeploymentId: !Ref ApiDeployment
CacheClusterEnabled: True
CacheClusterSize: 0.5
MethodSettings:
- ResourcePath: /*
HttpMethod: '*'
CachingEnabled: True
```
# 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
```
レスポンスのペイロードが圧縮されると、圧縮されたデータサイズのみがデータ転送に対して課金されます。