定義自訂標頭

Media CDN 可讓您指定自訂要求和回應標頭。

自訂標頭可讓您執行下列操作：

• 傳回用戶端的地理資料，例如國家/地區、區域或城市，可用於顯示本地化內容。
• 判斷回應是否從快取提供 (完整或部分)，以及提供回應的快取位置。
• 移除、取代或附加至要求和回應標頭。

設定自訂標頭

標頭是在每個路徑上設定，因此您可以為不同的內容 (例如資訊清單或影片片段) 新增及移除標頭。

在 CDN 處理路徑中，於快取決策前，盡早設定每個路徑的自訂要求標頭。舉例來說，如果您將 cache-control 標頭設為每個路徑的自訂標頭，CDN 中的快取行為就會受到影響。

根據預設，新增的標頭值會以半形逗號分隔，並附加至具有相同欄位名稱的回應或要求標頭。

如要覆寫現有值，請將 replace 設為 true。

gcloud 和 YAML

如要列出 EdgeCacheService 資源的 YAML 設定，請使用下列指令：

gcloud edge-cache services describe prod-media-service

「.routing.pathMatchers[].routeRules[].headerAction」部分會顯示要新增和移除的標頭：

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"

Terraform

下列 Terraform 程式碼片段顯示含有自訂標頭的路徑規則。

route_rule {
  description = "video routes"
  priority    = 1
  match_rule {
    prefix_match = "/video/"
  }
  origin = google_network_services_edge_cache_origin.default.name
  header_action {
    response_header_to_add {
      # Return the country (or region) associated with the client's IP address.
      header_name  = "client-geo"
      header_value = "{client_region}"
      replace      = true
    }
    request_header_to_add {
      # Inform the upstream origin server that the request is from Media CDN.
      header_name  = "x-downstream-cdn"
      header_value = "Media CDN"
    }
    response_header_to_remove {
      header_name = "X-User-ID"
    }
    response_header_to_remove {
      header_name = "X-Other-Internal-Header"
    }
  }
}

這個範例會執行下列操作：

• 使用 {client_region} 變數，在回應中加入自訂 client-geo 標頭。這個變數會傳回與用戶端 IP 位址相關聯的國家/地區。
• 使用靜態字串，將自訂 x-downstream-cdn 標頭新增至要求。
• 移除兩個內部標頭。

如要設定來源專屬的自訂標頭，請參閱「設定來源專屬的主機重寫或標頭修改」。

動態標頭變數

自訂標頭可以包含一或多個動態變數。

屬於快取金鑰政策 (cacheKeyPolicy.includedHeaderNames) 的要求標頭可以包含一或多個自訂變數。含有其他動態變數的要求標頭不得做為快取金鑰。

變數	說明	支援要求標頭	支援快取金鑰中的要求標頭	支援回應標頭
cdn_cache_status	以半形逗號分隔的清單，列出要求/回應路徑中每個快取節點的位置 (最近機場的 IATA 代碼) 和狀態，最右側的值代表最靠近使用者的快取。			✔
client_city	發出要求的城市名稱，例如加州山景城 Mountain View。這個變數沒有有效值的標準清單。城市名稱可包含 US-ASCII 字母、數字、空格及下列字元：!#$%&'*+-.^_`|~.	✔		✔
client_city_lat_long	發出要求的城市經緯度，例如，以 37.386051,-122.083851 表示從山景城發出的要求。	✔		✔
client_region	與用戶端 IP 位址關聯的國家 (或地區)。這是 Unicode CLDR 地區代碼，例如 US 或 FR。 大部分國家的代碼都可以與 ISO-3166-2 代碼直接對應。	✔	✔	✔
client_region_subdivision	與用戶端 IP 位址相關聯的國家/地區分區，例如省或州。這是 Unicode CLDR 分區 ID，例如 USCA 或 CAON。這些 Unicode 代碼是從 ISO-3166-2 標準所定義的分區衍生出來的。	✔	✔	✔
client_rtt_msec	CDN 與 HTTP(S) 用戶端之間的預估往返傳輸時間，以毫秒為單位。這是 CDN 的 TCP 堆疊根據 RFC 2988 測量出的順暢往返時間 (SRTT) 參數。	✔		✔
device_request_type	用戶端使用的裝置類型。有效值包括：DESKTOP、MOBILE、TABLET、SMART_TV、GAME_CONSOLE、WEARABLE 和 UNDETERMINED。	✔	✔
original_request_id	指派給原始要求的專屬 ID，該要求產生了這項回應。只有在快取回應的 request_id 與這個值不同時，才會填入這個欄位。			✔
origin_name	回應的 Proxy 來源 EdgeCacheOrigin 資源。			✔
origin_request_header	反映跨源資源共享 (CORS) 用途的要求中 Origin 標頭的值。			✔
proxy_status	回應路徑中的中繼 HTTP Proxy 清單。此值由 RFC 9209 定義。EdgeCacheService 資源以 Google-Edge-Cache 表示。如果回應是從來源擷取，EdgeCacheOrigin 資源會以 Google-Edge-Cache-Origin 表示。			✔
tls_sni_hostname	伺服器名稱指標 (如 RFC 6066 中的定義)，如果用戶端在 TLS 或 QUIC 交握期間提供。主機名稱會轉換為小寫，並移除任何尾隨點。	✔		✔
tls_version	在 SSL 交握期間，用戶端與負載平衡器之間協商的 TLS 版本。可能的值包括 TLSv1、TLSv1.1、TLSv1.2 和 TLSv1.3。如果用戶端使用 QUIC 而非 TLS 進行連線，則值為 QUIC。	✔		✔
tls_cipher_suite	在 TLS 交握期間協商的加密套件。這個值是由 IANA TLS 加密套件登錄檔定義，例如 TLS_RSA_WITH_AES_128_GCM_SHA256。對於 QUIC 和未加密的用戶端連線，該值為空。	✔		✔
user_agent_family	用戶端使用的瀏覽器系列。有效值包括：APPLE、APPLEWEBKIT、BLACKBERRY、DOCOMO、GECKO、GOOGLE、KHTML、KOREAN、MICROSOFT、MSIE、NOKIA、NETFRONT、OBIGO、OPENWAVE、OPERA、OTHER、POLARIS、TELECA、SEMC、SMIT 和 USER_DEFINED。	✔	✔

自訂變數的注意事項如下：

• 系統會保留現有的要求和回應標頭，但會移除下列標頭：

  • X-User-IP
  • 任何含有 X-Google 或 X-GFE 的標題

• 標頭鍵和值必須符合 RFC 7230 的規定，且不得使用已過時的表單。

• 所有標頭鍵都會轉換成小寫格式 (根據 HTTP/2)。

• 部分標題已合併。如果出現多個相同的標頭鍵 (例如 Via)，負載平衡器會將這些值合併為單一標頭鍵的逗號分隔清單。只有值可表示為以半形逗號分隔清單的標頭會合併。其他標頭 (例如 Set-Cookie) 則不會合併。

• 系統會新增部分標頭，或在標頭中附加值。 媒體 CDN 一律會新增或修改特定標頭，例如 X-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	指定要求的專屬 ID。這個值也會以 jsonPayload.requestId 的形式新增至要求記錄，方便您將用戶端要求/回應與記錄項目建立關聯。		✔
age	傳回快取物件的存留時間 (在快取中存放的秒數)。系統通常會根據物件最初在長尾 (防護) 快取位置快取的時間計算存在時間。 如果回應沒有 age 標頭，系統就不會從快取提供回應。		✔
server	設為 Google-Edge-Cache。		✔
cdn-loop	識別迴圈，例如來源主機與面向使用者的 (邊緣) 主機相同。 根據 RFC 8586，系統會在標頭中附加 google 權杖。權杖無法變更。	✔
forwarded	x-forwarded-for 標頭的結構化版本。 forwarded 標頭定義於 RFC 7239。 當路徑中存在 Proxy 時，您可以使用這些標頭識別連線用戶端的 IP 位址。舉例來說，如果 IP 位址為 192.0.2.60 的用戶端透過 HTTPS 連線至 Media CDN，系統會填入 forwarded 標頭，如下所示： forwarded: [for=192.0.2.60;proto=https] 如果有多個用戶端 Proxy，連線至 Media CDN 的用戶端就是標頭值中附加的最後一個地址。	✔
x-forwarded-for	forwarded 標頭的非結構化事實標準版本。值通常以半形逗號分隔。 這兩個標頭都會在要求中傳送，以支援可能不瞭解 forwarded 標頭的舊版來源。	✔

要求和回應標頭的標頭鍵都會轉換為小寫，因為標頭鍵不區分大小寫。

如要新增其他標頭，包括 PoP 邊緣位置和快取狀態 (例如 hit 和 miss)，請使用動態標頭變數。