定義自訂標頭

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

您可以透過自訂標頭執行下列操作：

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

您也可以使用標頭將要求轉送至不同的來源。如果您需要設定跨源資源共享 (CORS) 標頭，請為每個路徑設定 CORS 政策。

設定自訂標頭

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

請在 CDN 處理路徑的早期 (在快取決策之前) 設定個別路徑的自訂要求標頭。舉例來說，如果您將 cache-control 標頭設為個別路徑自訂標頭，就會影響 CDN 中的快取行為。

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

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

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"

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) 的請求標頭可以包含一或多個自訂變數。包含其他動態變數的要求標頭，不得用於快取金鑰。

以下是自訂變數的注意事項：

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

  • X-User-IP
  • 任何包含 X-Google 或 X-GFE 的標頭

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

• 所有標頭鍵都會轉換為小寫 (依據 HTTP/2)。

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

• 新增部分標頭，或在標頭中附加值。Media CDN 一律會新增或修改特定標頭，例如 Via 和 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 會分別在原始要求和用戶端回應中加入下列要求和回應標頭。

請注意，標頭鍵不區分大小寫，因此請求和回應標頭的標頭鍵都會轉為小寫。

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