routeRules:-priority:1description:"videoroutes"matchRules:-prefixMatch:"/video/"headerAction:responseHeadersToAdd:# Return the country (or region) associated with the client's IP address.-headerName:"client-geo"headerValue:"{client_region}"replace:truerequestHeadersToAdd:# Inform the upstream origin server the request is from Media CDN-headerName:"x-downstream-cdn"headerValue:"MediaCDN"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 位址相關聯的國家/地區。
[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["難以理解","hardToUnderstand","thumb-down"],["資訊或程式碼範例有誤","incorrectInformationOrSampleCode","thumb-down"],["缺少我需要的資訊/範例","missingTheInformationSamplesINeed","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間：2025-09-03 (世界標準時間)。"],[],[],null,["# Define custom headers\n\nMedia CDN lets you specify custom request and response headers.\n\nCustom headers let you do the following:\n\n- Return geographic data about the client, such as country, region, or city, that you can use to show localized content.\n- Determine whether a response was served from cache (in full or in part) and which cache location it was served from.\n- Remove, replace, or append to both request and response headers.\n\nSet custom headers\n------------------\n\nHeaders are set on each route, which lets you add and remove headers for\ndifferent content, such as manifests or video segments.\n\nSet per-route custom request headers early in the CDN processing path, prior to\ncaching decisions. For example, if you set a `cache-control` header as a\nper-route custom header, it affects caching behavior in the CDN.\n\nBy default, added header values are comma-separated and appended to the response\nor request headers with the same field names.\n\nTo overwrite existing values, set `replace` to `true`. \n\n### gcloud and YAML\n\nTo list the YAML configuration for the `EdgeCacheService` resource, use\nthe following command: \n\n```\ngcloud edge-cache services describe prod-media-service\n```\n\nThe `.routing.pathMatchers[].routeRules[].headerAction` section shows\nthe headers to be added and removed: \n\n routeRules:\n - priority: 1\n description: \"video routes\"\n matchRules:\n - prefixMatch: \"/video/\"\n headerAction:\n responseHeadersToAdd:\n # Return the country (or region) associated with the client's IP address.\n - headerName: \"client-geo\"\n headerValue: \"{client_region}\"\n replace: true\n requestHeadersToAdd:\n # Inform the upstream origin server the request is from Media CDN\n - headerName: \"x-downstream-cdn\"\n headerValue: \"Media CDN\"\n responseHeadersToRemove:\n - headerName: \"X-User-ID\"\n - headerName: \"X-Other-Internal-Header\"\n\n### Terraform\n\nThe following Terraform snippet shows a route rule with custom headers. \n\n route_rule {\n description = \"video routes\"\n priority = 1\n match_rule {\n prefix_match = \"/video/\"\n }\n origin = google_network_services_edge_cache_origin.default.name\n header_action {\n response_header_to_add {\n # Return the country (or region) associated with the client's IP address.\n header_name = \"client-geo\"\n header_value = \"{client_region}\"\n replace = true\n }\n request_header_to_add {\n # Inform the upstream origin server that the request is from Media CDN.\n header_name = \"x-downstream-cdn\"\n header_value = \"Media CDN\"\n }\n response_header_to_remove {\n header_name = \"X-User-ID\"\n }\n response_header_to_remove {\n header_name = \"X-Other-Internal-Header\"\n }\n }\n }\n\nThis example does the following:\n\n- Adds a custom `client-geo` header to the response by using the `{client_region}` variable, which returns the country (or region) associated with the client's IP address.\n- Adds a custom `x-downstream-cdn` header to the request by using a static string.\n- Removes two internal headers.\n\nTo configure origin-specific custom headers, see\n[Configure origin-specific host rewrites or header modifications](/media-cdn/docs/configure-origin#configure-rewrites).\n\nDynamic header variables\n------------------------\n\nCustom headers can contain one or more dynamic variables.\n\nRequest headers that are a part of cache key policy (`cacheKeyPolicy.includedHeaderNames`)\ncan contain one or more custom variables. Request headers that contain other\ndynamic variables can't be a part of the cache key.\n\nThe following considerations apply to custom variables:\n\n- Existing request and response headers are preserved, except for the\n following, which are removed:\n\n - `X-User-IP`\n - Any headers with `X-Google` or `X-GFE`\n- Header keys and values must be compliant with [RFC\n 7230](https://tools.ietf.org/html/rfc7230), with\n obsolete forms disallowed.\n\n- All header keys are lowercased (per HTTP/2).\n\n- Some headers are coalesced. When there are multiple instances of the same\n header key (for example, `Via`), the load balancer combines their values\n into a single comma-separated list for a single header key. Only the headers\n whose values can be represented as a comma-separated list are coalesced.\n Other headers, such as `Set-Cookie`, are never coalesced.\n\n- Some headers are added, or values are appended to them.\n Media CDN always adds or modifies certain headers, such as\n `X-Forwarded-For`.\n\n- Media CDN expands any response header with a [supported\n variable](#header-variables), even if set by the client or origin. This lets\n you set dynamic headers from your client (such as a video player) or origin\n infrastructure, in addition to configuring custom headers.\n Media CDN doesn't expand variables on the request path.\n\n- As an example, as per the rules described earlier, `X-Goog-` and\n `X-Amz-` headers are preserved and lowercased.\n\nCache status values\n-------------------\n\nThe `{cdn_cache_status}` header variable can return multiple values\ncorresponding to the tier of cache that served the response. Consider the\nfollowing guidelines for interpreting the `{cdn_cache_status}` header variable:\n\n- If the header contains `hit`, the requested content was retrieved from the cache.\n- If the header contains `miss`, the requested content was not found in a cache node and had to be retrieved from an upstream node.\n- If the header contains `fetch`, the requested content was retrieved from the origin.\n- If the header contains `uncacheable`, the requested content was\n considered uncacheable by some or all components of the caching\n infrastructure.\n\n - If the header also contains `hit` or `miss`, the requested content was considered uncacheable by some caching components and cacheable by others.\n - If the header does not also contain `hit` or `miss`, the requested content was considered uncacheable by all caching components, and all requests for this content are fetched from the origin. To ensure that your content is cached appropriately, review the Media CDN [origin\n requirements](/media-cdn/docs/origins#origin-requirements).\n\nDefault headers\n---------------\n\nMedia CDN adds the following request and response headers to\norigin requests and client responses, respectively.\n\nHeader keys are lowercased for both request and response headers because header\nkeys are case-insensitive.\n\nOther headers, including the edge point of presence (PoP) location and cache\nstatus (such as `hit` and `miss`), can be added by using\n[dynamic header variables](#header-variables)."]]
