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

Media CDN では、カスタム リクエスト ヘッダーとカスタム レスポンス ヘッダーを指定できます。

カスタム ヘッダーを使用すると、次のことができます。

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

ヘッダーを使用して、リクエストを異なる送信元にルーティングすることもできます。クロスオリジン リソース シェアリング(CORS)ヘッダーを構成する必要がある場合は、ルートごとに CORS ポリシーを構成します。

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

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

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

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

次の .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 country (or region) associated with the client's IP address.
        - headerName: "client-geo"
          headerValue: "{client_region}"
          replace: true
      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"

この例では、次の操作を行います。

  • {client_region} 変数を使用してレスポンスにカスタム client-geo ヘッダーを追加します。これは、クライアントの IP アドレスに関連付けられている国(またはリージョン)を返します。
  • 静的文字列を使用して、カスタム x-downstream-cdn ヘッダーをリクエストに追加します。
  • 2 つの内部ヘッダーを削除します。

動的ヘッダー変数

カスタム ヘッダーには、1 つ以上の動的変数を含めることができます。

キャッシュキー ポリシー(cacheKeyPolicy.includedHeaderNames)の一部であるリクエスト ヘッダーには、1 つ以上のカスタム変数を含めることができます。他の動的変数を含むリクエスト ヘッダーをキャッシュキーの一部にすることはできません。

変数 説明 リクエスト ヘッダーでのサポート キャッシュキーのリクエスト ヘッダーでのサポート レスポンス ヘッダーでのサポート
cdn_cache_status リクエスト / レスポンス パス内の各キャッシュ ノードのロケーション(最も近い空港の IATA コード)とステータスのカンマ区切りのリスト。右端の値は、ユーザーに最も近いキャッシュを表します。
client_city リクエスト送信元の市区町村の名前。たとえば、カリフォルニアの Mountain View の場合は Mountain View です。この変数について有効な値の正規リストはありません。都市名には、US-ASCII 文字、数字、スペース、および !#$%&'*+-.^_`|~ を含めることができます。
client_city_lat_long リクエスト送信元の都市の緯度と経度。たとえば、Mountain View からのリクエストの場合は 37.386051,-122.083851 です。
client_region クライアントの IP アドレスに関連付けられる国(またはリージョン)。これは、USFR などの Unicode CLDR リージョン コードです。 ほとんどの国では、このコードが ISO-3166-2 コードに直接対応しています。
client_region_subdivision サブディビジョン(クライアントの IP アドレスに関連付けられる国の県や州など)。これは、USCACAON などの Unicode CLDR サブディビジョン ID です。この Unicode コードは、ISO-3166-2 標準で定義されているサブディビジョンから派生しています。
client_rtt_msec CDN と HTTP(S) クライアント間の推定ラウンドトリップ送信時間(ミリ秒単位)。これは、ロードバランサの TCP スタックによって測定される平滑化されたラウンドトリップ時間(SRTT)パラメータです(RFC 2988 を遵守)。
device_request_type クライアントが使用しているデバイスのタイプ。有効な値は次のとおりです。DESKTOPMOBILETABLETSMART_TVGAME_CONSOLEWEARABLEUNDETERMINED
original_request_id このレスポンスを最初に生成したリクエストに割り当てられた一意の識別子。キャッシュに保存されたレスポンスの request_id とは異なる場合にのみ入力されます。
origin_name レスポンスがプロキシされた EdgeCacheOrigin リソース。
origin_request_header クロスオリジン リソース シェアリング(CORS)のユースケースのリクエストに含まれる送信元ヘッダーの値を反映したものになります。
proxy_status レスポンスパス内の中間 HTTP プロキシのリスト。値は RFC 9209 で定義されています。 EdgeCacheService リソースは、Google-Edge-Cache と表されます。レスポンスが送信元から取得された場合、EdgeCacheOrigin リソースは Google-Edge-Cache-Origin で表されます。
tls_sni_hostname RFC 6066 で定義されたサーバー名表示(TLS または QUIC handshake 中にクライアントによって提供された場合)。ホスト名は小文字に変換され、末尾のドットはすべて削除されます。
tls_version SSL handshake 中にクライアントとロードバランサの間でネゴシエートされた TLS バージョン。可能な値は、TLSv1TLSv1.1TLSv1.2TLSv1.3 などです。クライアントが TLS ではなく QUIC を使用して接続した場合、値は QUIC です。
tls_cipher_suite TLS handshake 中にネゴシエートされた暗号スイート。値は IANA TLS 暗号スイートレジストリで定義されます(例: TLS_RSA_WITH_AES_128_GCM_SHA256)。この値は、QUIC と暗号化されていないクライアント接続の場合には空です。
user_agent_family クライアントが使用しているブラウザ ファミリー。有効な値は次のとおりです。APPLEAPPLEWEBKITBLACKBERRYDOCOMOGECKOGOOGLEKHTMLKOREANMICROSOFTMSIENOKIANETFRONTOBIGOOPENWAVEOPERAOTHERPOLARISTELECASEMCSMITUSER_DEFINED

カスタム変数に関しては、次の点を考慮する必要があります。

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

    • X-User-IP
    • X-Google または X-GFE を含む任意のヘッダー
  • ヘッダーの鍵と値は、RFC 7230 に準拠している必要があります。旧式の形式は許可されません。

  • すべてのヘッダーキーは小文字です(HTTP/2 を遵守)。

  • 一部のヘッダーは統合されます。同じヘッダーキー(例: Via)を持つ複数のインスタンスがある場合は、ロードバランサはそれらの値を 1 つのヘッダーキーを持つ、1 つのカンマ区切りのリストにまとめます。値をカンマ区切りのリストで表すことができるヘッダーのみが統合されます。 その他のヘッダー(Set-Cookie など)が結合されることはありません。

  • いくつかのヘッダーが追加されるか、値が追加されます。 Media CDN は常に、ViaX-Forwarded-For などの特定のヘッダーを追加または変更します。

  • Media CDN は、クライアントや送信元で設定されていたとしても、サポートされている変数を含む任意のレスポンス ヘッダーを展開します。これにより、カスタム ヘッダーの構成に加えて、クライアント(動画プレーヤーなど)または送信元のインフラストラクチャから動的ヘッダーを設定できます。Media CDN では、リクエストパスの変数は展開されません。

  • たとえば、前述のルールに従って、X-Goog- ヘッダーと X-Amz- ヘッダーは保持され、小文字になります。

キャッシュ ステータス値

{cdn_cache_status} ヘッダー変数は、レスポンスを提供したキャッシュの階層に対応する複数の値を返すことができます。{cdn_cache_status} ヘッダー変数の解釈には、次のガイドラインを参考にしてください。

  • ヘッダーに hit が含まれている場合、リクエストされたコンテンツはキャッシュから取得されています。
  • ヘッダーに miss が含まれている場合、リクエストされたコンテンツはキャッシュ ノードで見つからないため、アップストリーム ノードから取得する必要がありました。
  • ヘッダーに fetch が含まれている場合、リクエストされたコンテンツは送信元から取得されています。
  • ヘッダーに uncacheable が含まれている場合、リクエストされたコンテンツは、キャッシュ インフラストラクチャの一部またはすべてのコンポーネントでキャッシュ不可とみなされています。

    • ヘッダーに hit または miss も含まれている場合、リクエストされたコンテンツは、一部のキャッシュ コンポーネントではキャッシュ不可、他のコンポーネントではキャッシュ可能とみなされています。
    • ヘッダーに hit または miss も含まれていない場合、リクエストされたコンテンツは、すべてのキャッシュ コンポーネントでキャッシュ不可とみなされ、このコンテンツに対するすべてのリクエストは送信元から取得されます。コンテンツが適切にキャッシュに保存されるようにするには、Media CDN の送信元の要件を確認してください。

デフォルトのヘッダー

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)のロケーションやキャッシュ ステータス(hitmiss など)など、その他のヘッダーは、動的ヘッダー変数を使用して追加できます。