設定快取行為

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

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

可快取性

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

預設快取行為

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

• CACHE_ALL_STATIC 的預設快取模式：

  • 遵守來源快取指令，例如 Cache-Control 或 Expires，但不得超過可設定的存留時間上限。
  • 如果沒有來源快取指令，系統會自動快取靜態媒體類型，預設存留時間為 3600 秒。
  • 快取 HTTP 200、204 和 206 狀態碼 (未啟用 negative caching)。

• 不會快取含有 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 屬性	需求條件
狀態碼	回應狀態碼必須是 200、203、204、206、300、301、302、307、308、400、403、404、405、410、451、500、501、502、503 或 504。
HTTP 方法	GET 和 HEAD
要求標頭	系統會忽略大多數快取要求指令，詳情請參閱「快取控制指令」。
回應標頭	含有有效的 HTTP 快取指令，例如 Cache-Control: max-age=3600, public。 具有可快取該內容的快取模式，或具有包含未來日期的 Expires 標頭。
回應大小	最多 100 GiB。

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

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

來源規定

如要允許 Media CDN 快取大於 1 MiB 的來源回應，來源必須在 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，您可以為每個來源明確設定通訊協定欄位。

注意： 如果回應較小 (小於 1 MiB)，且缺少先前列出的完整標頭集，則可能會比大型回應更快從快取中清除。

不可快取的回應

下表詳細說明可防止回應遭到快取的請求和回應屬性。如果回應可快取，但符合「不可快取」條件，系統就不會快取。

HTTP 屬性	條件
狀態碼	狀態碼並非定義為可快取，例如 HTTP 401、HTTP 412 或 HTTP 505。 這些狀態碼通常代表用戶端問題，而非來源狀態。快取這些回應可能會導致「快取中毒」情境，也就是使用者觸發的「錯誤」回應會快取給所有使用者。
要求標頭	如果要求含有 Authorization 要求標頭，回應必須包含 public Cache-Control 指令，才能快取。 要求中的 no-store 指令會導致回應無法快取。詳情請參閱「快取控制指令」。
回應標頭	含有 Set-Cookie 標頭。 具有 Vary 標頭，但不是 Accept、Accept-Encoding、Access-Control-Request-Headers、Access-Control-Request-Method、Origin、Sec-Fetch-Dest、Sec-Fetch-Mode、Sec-Fetch-Site、X-Goog-Allowed-Resources 或 X-Origin。 在 CACHE_ALL_STATIC 或 USE_ORIGIN_HEADERS 模式下，具有 no-store 或 private 快取控制指令。
回應大小	大於 100 GiB。

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

• 設定 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 何時應遵守來源快取指令、快取靜態媒體類型，以及快取來源的所有回應 (無論設定的指令為何)。

快取模式是在路徑層級設定，並搭配存留時間覆寫，讓您依主機、路徑、查詢參數和標頭 (任何可比對的要求參數) 設定快取行為。

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

注意： 如要設定如何快取重新導向 (3xx) 等非 2xx 回應，請參閱負面快取。

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

快取模式	行為
USE_ORIGIN_HEADERS	來源回應須設定有效快取指令和有效快取標頭。如需完整的規定清單，請參閱「可快取的回應」。
CACHE_ALL_STATIC	自動快取含有靜態內容的成功回應，除非這些回應有 no-store 或 private 指令。系統會優先處理來源的有效快取指令。 靜態內容包括影片、音訊、圖片，以及 Content-Type回應標頭中 MIME 類型定義的常見網頁素材資源。
FORCE_CACHE_ALL	無條件快取成功的回應，覆寫來源所設定的任何快取指令。 請務必不要在設定這個模式後，提供個別使用者 (可識別使用者身分) 的私人內容，例如動態 HTML 或 API 回應。
BYPASS_CACHE	即使有與快取鍵相符的快取物件，只要要求與設定此快取模式的路由相符，就會略過快取。 建議只將這項功能用於偵錯，因為 Media CDN 的設計是全球規模的快取基礎架構，而非一般用途的 Proxy。

靜態內容 MIME 類型

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

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

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

類別	MIME 類型
網路資產	text/css text/ecmascript text/javascript application/javascript
字型	任何符合 font/* 的 Content-Type
圖片	任何符合 image/* 的 Content-Type
影片	任何符合 video/* 的 Content-Type
音訊	任何符合 audio/* 的 Content-Type
格式化文件類型	application/pdf and application/postscript

注意事項：

• 來源的網路伺服器軟體必須為每個回應設定 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) 覆寫功能，為快取內容設定預設存留時間值，並覆寫來源設定的 max-age 和 s-maxage 快取控制指令 (或 Expires 標頭) 中設定的存留時間值。

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

下表列出三種存留時間設定。

設定	預設	下限	上限	說明	適用的快取模式
Default TTL	1 小時 (3600 秒)	0 秒	1 年 (31,536,000 秒)	來源未指定 max-age 或 s-maxage 標頭時要設定的存留時間。 如果來源指定 s-maxage 標頭，系統會使用該標頭，而非此處的預設存留時間值。 使用 FORCE_CACHE_ALL 無條件快取所有回應時，系統會使用預設存留時間設定快取存留時間。系統會忽略其他值和指令。	CACHE_ALL_STATIC FORCE_CACHE_ALL
Max TTL	1 天 (86400 秒)	0 秒	1 年 (31,536,000 秒)	可快取的回應允許的存留時間上限。如果值大於此值，系統會將值上限設為 maxTtl。	CACHE_ALL_STATIC
Client TTL	預設為未設定。	0 秒	1 天 (86400 秒)	如果可快取的回應需要與其他存留時間值不同，則允許在下游 (面向用戶端) 回應中使用的存留時間上限。	CACHE_ALL_STATIC FORCE_CACHE_ALL

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

快取模式設為 Use Origin Headers 時，無法設定存留時間，因為 Media CDN 會依據來源來決定行為。

注意：

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

Negative caching

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

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

注意： 如要設定成功回應 (2xx 狀態碼) 的快取方式，請參閱快取模式。

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

狀態碼	Reason-phrase	存留時間
HTTP 300	多個選擇	10 分鐘
HTTP 301 和 HTTP 308	永久重新導向	10 分鐘
HTTP 404	找不到	120 秒
HTTP 405	找不到方法	60 秒
HTTP 410	消失	120 秒
HTTP 451	基於法律原因而無法提供	120 秒
HTTP 501	未執行	60 秒

預設的 negative caching 代碼集符合 HTTP RFC 9110 中描述的啟發式可快取狀態碼，但有下列例外狀況：

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

如要設定自己的狀態碼存留時間，並覆寫預設行為，可以設定 cdnPolicy.negativeCachingPolicy。您可以為 Media CDN 允許的任何狀態碼設定存留時間，包括：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

重要事項： 設定 negativeCachingPolicy 時，請指定要快取的所有狀態碼 (及其存留時間)。如果存在政策，系統就不會套用預設 TTL (如本頁所述)。

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

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

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

注意：

• 在路徑上啟用 negativeCaching 後，如果回應定義有效快取指令，回應中的快取指令會優先採用。
• 如果您設定明確的 negativeCachingPolicy，且為指定狀態碼定義了存留時間，系統一律會使用政策中定義的存留時間。
• negativeCachingPolicy 設定的存留時間上限為 1800 秒 (30 分鐘)，但系統會遵守存留時間較長的來源快取指令。
• 如果快取模式設為 FORCE_CACHE_ALL，系統一律會忽略來源指令。

快取控制指令

本文說明 Media CDN 對於 Cache-Control 指令的行為。

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

指令	要求	回應
no-cache	系統會忽略 no-cache 要求指令，避免用戶端可能啟動或強制重新驗證來源。	系統會快取含有 no-cache 的回應，但必須先向來源驗證，才能提供回應。 您可以透過 FORCE_CACHE_ALL 快取模式，為每個路徑覆寫這項指令。
no-store	系統不會快取含有 no-store 的要求回應。	系統不會快取含有 no-store 的回應。 您可以透過 FORCE_CACHE_ALL 快取模式，為每個路徑覆寫這項指令。
public	不適用	如果回應整體可快取且回應也具有 max-age 或 s-maxage 指令，系統就會快取含有 public 指令的回應。 使用 CACHE_ALL_STATIC 快取或 FORCE_CACHE_ALL 模式時，則不需要這項設定。
private	不適用	即使回應在其他情況下可快取，Media CDN 也不會快取含有 private 指令的回應。用戶端 (例如瀏覽器) 可能仍會快取結果。 您可以透過 FORCE_CACHE_ALL 快取模式，為每個路徑覆寫這項指令。 使用 no-store 可避免快取所有回應。
max-age=SECONDS	系統會忽略 max-age 要求指令，並傳回已快取的回應，如同要求中不具有此標頭一樣。	含有 max-age 指令的回應會快取至已定義的 SECONDS。
s-maxage=SECONDS	不適用	含有 s-maxage 指令的回應會快取至已定義的 SECONDS。 如果 max-age 和 s-maxage 同時存在，伺服器會使用 s-maxage。 請注意，s-max-age (兩個連字號) 不適用於快取。
min-fresh=SECONDS	系統會忽略 min-fresh 要求指令，並傳回已快取的回應，如同要求中不具有此標頭一樣。	不適用
max-stale=SECONDS	系統會忽略 max-stale 要求指令。 並傳回已快取的回應，如同要求中不具有此標頭一樣。	不適用
stale-while-revalidate=SECONDS	不適用	沒有作用。這項指令會在回應中傳遞給用戶端。
stale-if-error=SECONDS	系統會忽略 stale-if-error 要求指令，並傳回已快取的回應，如同要求中不具有此標頭一樣。	沒有作用。這項指令會在回應中傳遞給用戶端。
must-revalidate	不適用	回應到期後，系統會使用原始伺服器重新驗證含有 must-revalidate 的回應。
proxy-revalidate	不適用	回應到期後，系統會使用來源伺服器重新驗證含有 proxy-revalidate 的回應。
immutable	不適用	沒有作用。這項指令會在回應中傳遞給用戶端。
no-transform	不適用	Media CDN 不會套用任何轉換。
only-if-cached	系統會忽略 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。

警告： 請勿在網址路徑或查詢參數加入機密、敏感或個人識別資訊。依據《服務專屬條款》第 12 節 (資源欄位)，網址 (包括主機、路徑和查詢參數) 屬於無法用來識別身分的服務資料。為維護隱私權與安全性，網址元件應使用符合下列條件的 ID：由系統產生、不會透露實際資訊，而且並非取自使用者輸入內容。

元件	預設包含這項服務嗎？	詳細資料
通訊協定	否	透過 HTTP 和 HTTPS 傳送的要求會參照相同的快取物件。 如要針對 http: 和 https: 要求傳回不同的回應，請在相關聯的路由上將 cacheKeyPolicy.includeProtocol 設為 true。
主機	是	不同主機不會參照相同的快取物件。 如果您有多個主機名稱指向同一個 EdgeCacheService，且這些主機名稱提供相同的內容，請將 cdnPolicy.excludeHost 設為 true。
路徑	是	一律會納入快取鍵，且無法移除。路徑是快取中物件的最小表示法。
查詢參數	是	如果查詢參數無法區分不同回應，請將 cacheKeyPolicy.excludeQueryString 設為 true。 如果快取金鑰只應包含部分查詢參數，請視需要設定 includedQueryParameters 或 excludedQueryParameters。
標題	否	使用 cacheKeyPolicy.includedHeaderNames 設定要納入快取金鑰的標頭名稱。 指定多個標頭，這些標頭合併後會產生大量值 (例如，合併後的標頭值可識別單一使用者)，會大幅降低快取命中率，並可能導致淘汰率提高和效能降低。
Cookie	否	設定 cacheKeyPolicy.includedCookieNames，其中包含要納入快取金鑰的 Cookie 名稱。 指定多個 Cookie，這些 Cookie 合起來的值範圍很大 (例如，合併的 Cookie 值可識別單一使用者)，會大幅降低快取命中率，並可能導致淘汰率提高和效能降低。

注意事項：

• 快取鍵不會附加至已設定的來源，因此您可以更新來源設定 (或完全取代來源)，不必擔心「清除」快取 (例如在供應商之間遷移來源儲存空間時)。
• 快取金鑰僅限用於 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-Encoding：用於指出用戶端接受的壓縮類型
• Access-Control-Request-Headers/Access-Control-Request-Method:用於支援 CORS 預檢回覆
• 來源/X 來源：通常用於跨源資源共享
• 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- 的要求)，這類要求會讓要求對來源保持開啟狀態，直到來源關閉回應 (例如來源將所有位元組寫入線路) 或逾時為止。

注意： 您的原始基礎架構也必須支援串流物件，才能回應開放式 Range 要求，並在物件完全寫入前傳送。部分來源 (例如 Cloud Storage 和 Amazon S3) 支援無限制範圍要求，但只會在物件完全寫入後提供服務。

開放式位元組範圍通常用於要求 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 倍)。

直播擴充功能

如果客戶使用 Media CDN 提供直播影片，可以啟用直播擴展功能 (選用功能)，進一步最佳化工作流程，以低延遲提供內容。

直播擴展功能會改變邊緣使用的快取層，有助於確保改善體驗品質 (QoE) 指標，這對直播活動至關重要。

擴充直播時的快取行為

• 物件大小限制：啟用 Livestream 擴展功能後，邊緣快取可快取的物件大小上限為 25 MiB。
• 超過 25 MiB 的物件：超過 25 MiB 的物件不會儲存在 Media CDN 邊緣快取中。根據預設，Media CDN 會將這些物件的所有要求直接 Proxy 至原始伺服器，因此每個用戶端要求都會產生原始要求。
  • 如要保護原始伺服器負載過重，可以啟用選用設定。啟用這項設定後，如果可快取的物件大於 25 MiB 上限，Media CDN 會傳回 503 Service Unavailable 回應，而不是將要求 Proxy 至來源。

注意： 直播擴展功能僅限許可清單中的人員使用，且預設為停用。如要為 Media CDN 服務啟用這項功能，請與 Google Cloud 銷售團隊或帳戶團隊聯絡。他們可以協助評估是否適合直播工作負載，並啟動啟用程序。

後續步驟

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