API Gateway:キャッシュプラグイン

1. 注意事項

• GET メソッドに対するレスポンスのみがキャッシュされます。

• default group second-level domain を使用するリクエストはキャッシュできません。default group second-level domain はテスト専用であり、1 日あたりの呼び出し回数は 1,000 回に制限されています。中国本土以外のリージョンおよび香港 (中国) では、1 日あたり 100 回に制限されています。

• キャッシュを区別するには、次の設定を追加します：

  • varyByApp：アプリに基づいてキャッシュを区別します。

  • varyByParameters：パラメータ値に基づいてキャッシュを区別します。パラメータは、バインドされた API で定義されている名前と一致する必要があります。

  • varyByHeaders：Accept や Accept-Language などのリクエストヘッダーに基づいてキャッシュを区別します。

• 各ユーザーには、リージョンごとに 1 MB のキャッシュ領域が割り当てられます。領域は有効期限ポリシーに基づいて解放されます。キャッシュがいっぱいの場合、以降のレスポンスはキャッシュされません。

• バックエンドのレスポンスに Cache-Control ヘッダーが含まれている場合、API Gateway はそのポリシーに従ってレスポンスをキャッシュします。含まれていない場合は、キャッシュプラグインの duration パラメータで指定した期間、レスポンスをキャッシュします。

• 最大有効期限は 48 時間 (172,800 秒) です。この制限を超える値は無効として扱われ、既定で 48 時間になります。

• 既定では、API Gateway はクライアントの Cache-Control ヘッダーを無視します。この動作を変更するには、clientCacheControl パラメータを使用します。mode には次の値を指定できます：

  • off：すべてのクライアントリクエストの Cache-Control ヘッダーを無視します。

  • all：すべてのクライアントリクエストの Cache-Control ヘッダーを処理します。

  • app：アプリ ID が apps 設定リストに含まれているリクエストに対してのみ、Cache-Control ヘッダーを処理します。

• 既定では、API Gateway は Content-Type、Content-Length、Content-Language のレスポンスヘッダーのみをキャッシュします。追加のヘッダーをキャッシュするには、cacheableHeaders パラメータを設定します。

2. プラグインの設定

プラグインは JSON または YAML 形式で設定します。両形式は同じスキーマを共有しており、yaml to json ツールで相互に変換できます。次のテンプレートは YAML 形式を使用しています。

---
varyByApp: false    # API 呼び出し元のアプリ ID に基づいて、キャッシュされたレスポンスを照合して返すかどうかを指定します。既定値：false。
varyByParameters:   # 特定のパラメータの値に基づいて、キャッシュされたレスポンスを照合して返すかどうかを指定します。
- userId            # バックエンドパラメータの名前です。バックエンドパラメータが別名のパラメータにマッピングされている場合は、このパラメータにマッピング先のパラメータ名を設定します。
varyByHeaders:      # 異なるリクエストヘッダーに基づいて、キャッシュされたレスポンスを照合して返すかどうかを指定します。
- Accept            # Accept ヘッダーに基づいて、キャッシュされたレスポンスを照合して返します。
clientCacheControl: # API Gateway は、clientCacheControl 設定に基づいてクライアントリクエストの Cache-Control ヘッダーをどのように処理するかを決定します。
  mode: "app"       # 有効な値：off、all、app。既定値：off。off は、すべてのクライアントリクエストの Cache-Control ヘッダーを無視することを示します。all は、すべてのクライアントリクエストの Cache-Control ヘッダーを処理することを示します。app は、設定済みの apps リストにアプリ ID が含まれるクライアントリクエストの Cache-Control ヘッダーのみを処理することを示します。
  apps:             # アプリ ID のリストです。mode が app に設定されている場合、このリストに含まれるアプリ ID を持つリクエストの Cache-Control ヘッダーのみを処理します。
  - 1992323         # サンプルのアプリ ID です。AppKey ではありません。
  - 1239922         # サンプルのアプリ ID です。AppKey ではありません。
cacheableHeaders:   # キャッシュ可能なレスポンスヘッダーフィールドです。既定では、`Content-Type`、`Content-Length`、`Content-Language` ヘッダーフィールドのみをキャッシュできます。
- X-Customer-Token  # キャッシュ可能なレスポンスヘッダーの名前です。
duration: 3600      # キャッシュ内にレスポンスを保存する既定期間です。単位：秒。        

3. 実行ルール

• API Gateway でキャッシュヒットが発生すると、レスポンスに X-Ca-Caching: true ヘッダーが含まれます。

4. 制限

• プラグインメタデータのサイズは 50 KB に制限されています。

• サイズが 128 KB を超えるレスポンスボディはキャッシュできません。

• サーバーレスインスタンスでは、ユーザーごとのキャッシュ上限はリージョンあたり合計 1 MB です。専有インスタンスについては、インスタンス仕様をご参照ください。

• API Gateway はキャッシュの手動更新をサポートしていません。設定した duration の有効期限が切れるとキャッシュは自動的に再生成されるため、有効期限前に手動で更新をトリガーすることはできません。キャッシュされたコンテンツを更新するには、duration パラメータを調整するか、キャッシュの有効期限が切れるのを待ってください。