設定快取行為

Media CDN 會使用 Google 的全球邊緣快取基礎架構來快取內容，並減少來源基礎架構的負載，盡可能提供和使用者息息相關的內容。

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

可快取性

下列各節說明 Media CDN 會快取哪些回應，以及如何提升快取卸載量。

預設快取行為

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

• CACHE_ALL_STATIC 的預設快取模式：

  • 遵守來源快取指令，例如 Cache-Control 或 Expires，最高可達可設定的存留時間上限。
  • 如果沒有原始快取指令，系統會自動快取靜態媒體類型，預設 TTL 為 3600 秒。
  • 快取 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 超過快取存留時間時重新驗證。

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

來源規定

如要允許 Media CDN 快取大於 1 MiB 的原始伺服器回應，原始伺服器必須在 HEAD 和 GET 要求的相關回應標頭中加入下列項目 (除非另有規定)：

• Last-Modified 或 ETag HTTP 回應標頭 (驗證器)。
• 有效的 HTTP Date 標頭。
• 有效的 Content-Length 標頭。
• Content-Range 回應標頭，用來回應 Range GET 要求。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 指令)。
• 為避免系統快取非成功回應的時間超出預期，非 2xx (非成功) 狀態碼不會根據 Content-Type (MIME 類型) 快取，也不會套用預設存留時間。

下表列出可用的快取模式，這些模式會在每個路徑的 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 類型可供快取，但具有 Cache-Control 回應指令 private、no-store 或 Set-Cookie 標頭，則不會快取。

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

設定快取存留時間

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

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

下表顯示三種 TTL 設定。

如果將任何存留時間值設為零 (0 秒)，系統會在提供回應前，重新驗證每個要求與來源的關係，如果設定範圍過廣，會增加來源的負載。

如果快取模式設為 Use Origin Headers，就無法設定 TTL，因為 Media CDN 會依據來源來決定行為。

注意：

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

負面快取

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

這樣一來，您就能在更靠近使用者的位置快取錯誤回應，例如重新導向 (HTTP 301 和 308) 和找不到 (HTTP 404) 回應，如果回應不太可能變更且可以快取，還能更廣泛地減少原始負載。

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

預設的負向快取代碼集與 HTTP RFC 9110 中描述的啟發式可快取狀態碼相符，但有以下例外狀況：

• 為避免快取中毒，快取功能不支援 HTTP 狀態碼 414 (URI Too Long)。
• 如HTTP RFC 7725 所述，系統支援 HTTP 狀態碼 451 (因法律要求而遭拒) 的快取。

如要設定自己的每個狀態碼存留時間，並覆寫預設行為，可以設定 cdnPolicy.negativeCachingPolicy。您可以為 Media CDN 允許的任何狀態碼設定 TTL：300、301、302、307、308、400、403、404、405、410、451、500、501、502、503 和 504。

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

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

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

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

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

注意：

• 在路徑上啟用 negativeCaching 時，如果回應定義了有效快取指令，回應中的快取指令會優先採用。
• 如果您設定明確的 negativeCachingPolicy，且已為指定狀態碼定義存留時間，系統一律會使用政策中定義的存留時間。
• 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 聯絡來源的次數，請考量哪些項目可做為要求的專屬 ID，並移除要求之間可能經常變更的元件。這組要求元件通常稱為「快取金鑰」。

下列各節說明如何設定快取金鑰。

快取金鑰元件

快取鍵是一組要求參數 (例如主機、路徑和查詢參數)，快取物件會透過這些參數參照。

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

注意事項：

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

納入或排除查詢參數

如要將特定查詢參數納入或排除在快取金鑰之外，請在特定路徑的 includedQueryParameters 或 excludedQueryParameters 快取金鑰設定中加入參數名稱。

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

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

請務必加入可明確識別內容的查詢參數，並排除無法識別內容的查詢參數。舉例來說，您可以排除 Analytics 查詢參數、播放工作階段 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 要求，確認標頭未變更，藉此重新驗證快取回應是否為最新版本。
• 如果回應設定 max-age 或 s-maxage 快取指令，或使用存留時間覆寫指定高存留時間值 (例如 30 天)，則可能不會在快取中儲存完整存留時間。無法保證物件會儲存在快取中一段時間，尤其是存取頻率不高的物件。

如果逐出率偏高，請確認您已設定快取鍵，排除無法明確識別回應的參數。

其他注意事項

快取也可能適用下列注意事項。

Vary 標頭

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

• Accept：用於指出用戶端接受的媒體類型
• Accept-Encoding：用於指出用戶端接受的壓縮類型
• Available-Dictionary：用於提供可用字典的雜湊，以進行壓縮
• 來源/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 9110 中定義的 HTTP 範圍要求。

此外，Media CDN 會使用範圍要求，從來源擷取較大的回應。這樣一來，Media CDN 就能快取個別位元組範圍，不必一次擷取整個物件進行快取。

• 系統會以位元組範圍要求擷取大於 1 MiB 的物件，每個要求最多 2 MiB。
• 擷取的回應大小上限為 1 MiB，且來源不支援位元組範圍。
• 如果來源不支援位元組範圍，系統就不會提供大於 1 MiB 的回應。

原始伺服器是否支援位元組範圍要求取決於下列因素：

• HTTP 狀態碼為 200 (OK) 或 206 (Partial Content)。
• 有效的 Content-Length 或 Content-Range 回應標頭。
• 回應驗證器 (ETag 或 Last-Modified)。

系統會將每個位元組範圍的個別來源填滿要求記錄為離散記錄項目，並與其上層用戶端要求建立關聯。您可以比對每項要求的 jsonPayload.cacheKeyFingerprint 值，將這些要求分組。

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

多部分範圍要求

媒體 CDN 支援多部分範圍要求，讓使用者在單一 HTTP 要求中，要求檔案的多個不連續片段，例如 Range: bytes=0-499, 1000-1499。

為盡量提升用戶端效能並卸載原始伺服器，Media CDN 可以從快取提供所要求的個別位元組範圍，並將這些範圍整合成單一回應，連同 HTTP 206 Partial Response 狀態碼傳送給用戶端，且 Content-Type 設為 multipart/byteranges。

如果是可快取的回應，當用戶端要求多部分範圍時，Media CDN 會將要求轉換為一組單一部分範圍要求，藉此最佳化程序。每個要求的大小為 2 MB，可涵蓋用戶端要求的所有位元組範圍部分。然後，Media CDN 會使用這些回應，在邊緣產生單一的多部分回應。這種做法可有效運用快取、減少多餘的原始擷取作業，並支援大量使用案例，例如應用程式商店下載和 OS 更新。

對於無法快取的內容，Media CDN 會直接將要求轉送至來源。

開放式範圍要求

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

要求 Apple Low-Latency 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 登錄檔說明文件。