カスタム ヘッダーを定義する

Media CDN では、カスタム リクエスト ヘッダーとカスタム レスポンス ヘッダーを指定できます。カスタム リクエスト ヘッダーは静的値をサポートしますが、カスタム レスポンス ヘッダーは静的値と動的値の両方をサポートしています。

カスタム ヘッダーによって、次のことができます。

  • 国、リージョン、都市など、クライアントに関する地理データを返し、ローカライズされたコンテンツの表示に使用できます。
  • レスポンスがキャッシュから提供されているかどうか（全体または一部）と、レスポンスを送信するキャッシュのロケーションを決定します。
  • リクエスト ヘッダーとレスポンス ヘッダーの両方を除去または置き換えます。

高度なルーティングのドキュメントで説明されているように、ヘッダーを使用してリクエストをさまざまな送信元にルーティングすることもできます。クロスオリジン リソース シェアリング（CORS）ヘッダーを構成する必要がある場合は、ルートごとに CORS ポリシーを構成します。

カスタム ヘッダーを設定する

ヘッダーはルートごとに設定されるため、マニフェストや動画セグメントなどのさまざまなコンテンツのヘッダーを追加および削除できます。

デフォルトでは、追加されたヘッダー値は、同じフィールド名を持つレスポンス ヘッダーまたはリクエスト ヘッダーに追加されます。追加する値はカンマで区切ります。

既存の値を上書きするには、replace を true に設定します。

次の .routing.pathMatchers[].routeRules[].headerAction の例は、EdgeCacheService で追加および削除されるヘッダーを示しています。

gcloud edge-cache services describe prod-media-service

routeRules:
- priority: 1
  description: "video routes"
  matchRules:
  - prefixMatch: "/video/"
  headerAction:
    responseHeadersToAdd:
      # Return the IATA (airport) code(s) nearest the cache node(s) that served
      # the response
      - headerName: "cache-id"
        headerValue: "{cdn_cache_id}"
        replace: true
      # Return how the response was served - for example, "MISS, HIT"
      - headerName: "x-cache-status"
        headerValue: "{cdn_cache_status}"
    requestHeadersToAdd:
      # Inform the upstream origin server the request is from Media CDN
      - headerName: "x-downstream-cdn"
        headerValue: "Media CDN"
    responseHeadersToRemove:
      - headerName: "X-User-ID"
      - headerName: "X-Other-Internal-Header"

この例は以下のように実行されます。

  • {cdn_cache_id} 変数を使用してレスポンスにカスタム Cache-ID ヘッダーを追加します。これは、リクエストの実行に使用されたキャッシュ ID（階層化された入力の場合は複数の ID）が表示されます。
  • 静的文字列を使用して、カスタム x-downstream-cdn ヘッダーをリクエストに追加します。
  • 2 つの内部ヘッダーを削除します。

動的ヘッダー変数

レスポンス ヘッダーでは、Cloud CDN と HTTP(S) ロード バランシングでサポートされているものと同一のカスタム変数がサポートされています。

サポートされる変数のリストは、次のように定義されています。

変数 説明
cdn_cache_id リクエストの処理に使用されるキャッシュ インスタンスのロケーション コードと ID。 これは、Logging の Cloud CDN リクエストログの jsonPayload.cacheId フィールドに入力されている値と同じです。
cdn_cache_status 現在のキャッシュ ステータス。値には、キャッシュに保存されたレスポンスのステータスと、キャッシュの提供元であるキャッシュの階層（存在する場合）が反映されます。
origin_request_header クロスオリジン リソース シェアリング（CORS）のユースケースのリクエストに含まれる送信元ヘッダーの値を反映したものになります。
client_rtt_msec ロードバランサと HTTP(S) クライアント間の推定ラウンドトリップ送信時間（ミリ秒単位）。これは、ロードバランサの TCP スタックによって測定される平滑化されたラウンドトリップ時間（SRTT）パラメータです（RFC 2988 を遵守）。
client_region クライアントの IP アドレスに関連付けられる国（またはリージョン）。これは、US や FR などの Unicode CLDR リージョン コードです。（ほとんどの国では、このコードが ISO-3166-2 コードに直接対応しています）。
client_region_subdivision 下位地域区分 - クライアントの IP アドレスに関連付けられる国の区分（たとえば、都道府県や州）。これは Unicode CLDR サブディビジョン ID です（USCA や CAON など）。（この Unicode コードは、ISO-3166-2 標準で定義されている下位地域区分から派生しています）。
client_city リクエスト送信元の市区町村の名前です。たとえば、カリフォルニアの Mountain View は Mountain View です。この変数について有効な値の正規リストはありません。都市名には、US-ASCII 文字、数字、スペース、および !#$%&'*+-.^_`|~ を含めることができます。
client_city_lat_long リクエスト送信元の都市の緯度と経度です。たとえば、Mountain View からのリクエストの場合には 37.386051,-122.083851 となります。
tls_sni_hostname （RFC 6066 で定義された）サーバー名表示（TLS または QUIC handshake 中にクライアントによって提供された場合）。ホスト名は小文字に変換され、末尾のドットはすべて削除されます。
tls_version SSL handshake 中にクライアントとロードバランサの間でネゴシエートされた TLS バージョン。可能な値は、TLSv1、TLSv1.1、TLSv1.2、TLSv1.3 などです。クライアントが TLS ではなく QUIC を使用して接続した場合、値は QUIC です。
tls_cipher_suite TLS handshake 中にネゴシエートされた暗号スイート。値は、IANA TLS Cipher Suite Registry で定義された 4 桁の 16 進数です。たとえば、TLS_RSA_WITH_AES_128_GCM_SHA256 の場合は 009C となります。この値は、QUIC と暗号化されていないクライアント接続の場合には空です。

既存のリクエスト ヘッダーとレスポンス ヘッダーは保持されますが、次のものは削除されます。

  • X-User-IP
  • X-Google または X-GFE を含む任意のヘッダー

次の特長があります。

  • ヘッダーの鍵と値は、RFC 7230 に準拠している必要があります。旧式の形式は許可されません。
  • すべてのヘッダーキーは小文字（HTTP/2 ごと）です。
  • 一部のヘッダーは統合されます。同じヘッダーキー（例: Via）を持つ複数のインスタンスがある場合は、ロードバランサはそれらの値を 1 つのヘッダーキーを持つ、1 つのカンマ区切りのリストにまとめます。値をカンマ区切りのリストで表すことができるヘッダーのみが統合されます。その他のヘッダー（Set-Cookie など）は統合されません。
  • いくつかのヘッダーが追加されるか、値が追加されます。外部 HTTP(S) ロードバランサは、Via や X-Forwarded-For などの特定のヘッダーを常に追加、または変更します。
  • Media CDN は、クライアントや送信元で設定されていたとしても、サポートされている変数を含む任意のレスポンス ヘッダーを展開します。これにより、カスタム ヘッダーの構成に加えて、クライアント（動画プレーヤーなど）または送信元のインフラストラクチャから動的ヘッダーを設定できます。Media CDN は、リクエストパスの変数を展開しません。

キャッシュ ステータスの値

{cdn_cache_status} ヘッダー変数は、レスポンスを提供したキャッシュの階層に対応する複数の値を返すことができます。

値 説明
HIT キャッシュに保存されているレスポンスが完全にキャッシュから提供されました。
MISS レスポンスがキャッシュにありません。
PARTIAL レスポンスが部分的にキャッシュから提供されました。

大きなオブジェクト（2 MB 以上）の場合、キャッシュの一部バイトしか利用できず、残りのリクエストされたレスポンスに入力するために HTTP Range リクエストが作成されることを意味しています。
REVALIDATED レスポンスがキャッシュに存在しましたが、提供される前に送信元との再検証が必要でした。
BYPASSED キャッシュはバイパスされました。これは、所与のルートの cdnPolicy.cacheMode が BYPASS_CACHE に設定されている場合に発生します（たとえば、デバッグ時）。
UNCACHEABLE レスポンスがキャッシュから提供できず、送信元から直接取得されました。これは、構成された cdnPolicy.cacheMode によって、レスポンスに有効なキャッシュ ディレクティブが含まれていない場合、レスポンスがキャッシュするには大きすぎる場合、またはキャッシュ可能なコンテンツ タイプではない場合に発生することがあります。

対応するリクエストログの cache_details フィールドには理由が含まれています。

レスポンスパスのキャッシュの各階層（該当する場合）が、ヘッダー値に追加されます。

例:

  • ユーザーに最も近いキャッシュでキャッシュ レスポンスが使用できないが、次の階層で実行された場合、cdn_cache_status は HIT, MISS になります。
  • キャッシュの最初の 2 つの階層でキャッシュ レスポンスが使用できず、レスポンスの部分的なチャンクのみがキャッシュで使用できた場合、cdn_cache_status は PARTIAL, MISS, MISS になります。

BYPASSED と UNCACHEABLE が適用されるリクエストとレスポンスの場合、これらの値はキャッシュの全階層に適用されるため、cdn_cache_status には 1 つの値しか表示されません。

デフォルトのヘッダー

Media CDN は、送信元のリクエストとクライアントのレスポンスにそれぞれ次のリクエスト ヘッダーとレスポンス ヘッダーを追加します。

ヘッダー 詳細 リクエスト レスポンス
x-request-id 所与のリクエストの一意の識別子。この値はリクエスト ログにも jsonPayload.requestId として追加されるため、クライアントのリクエストとレスポンスをログエントリに関連付けることができます。 ✔
age キャッシュに保存されたオブジェクトの経過時間（キャッシュに存在している秒数）を返します。経過時間は、通常、オブジェクトがロングテール（シールド）キャッシュのロケーションに最初にキャッシュされた時点に基づいて計算されます。

Age ヘッダーのないレスポンスはキャッシュから提供されません。

 ✔
via Google を中間プロキシとして識別します。

1.1 google として設定され、変更できません。

 ✔ ✔
server これは Google-Edge-Cache として設定されています。 ✔
cdn-loop 「ループ」を識別します。たとえば、送信元ホストがユーザー向けの（エッジ）ホストと同じである場合です。

RFC 8586 に従って、google のトークンがヘッダーに追加されます。トークンは変更できません。

 ✔
forwarded x-forwarded-for ヘッダーの構造化バージョン。forwarded ヘッダーは、RFC 7239 で定義されています。

これらのヘッダーによって、1 つのプロキシ（または複数のプロキシ）がパス内にあるときに、接続クライアントの IP アドレスを識別できます。たとえば、IP アドレス 192.0.2.60 を持つクライアントが HTTPS 上で Media CDN に接続する場合、forwarded ヘッダーには次のように入力されます。

forwarded: [for=192.0.2.60;proto=https]

複数のクライアント側プロキシの場合、Media CDN に接続したクライアントはヘッダー値に追加される最後のアドレスになります。		 ✔
x-forwarded-for 非構造化で事実上の forwarded ヘッダーの標準版。通常、値はカンマで区切ります。

両方のヘッダーは、forwarded ヘッダーを認識できない場合がある従来の送信元をサポートするリクエストで送信されます。

 ✔

ヘッダーキーは小文字で大文字と小文字を区別しないため、リクエスト ヘッダーとレスポンス ヘッダーの両方で小文字が指定されます。

エッジ POP ロケーションやキャッシュ ステータス（HIT、MISS など）などのその他のヘッダーは、動的ヘッダー変数を介して追加できます。