Amazon API Gateway
開発者ガイド

API キャッシュを有効にして応答性を強化する

Amazon API Gateway で API キャッシュを有効にして、エンドポイントのレスポンスがキャッシュされるようにできます。キャッシュを有効にすると、エンドポイントへの呼び出しの数を減らすことができ、また、API へのリクエストのレイテンシーを短くすることもできます。ステージに対してキャッシュを有効にすると、API Gateway は、秒単位で指定した有効期限 (TTL) が切れるまで、エンドポイントからのレスポンスをキャッシュします。その後、API Gateway は、エンドポイントへのリクエストを行う代わりに、キャッシュからのエンドポイントレスポンスを調べてリクエストに応答します。API キャッシュのデフォルトの TTL 値は 300 秒です。最大の TTL 値は 3600 秒です。TTL=0 は、キャッシュが無効なことを意味します。

これは HIPAA 対象サービスです。AWS、米国 Health Insurance Portability and Accountability Act of 1996 (HIPAA)、および AWS サービスを使用した保護されるべき医療情報 (PHI) の処理、保存、転送に関する詳細については、「HIPAA 概要」を参照してください。

重要

ステージに対してキャッシュを有効にすると、デフォルトではGET メソッドのみでキャッシュが有効になります。これは、API の安全性と可用性を確保するのに役立ちます。オーバーライドするメソッドの設定により、他のメソッドのキャッシュを有効にできます。

重要

キャッシュでは、時間単価で料金が発生し、AWS 無料利用枠の対象ではありません。

Amazon API Gateway キャッシュを有効にする

API Gateway では、指定されたステージでキャッシュを有効にできます。

キャッシュを有効にするときは、キャッシュ容量を選択する必要があります。一般的に、容量を大きくすると、パフォーマンスは良くなりますが、コストは増えます。

API Gateway で、キャッシュを有効にするには、専用のキャッシュインスタンスを作成します。このプロセスには最長 4 分かかることがあります。

API Gateway で、キャッシュの容量を変更するには、既存のキャッシュインスタンスを削除してから、変更した容量でキャッシュインスタンスを作成します。既存のキャッシュされたデータはすべて削除されます。

API Gateway コンソールで、Stage Editor の [設定] タブでキャッシュを設定します。

特定のステージの API キャッシュを設定するには

  1. API Gateway コンソールに移動します。

  2. API を選択します。

  3. [ステージ] を選択します。

  4. API の [ステージ] リストで、ステージを選択します。

  5. [Settings] タブを選択します。

  6. [API キャッシュを有効化] を選択します。

  7. キャッシュの作成が完了するのを待機します。

注記

キャッシュの作成または削除は、API Gateway が完了するまで約 4 分かかります。キャッシュが作成されると、[キャッシュのステータス] の値は CREATE_IN_PROGRESS から AVAILABLE に変わります。キャッシュの削除が完了すると、[キャッシュのステータス] の値は DELETE_IN_PROGRESS から空の文字列に変わります。

ステージの [キャッシュ設定] 内でキャッシュを有効にすると、GET メソッドのみがキャッシュされます。API の安全性と可用性を確保するため、この設定を変更しないことをお勧めします。ただし、オーバーライドするメソッドの設定により、他のメソッドのキャッシュを有効にできます。

キャッシュが想定どおり機能していることを確認するために、2 つの全般的なオプションがあります。

  • API とステージの CacheHitCount 数および CacheMissCount 数の CloudWatch メトリクスを調べる。

  • レスポンスにタイムスタンプを入力する。

注記

API が API Gateway キャッシュのインスタンスから供給されているかどうか確認するために、CloudFront レスポンスの X-Cache ヘッダーを使用しないでください。

API Gateway ステージレベルのキャッシュをメソッドキャッシュで上書きする

ステージレベルのキャッシュ設定は、特定のメソッドのキャッシュを有効または無効にする、TTL 期間を増減する、またはキャッシュされたレスポンスの暗号化のオンとオフを切り替えことで、オーバーライドできます。

キャッシュ中のメソッドがそのレスポンスで機密データを受け取ることが予想される場合は、[キャッシュ設定] で [キャッシュデータを暗号化する] を選択します。

コンソールを使用してメソッド別の API キャッシュを設定するには

  1. https://console.aws.amazon.com/apigateway で API Gateway コンソールにサインインします。

  2. API Gateway コンソールに移動します。

  3. API を選択します。

  4. [ステージ] を選択します。

  5. API の [ステージ] リストで、ステージを展開し、API のメソッドを選択します。

  6. [設定] の [このメソッドの上書き] を選択します。

  7. [キャッシュ設定] エリアで、[メソッドキャッシュの有効化] を設定またはオフにするか、その他の必要なオプションをカスタマイズできます。(このセクションは、ステージレベルのキャッシュが有効になっている場合にのみ表示されます。)

メソッドパラメーターまたは統合パラメーターをキャッシュキーとして使用して、キャッシュされたレスポンスにインデックスを付ける

キャッシュされたメソッドや統合に、カスタムヘッダー、URL パス、またはクエリ文字列の形式でパラメータを渡せる場合、パラメータの一部またはすべてを使用してキャッシュキーを作成できます。API Gateway は、使用されたパラメータ値に応じて、メソッドレスポンスをキャッシュできます。

注記

キャッシュキーはリソースにキャッシュを設定するときに必要です。

たとえば、以下の形式のリクエストがあるとします。

GET /users?type=... HTTP/1.1 host: example.com ...

このリクエストでは、typeadmin または 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 ...

API Gateway コンソールで、キャッシュキーにメソッドリクエストまたは統合リクエストのパラメータを含めるには、パラメータを追加した後に [キャッシュ] を選択します。


                メソッドパラメータまたは統合パラメータをキャッシュキーとして含めて、キャッシュされたレスポンスにインデックスを付ける

API Gateway で API ステージキャッシュをフラッシュする

API キャッシュが有効になったら、API ステージのキャッシュ全体をフラッシュして、API のクライアントが統合エンドポイントから最新のレスポンスを取得するようにできます。

API ステージキャッシュをフラッシュするには、API Gateway コンソールのステージエディタで、[設定] タブの [キャッシュ設定] セクションにある [キャッシュ全体をフラッシュ] ボタンを選択します。キャッシュのフラッシュオペレーションはほぼ瞬時に行われます。その結果、キャッシュステータスはフラッシュ直後に AVAILABLE になります。

注記

キャッシュがフラッシュされると、再度キャッシュが作成されるまで、統合エンドポイントからレスポンスが処理されます。この間に、統合エンドポイントに送信されるリクエストの数が増加する場合があります。これにより、API のレイテンシー全体が一時的に増える可能性があります。

API Gateway キャッシュエントリを無効にする

API のクライアントは既存のキャッシュエントリを無効化し、個別のリクエストに対して統合エンドポイントからそのエントリを再ロードできます。クライアントは、Cache-Control: max-age=0 ヘッダーを含むリクエストを送信する必要があります。クライアントは、クライアントが許可されている場合、キャッシュの代わりに統合エンドポイントから直接レスポンスを受け取ります。これは既存のキャッシュエントリを、統合エンドポイントから取得される新しいレスポンスで置き換えます。

クライアントのアクセス権限を付与するには、次の形式のポリシーを、ユーザーの IAM 実行ロールにアタッチします。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:InvalidateCache" ], "Resource": [ "arn:aws:execute-api:region:account-id:api-id/stage-name/GET/resource-path-specifier" ] } ] }

このポリシーでは、API Gateway 実行サービスが指定された 1 つまたは複数のリソースのリクエストに対してキャッシュを無効にします。対象リソースのグループを指定するには、account-idapi-id、および他のエントリの ARN 値 Resource に対してワイルドカード文字 (*) を使用します。API Gateway 実行サービスのアクセス権限の設定方法については、「IAM アクセス権限により API へのアクセスを制御する」を参照してください。

InvalidateCache ポリシーを適用しない場合、すべてのクライアントが API キャッシュを無効にできます。すべてまたはほとんどのクライアントが API キャッシュを無効にする場合、API のレイテンシーが非常に大きくなる可能性があります。

ポリシーが適用され、キャッシュが有効になり、認証が必要な場合、API Gateway コンソールの [未認証リクエストの処理] からオプションを選択して、未認証リクエストの処理方法を制御できます。


                キャッシュの無効化を設定する

3 つのオプションにより、次の動作が発生します。

  • 403 ステータスコードでリクエストに失敗する: 403 Unauthorized レスポンスが返されます。

    API を使用してこのオプションを設定するには、FAIL_WITH_403 を使用します。

  • キャッシュコントロールヘッダーを無視し、レスポンスヘッダーに警告を追加する: リクエストを処理し、レスポンスに警告ヘッダーを追加します。

    API を使用してこのオプションを設定するには、SUCCEED_WITH_RESPONSE_HEADER を使用します。

  • キャッシュコントロールヘッダーを無視する: リクエストを処理し、レスポンスで警告ヘッダーを追加しません。

    API を使用してこのオプションを設定するには、SUCCEED_WITHOUT_RESPONSE_HEADER を使用します。