設定快取行為

Media CDN 會使用 Google 的全球邊緣快取基礎架構，快取內容並降低來源基礎架構的負載，盡可能提供離使用者較近的內容。

您可以控管每個路由的內容快取方式。這可讓您根據內容類型、用戶端要求屬性和新鮮度需求，調整行為。

可快取性

下列各節將說明 Media CDN 快取的回應內容，以及如何改善快取卸載作業。

預設快取行為

根據預設，下列快取相關設定會套用至每項 Edge Cache 服務：

• CACHE_ALL_STATIC 的預設快取模式：

  • 遵循來源快取指令 (例如 Cache-Control 或 Expires)，最多可設定為存留時間上限。
  • 如果沒有來源快取指示，系統會自動快取靜態媒體類型，並設定 3600 秒的預設 TTL。
  • 快取 HTTP 200、204 和 206 狀態碼 (未啟用負面快取)。

• 不會快取具有 no-store 或 private 快取控制指令的回應，或無法快取的回應。

除非明確設定快取功能，否則系統不會快取非靜態內容或缺少有效快取指令的回應。如要瞭解如何覆寫預設行為，請參閱快取模式說明文件。

預設行為等同於下列 cdnPolicy。未明確設定 cdnPolicy 的路徑會以以下設定運作：

cdnPolicy:
  cacheMode: CACHE_ALL_STATIC
  defaultTtl: 3600s
  cacheKeyPolicy:
    includeProtocol: false
    excludeHost: false
    excludeQueryString: false
  signedRequestMode: DISABLED
  negativeCaching: false

可快取的回應

快取回應是指 Media CDN 可儲存及快速擷取的 HTTP 回應，可加快載入時間。並非所有 HTTP 回應都可以快取。

您可以為每個路徑設定快取模式，藉此覆寫這項行為 (例如，使用 CACHE_ALL_STATIC 快取模式快取常見的媒體類型)，即使來源未在回應中設定快取控制指示語，也能這麼做。

符合「無法快取的回應」中定義條件的要求和回應，會取代快取功能。

下表說明快取特定 HTTP 回應的相關規定。GET 和 HEAD 回應都必須遵守這些規定。

HTTP Age 標頭會根據 Media CDN 首次快取回應的時間設定，通常代表物件在來源遮蔽位置快取後經過的秒數。如果來源產生 Age 回應標頭，請使用 FORCE_CACHE_ALL 快取模式，以免在 Age 超過快取 TTL 時，導致重新驗證。

如要進一步瞭解 Media CDN 如何解讀 HTTP 快取指令，請參閱「快取控制指令」。

來源需求

如要讓 Media CDN 快取超過 1 MiB 的原始回應，來源必須在 HEAD 和 GET 要求的回應標頭中加入下列資訊，除非另有指定：

• Last-Modified 或 ETag HTTP 回應標頭 (驗證器)。
• 有效的 HTTP Date 標頭。
• 有效的 Content-Length 標頭。
• 回應 Range GET 要求的 Content-Range 回應標頭。Content-Range 標頭必須包含有效值，格式為 bytes x-y/z (其中 z 是物件大小)。

預設來源通訊協定為 HTTP/2。如果來源僅支援 HTTP/1.1，您可以明確設定每個來源的通訊協定欄位。

無法快取的回應

下表詳細說明可防止系統快取回應的要求和回應屬性。雖然可快取，但符合「不可快取」條件的回應不會快取。

除了設定的快取模式外，這些規則也會套用。具體情況如下：

• 設定 CACHE_ALL_STATIC 快取模式後，系統只會快取視為靜態內容的回應，或是回應標頭中含有有效快取指令的回應。其他回應則會以原樣轉送。
• FORCE_CACHE_ALL 快取模式會無條件快取所有回應，但須遵守先前所述的不可快取性規定。
• USE_ORIGIN_HEADERS 快取模式除了需要快取狀態碼外，還要求回應在回應標頭中設定有效的快取指令。

注意：

• 未快取的回應不會變更快取控制指令或其他標頭，而是會原封不動地進行 Proxy。
• 回應的 Cache-Control 和 Expires 標頭可摺疊為單一 Cache-Control 欄位。舉例來說，如果回覆內容包含 Cache-Control: public 和 Cache-Control: max-age=100 兩個不同行，系統會將其摺疊為 Cache-Control: public,max-age=100。
• 從計費角度來看，無法快取的回應 (永遠不會快取的回應) 不會計為 Cache Egress。

使用快取模式

快取模式可讓您設定 Media CDN 應在何時遵循來源快取指令、快取靜態媒體類型，以及快取來源的所有回應，不受指令集影響。

快取模式是在路由層級設定，並結合 TTL 覆寫值，讓您可以依主機、路徑、查詢參數和標頭 (任何可比對的要求參數) 設定快取行為。

• 根據預設，Media CDN 會使用 CACHE_ALL_STATIC 快取模式，自動快取常見的靜態媒體類型 1 小時 (3600 秒)，同時為可快取的回應指定來源，以便優先快取。
• 您可以設定路線上的 cdnPolicy.defaultTtl 欄位，藉此增加或減少套用至回應的快取存留時間，而無需設定明確的快取存留時間 (max-age 或 s-maxage 指令)。
• 為避免快取非成功回應的時間超過預期，系統不會根據 Content-Type (MIME 類型) 快取非 2xx (非成功) 狀態碼，也不會套用預設的 TTL。

下表列出可用的快取模式，這些模式會在每個路徑的 cdnPolicy.cacheMode 上設定。

靜態內容 MIME 類型

CACHE_ALL_STATIC 快取模式可讓 Media CDN 根據 Content-Type HTTP 回應標頭中傳回的 MIME 類型，自動快取影片、音訊、圖片和常見網頁素材資源等常見靜態內容。不過，無論媒體類型為何，Media CDN 都會優先處理來源回應中的任何明確 Cache-Control 或 Expires 標頭。

下表列出可透過 CACHE_ALL_STATIC 快取模式自動快取的 MIME 類型。

如果回應沒有 Content-Type 回應標頭，且標頭值與下列值不符，系統就不會自動快取回應。您必須確保回應會設定有效的快取指示語，或是必須使用 FORCE_CACHE_ALL 快取模式，才能無條件快取回應。

注意事項：

• 原始網站的網路伺服器軟體必須為每個回應設定 Content-Type。許多網路伺服器會自動設定 Content-Type 標頭，包括 NGINX、Varnish 和 Apache。
• 當您使用 Google Cloud 控制台或 gcloud CLI 上傳內容時，Cloud Storage 會自動在上傳時設定 Content-Type 標頭。
• Cloud Storage 一律會向 Media CDN 提供 Cache-Control 標頭。如未明確選擇值，則會傳送預設值。因此，除非您明確調整 Cloud Storage 中物件的快取控制中繼資料，或使用 FORCE_CACHE_ALL 模式覆寫 Cloud Storage 傳送的值，否則所有成功的 Cloud Storage 回應都會根據 Cloud Storage 預設值快取。

如果回應可根據其 MIME 類型進行快取，但具有 private 或 no-store 的 Cache-Control 回應指示，或是 Set-Cookie 標頭，則不會快取。

系統預設不會快取其他媒體類型，例如 HTML (text/html) 和 JSON (application/json)。這類回應通常是動態的 (依使用者而異)，也不太適合 Media CDN 的架構。建議您使用 Cloud CDN 來提供網路資產，以及快取 API 回應。

設定快取存留時間

存留時間 (TTL) 覆寫值可讓您為快取內容設定預設 TTL 值，並覆寫來源在 max-age 和 s-maxage 快取控制指示 (或 Expires 標頭) 中設定的 TTL 值。

無論是透過覆寫或使用快取指令設定，存留時間都是樂觀的。不常存取或不受歡迎的內容，可能會在達到 TTL 前從快取中移除。

下表列出三種 TTL 設定。

將任何 TTL 值設為零 (0 秒) 會導致每項要求在傳送回應前，都會向原始來源重新驗證，如果設定過於廣泛，也會增加對原始來源的負載。

將快取模式設為 Use Origin Headers 時，Media CDN 會依賴來源驅動行為，因此無法設定 TTL 設定。

注意：

• 存留時間上限的值一律必須大於 (或等於) 預設存留時間的值。
• 用戶端 TTL 的值一律必須小於 (或等於) 最大 TTL 的值。
• 當 Media CDN 覆寫來源 TTL 值時，傳送至用戶端的 Cache-Control 標頭也會反映該值。
• 如果原始來源設定 Expires 標頭，而 Media CDN 覆寫有效的 TTL (根據時間戳記)，則會在傳送至用戶端的下游回應中，將 Expires 標頭替換為 Cache-Control 標頭。

負面快取

負向快取會定義 Media CDN 如何快取非成功的 HTTP 狀態碼 (2xx 以外的狀態碼)。

這樣一來，您就能快取錯誤回應，例如重新導向 (HTTP 301 和 308) 和找不到 (HTTP 404) 回應，讓使用者更容易取得這些回應。如果回應不太可能變更且可快取，您還能進一步減少來源負載。

根據預設，系統會停用負向快取功能。下表列出啟用負向快取功能且未使用 negativeCachingPolicy 時，每個狀態碼的預設值。

預設的負面快取代碼組合會與 HTTP RFC 9110 中所述的啟發式快取狀態碼相符，但有以下例外狀況：

• 為避免快取中毒，系統不支援快取 HTTP 414 狀態碼 (URI 過長)。
• 如 HTTP RFC 7725 所述，HTTP 451 狀態碼 (因法律規定而無法使用) 可用於快取。

如果您需要設定個別狀態碼的 TTL，並覆寫預設行為，可以設定 cdnPolicy.negativeCachingPolicy。這麼做可讓您為 Media CDN 允許的任何狀態碼設定 TTL：300、301、302、307、308、400、403、404、405、410、451、500、501、502、503 和 504。

舉例來說，如要為 HTTP 404 (找不到) 回應設定短暫的 5 秒 TTL，以及為 HTTP 405 (方法不允許) 回應設定 10 秒 TTL，請在每個適用的路徑上使用以下 YAML 定義：

cdnPolicy:
  negativeCaching: true
  negativeCachingPolicy:
    "404": 5s
    "405": 10s
  # other status codes to apply TTLs for

為避免快取中毒，我們不建議為狀態碼 400 (錯誤要求) 或 403 (禁止) 啟用快取功能。請確認原始伺服器只檢查快取鍵中包含的請求元件，並據此傳回其中一個程式碼。例如，當原始伺服器在沒有正確的 Authorization 標頭的情況下，傳回 403 錯誤回應時，就可能發生快取中毒。在這種情況下，快取 403 錯誤回應會導致 Media CDN 為所有後續要求提供 403 錯誤回應，直到 TTL 到期為止，即使要求含有正確的 Authorization 標頭也一樣。

如要停用負面快取，請按照下列步驟操作：

• 如要停用預設的負面快取行為，請在路線上設定 cdnPolicy.negativeCaching: false。請注意，含有有效快取指令和可快取狀態碼的來源回應仍會快取。
• 如要避免針對特定狀態碼使用負面快取，但仍遵循來源快取指示，請在 negativeCachingPolicy 定義中省略狀態碼 (cdnPolicy.negativeCachingPolicy[].code)。
• 如要明確略過特定狀態碼的原始快取指示，請將該狀態碼的 cdnPolicy.negativeCachingPolicy[].ttl 設為 0 (零)。

注意：

• 如果路徑上已啟用 negativeCaching，且回應定義了有效的快取指令，回應中的快取指令會優先採用。
• 如果您設定明確的 negativeCachingPolicy，且已為指定的狀態碼定義 TTL，系統一律會使用政策中定義的 TTL。
• negativeCachingPolicy 設定的 TTL 最大值為 1800 秒 (30 分鐘)，但系統會遵循較高 TTL 的來源快取指令。
• 如果「快取模式」設為 FORCE_CACHE_ALL，系統會一律忽略來源指示。

快取控制指令

這裡定義了 Media CDN 對 Cache-Control 指令的行為。

如果指令不適用於要求或回應 (例如 only-if-cached，這是僅限用戶端的指令)，則該欄會標示「不適用」。

在可行情況下，Media CDN 會符合 RFC 標準 (HTTP RFC 7234)，但會優先最佳化快取卸載作業，並盡可能減少用戶端對命中率和整體來源載入作業的影響。

如採用 HTTP/1.1 Expires 標頭的回應：

• Expires 標頭的值必須是有效的 HTTP 日期，如RFC 7231 所定義
• 過去的日期值、無效日期或 0 值表示內容已過期，需要重新驗證。
• 如果回應中包含 Cache-Control 標頭，Media CDN 會忽略 Expires 標頭。

如果回應中包含 HTTP/1.0 Pragma 標頭，系統會略過該標頭，並將其原封不動地傳遞給用戶端。

快取金鑰

您可以考量如何唯一識別要求，並移除在要求之間可能經常變更的元件，藉此減少 Media CDN 需要聯絡原始來源的次數。這組要求元件通常稱為「快取索引鍵」。

以下各節將說明如何設定快取索引鍵。

快取金鑰元件

快取金鑰是快取物件參照的一組要求參數 (例如主機、路徑和查詢參數)。

根據預設，Edge Cache 服務的快取鍵會包含要求主機、路徑和要求的查詢參數，且範圍限定為特定 EdgeCacheService。

注意事項：

• 快取鍵不會附加至已設定的來源，因此您可以更新來源設定 (或完全取代來源)，而不會有「清除」快取的風險 (例如在供應器之間遷移來源儲存空間時)。
• 快取鍵會受限於 EdgeCacheService。不同的 EdgeCacheServices 會有不同的快取命名空間，因此即使主機、路徑或其他快取鍵元件相符，您也不會在正式上線、測試前環境和其他測試環境之間不小心快取物件。刪除 EdgeCacheService 後，該服務的所有快取物件都會失效。
• 快取鍵的範圍並未限定為個別路徑。多個路徑可能會參照相同的快取鍵，特別是如果這些路徑與未包含在快取鍵中的元件相符，例如要求標頭或排除的參數。如果您希望多個路徑共用相同快取，但要傳回不同的回應標頭或 CORS 設定，這項功能就相當實用。
• 快取鍵不會包含網址重寫設定，舉例來說，快取鍵是根據面向使用者的請求而非最終「重寫」請求。
• 在路線上設定已簽署的請求時，快取金鑰中不會包含已簽署的屬性。系統會將要求視為 (已簽署) 查詢參數或路徑元件，這些元件以 edge-cache-token 開頭，並以下一個路徑分隔符號 ("/") 結尾，因此不屬於網址的一部分。

包含或排除查詢參數

您可以在特定路徑上，將參數名稱新增至 includedQueryParameters 或 excludedQueryParameters 快取金鑰設定，藉此在快取金鑰中加入或排除特定查詢參數。

舉例來說，如要將 contentID 和 country 查詢參數納入快取金鑰，並忽略其他所有參數：

cdnPolicy:
  cacheMode: CACHE_ALL_STATIC
  defaultTtl: 86400s
  cacheKeyPolicy:
    includedQueryParameters: ["contentID", "country"]

請務必加入可用於識別內容的查詢參數，並排除其他參數。舉例來說，請排除分析查詢參數、播放工作階段 ID 或其他僅限於用戶端的參數。加入不必要的查詢參數可能會降低快取命中率。

或者，您可以選擇從快取金鑰中排除哪些參數，而非指定要納入快取金鑰的參數。舉例來說，如要從快取鍵中排除特定用戶端的播放 ID 和時間戳記資訊，請設定下列項目：

cdnPolicy:
  cacheMode: CACHE_ALL_STATIC
  defaultTtl: 86400s
  cacheKeyPolicy:
    excludedQueryParameters: ["playback-id", "timestamp"]

針對特定路徑，您可以指定 includedQueryParameters 或 excludedQueryParameters 其中之一。

如果查詢參數從未用於在各項要求中唯一識別內容，您可以從路徑的快取金鑰中移除所有查詢參數。方法是將 excludeQueryString 設為 true，如下所示：

cdnPolicy:
  cacheMode: CACHE_ALL_STATIC
  defaultTtl: 3600s
  cacheKeyPolicy:
    excludeQueryString: true

如果在路線上啟用已簽署的要求，則查詢字串中不會包含用於簽署的查詢參數，且如果包含這些參數，系統會忽略這些參數。在快取鍵中加入已簽署的參數，可有效地讓每個使用者要求都獨一無二，並要求每項要求都從來源提供。

查詢參數排序

系統會預設排序查詢參數 (查詢字串)，以提升快取命中率，因為用戶端可能會重新排序，或以其他方式要求相同的快取物件，但查詢參數的順序不同。

舉例來說，在產生快取金鑰之前，查詢參數 b=world&a=hello&z=zulu&p=paris 和 p=paris&a=hello&z=zulu&b=world 會排序為 a=hello&b=world&p=paris&z=zulu。這可讓兩個要求對應至相同的快取物件，避免對來源提出不必要的要求 (以及來源的回應)。

如果查詢參數鍵有多個例項，且每個例項的值皆不同，系統會依據完整值排序參數 (例如，a=hello 會排在 a=world 之前)。無法停用排序功能。

包含標頭

標頭名稱不區分大小寫，並會由 Media CDN 轉換為小寫。

下列標頭不得納入快取索引鍵：

• 任何以 access-control- 開頭的標頭
• 任何以 sec-fetch- 開頭的標頭
• accept-encoding
• accept
• authorization
• connection
• content-md5
• content-type
• cookie
• date
• forwarded
• from
• host
• if-match
• if-modified-since
• if-none-match
• origin
• proxy-authorization
• range
• referer
• referrer
• user-agent
• want-digest
• x-csrf-token
• x-csrftoken
• x-forwarded-for

如要在快取金鑰中納入 HTTP 方法，請使用特殊標頭名稱 :method。

納入 Cookie

請注意，Cookie 名稱有大小寫之分。

開頭為 edge-cache- 的 Cookie (不論大小寫) 皆不得用於快取金鑰。

重新驗證、撤銷和到期日

內容傳遞聯播網 (包括 Media CDN) 會盡可能快取最受歡迎的內容，並將內容儲存在最靠近使用者的位置。

Media CDN 的大量儲存空間和來源防護機制，可避免您需要移除不受歡迎的內容。每天存取次數不多的內容可能最終會遭到移除。

• 快取的回應達到設定的存留時間後，可能不會立即遭到淘汰。針對熱門內容，Media CDN 會向原始來源發出 HEAD 要求，確認標頭未變更，藉此重新驗證快取的回應是否為最新版本。在某些情況下，Media CDN 會改為傳送要求給來源，並附上 If-None-Match 和 If-Modified-Since 這兩個要求標頭或其中一個。在這種情況下，如果快取具有該回應的「最新」副本，則正確設定的來源應傳回 HTTP 304 (Not Modified) 回應，但不含主體位元組。
• 設定 max-age 或 s-maxage 快取指示詞的回應，或是使用TTL 覆寫值指定高 TTL 值 (例如 30 天)，可能不會儲存在快取中，系統無法保證物件會在整個期間內儲存在快取中，尤其是如果物件很少被存取的話。

如果您發現遭到淘汰的機率很高，請確認您已設定快取索引鍵，以便排除無法明確識別回應的參數。

其他注意事項

以下考量事項也適用於快取。

Vary 標頭

Vary 標頭代表回應會根據用戶端的要求標頭而改變。如果回應中含有 Vary 標頭，Media CDN 不會快取該標頭，除非標頭指定的標頭已設為快取鍵設定，或指定下列其中一個值：

• Accept：用於指出用戶端接受的媒體類型
• Accept-Encoding：用於指出用戶端接受的壓縮類型
• Available-Dictionary：用於提供可用字典的雜湊，以便壓縮
• Origin/X-Origin：通常用於跨來源資源共享
• X-Goog-Allowed-Resources:支援 Google Cloud 機構限制
• Sec-Fetch-Dest/Sec-Fetch-Mode/Sec-Fetch-Site:用於擷取中繼資料要求標頭

Media CDN 會使用標頭的值做為快取金鑰的一部分，在回應中快取帶有 Vary 標頭的回應。如果回應中的 Vary 標頭含有多個值，系統會依字典順序排序，確保快取鍵是確定性的。

Media CDN 會為特定快取鍵快取最多 100 個變化版本，並隨機從快取中移除超過此限制的變化版本。明確撤銷特定網址或快取代碼的快取時，所有變化版本都會失效。

略過快取

您可以在路線上設定 BYPASS_CACHE 快取模式，有意略過相符要求的快取。如果您需要略過快取，以便處理非必要流量的一小部分，或偵錯來源連線，這項做法就很實用。

如果您需要提供動態回應 (例如 API 後端)，建議您設定外部應用程式負載平衡器。

建議您一般將這項功能的使用範圍限制在偵錯情境，以免不小心載入來源。略過快取時輸出的流量，會以網際網路輸出費率計價。

快取撤銷

請參閱快取撤銷。

位元組範圍要求

Media CDN 支援 RFC 7233 中定義的單部分 HTTP 範圍要求。

此外，Media CDN 也會使用範圍要求，從來源擷取較大的回應。這可讓 Media CDN 個別快取區塊，且不需要一次擷取整個物件來快取。

• 大於 1 MiB 的物件會以位元組範圍要求 (「區塊」) 擷取，每個區塊最多可達 2 MiB。
• 可擷取最多 1 MiB 的回應，但不支援原點的位元組範圍。
• 如果來源不支援位元組範圍，系統就不會提供比這個值大的回應。

原始來源是否支援位元組範圍要求，取決於下列因素：

• HTTP 狀態碼為 200 (OK) 或 206 (部分內容)。
• 有效的 Content-Length 或 Content-Range 回應標頭。
• 回應驗證工具 (ETag 或 Last-Modified)。

每個「區塊」(位元組範圍) 的個別來源填充要求會記錄為個別記錄項目，並與其父項用戶端要求建立關聯。您可以透過比對 jsonPayload.cacheKeyFingerprint 上的請求，將這些請求分組。

如要進一步瞭解記錄內容，請參閱 Cloud Logging 說明文件。

開放式範圍要求

Media CDN 支援「開放式」Range 要求 (例如含有 Range: bytes=0- 的要求)，可讓要求持續對應至來源，直到來源關閉回應 (例如來源將所有位元組寫入網路) 或逾時為止。

開放式位元組範圍通常用於要求 Apple 低延遲 HLS 區段的用戶端：由於每個 CMAF 區塊都會寫入網路，CDN 可以將該區塊快取並提交給用戶端。

在其他情況下 (例如不需要與 DASH 互通)，媒體播放清單會向播放器指出哪些位元組代表每個區塊：

  #EXTINF:4.08,
  fs270.mp4
  #EXT-X-PART:DURATION=1.02,URI="fs271.mp4",BYTERANGE=20000@0
  #EXT-X-PART:DURATION=1.02,URI="fs271.mp4",BYTERANGE=23000@20000
  #EXT-X-PART:DURATION=1.02,URI="fs271.mp4",BYTERANGE=18000@43000
  #EXT-X-PRELOAD-HINT:TYPE=PART,URI="fs271.mp4",BYTERANGE-START=61000

您可以使用 EdgeCacheOrigin.timeouts.readTimeout 設定值，設定 Media CDN 在讀取之間等待的時間長度。通常應將此值設為目標時間長度的倍數 (例如 2 倍)。

後續步驟

• 查看進階轉送。
• 瞭解如何連線至不同的來源。
• 為服務設定 TLS (SSL) 憑證。
• 設定已簽署的要求，以驗證內容存取權。
• 如要進一步瞭解如何使用 Terraform 設定 EdgeCacheService 資源，請參閱 Terraform Registry 說明文件。