定义自定义标头

借助媒体 CDN，您可以指定自定义请求和响应标头。

借助自定义标头，您可以执行以下操作：

• 返回客户端的地理数据，例如国家/区域或城市，以便您显示本地化内容。
• 确定响应是否从缓存中传送（全部或部分），以及从哪个缓存位置传送。
• 移除、替换或附加请求和响应标头。

您还可以使用标头将请求路由到不同的来源。如果您需要配置跨源资源共享 (CORS) 标头，请为每个路由配置 CORS 政策。

设置自定义标头

您可以在每个路线上设置标头，以便为不同的内容（例如清单或视频片段）添加和移除标头。

在 CDN 处理路径的早期（在缓存决策之前）设置每个路由的自定义请求标头。例如，如果您将 cache-control 标头设置为按路由的自定义标头，则会影响 CDN 中的缓存行为。

默认情况下，添加的标头值以英文逗号分隔，并附加到具有相同字段名称的响应或请求标头。

如需覆盖现有值，请将 replace 设置为 true。

以下 .routing.pathMatchers[].routeRules[].headerAction 示例展示了在 EdgeCacheService 资源中添加和移除的标头：

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"

此示例会执行以下操作：

• 使用 {client_region} 变量向响应添加自定义 client-geo 标头，该变量会返回与客户端 IP 地址相关联的国家/地区（或区域）。
• 使用静态字符串将自定义 x-downstream-cdn 标头添加到请求。
• 移除了两个内部标头。

如需配置特定于来源的自定义标头，请参阅配置特定于来源的主机重写或标头修改。

动态标头变量

自定义标头可以包含一个或多个动态变量。

缓存键政策 (cacheKeyPolicy.includedHeaderNames) 中的请求标头可以包含一个或多个自定义变量。包含其他动态变量的请求标头不能包含在缓存键中。

变量	说明	支持请求标头	支持缓存键中的请求标头	支持响应标头
cdn_cache_status	请求/响应路径中每个缓存节点的位置（最近机场的 IATA 代码）和状态的分号分隔列表，其中最右侧的值表示距离用户最近的缓存。			✔
client_city	发起请求的城市名称，例如表示加利福尼亚州山景城的 Mountain View。此变量没有标准的有效值列表。城市名称可以包含 US-ASCII 字母、数字、空格和以下字符：!#$%&'*+-.^_`|~。	✔		✔
client_city_lat_long	发出请求的城市的纬度和经度，例如 37.386051,-122.083851（表示请求来自山景城）。	✔		✔
client_region	与客户端 IP 地址相关联的国家/地区（或区域）。这是 Unicode CLDR 区域代码，例如 US 或 FR。对于大多数国家/地区，这些代码直接对应于 ISO-3166-2 代码。	✔	✔	✔
client_region_subdivision	与客户端 IP 地址相关联的国家/地区的下属行政区（例如省或州）。这是 Unicode CLDR 下属行政区 ID，例如 USCA 或 CAON。这些 Unicode 代码从 ISO-3166-2 标准定义的下属行政单位派生而来。	✔	✔	✔
client_rtt_msec	CDN 与 HTTP(S) 客户端之间的预计往返传输时间，以毫秒为单位。这是 CDN 的 TCP 堆栈根据 RFC 2988 测量的平滑往返时间 (SRTT) 参数。	✔		✔
device_request_type	客户端使用的设备类型。有效值包括：DESKTOP、MOBILE、TABLET、SMART_TV、GAME_CONSOLE、WEARABLE 和 UNDETERMINED。	✔	✔
original_request_id	分配给最初生成此响应的请求的唯一标识符。对于缓存的响应，仅当此值与 request_id 不同时才填充。			✔
origin_name	代理响应的 EdgeCacheOrigin 资源。			✔
origin_request_header	反映的是请求中跨域资源共享 (CORS) 用例的 Origin 标头的值。			✔
proxy_status	响应路径中的中继 HTTP 代理列表。此值由 RFC 9209 定义。 EdgeCacheService 资源由 Google-Edge-Cache 表示。如果响应是从源中提取的，则 EdgeCacheOrigin 资源由 Google-Edge-Cache-Origin 表示。			✔
tls_sni_hostname	由客户端在 TLS 或 QUIC 握手期间提供的服务器名称指示（如 RFC 6066 中所定义）。系统会将主机名转换为小写字母并移除结尾的任何英文句点。	✔		✔
tls_version	客户端与负载均衡器在 SSL 握手期间协商的 TLS 版本。可能的值包括 TLSv1、TLSv1.1、TLSv1.2 和 TLSv1.3。如果客户端使用 QUIC（而不是 TLS）进行连接，则值为 QUIC。	✔		✔
tls_cipher_suite	在 TLS 握手期间协商的加密套件。该值由 IANA TLS 加密套件注册库定义，例如 TLS_RSA_WITH_AES_128_GCM_SHA256。对于 QUIC 和未加密的客户端连接，此值为空。	✔		✔
user_agent_family	客户端使用的浏览器系列。有效值包括：APPLE、APPLEWEBKIT、BLACKBERRY、DOCOMO、GECKO、GOOGLE、KHTML、KOREAN、MICROSOFT、MSIE、NOKIA、NETFRONT、OBIGO、OPENWAVE、OPERA、OTHER、POLARIS、TELECA、SEMC、SMIT 和 USER_DEFINED。	✔	✔

以下注意事项适用于自定义变量：

• 现有请求和响应标头会保留，但以下标头除外，它们会被移除：

  • X-User-IP
  • 包含 X-Google 或 X-GFE 的任何标头

• 标头键和值必须符合 RFC 7230 的规定，不允许使用已过时的格式。

• 所有标头键均采用小写形式（根据 HTTP/2）。

• 某些标头会合并。如果同一标头键（例如 Via）具有多个实例，则负载均衡器会将它们的值组合成单个标头键的单一英文逗号分隔列表。只有其值可以用英文逗号分隔列表来表示的标头会合并。 Set-Cookie 之类的其他标头永远不会合并。

• 系统会添加一些标头，或者为一些标头附加值。媒体 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，则所有缓存组件都会将请求的内容视为不可缓存，并且系统会从源提取对此内容的所有请求。为确保您的内容得到适当缓存，请查看媒体 CDN 源要求。

默认标头

Media CDN 会分别向源请求和客户端响应添加以下请求和响应标头。

标题	说明	请求	响应
x-request-id	给定请求的唯一标识符。此值也会作为 jsonPayload.requestId 添加到请求日志中，以便您将客户端请求/响应与日志条目相关联。		✔
age	返回缓存对象的年龄（在缓存中存储的时长（秒数））。系统通常根据对象最初缓存在长尾（屏蔽）缓存位置的时间来计算年龄。 系统不会从缓存中提供没有 age 标头的响应。		✔
via	将 Google 标识为中间代理。 此值设为 1.1 google，无法更改。	✔	✔
server	设置为 Google-Edge-Cache。		✔
cdn-loop	识别循环，例如，来源主机与面向用户的边缘主机相同。 系统会根据 RFC 8586 将 google 令牌附加到标头。令牌无法更改。	✔
forwarded	x-forwarded-for 标题的结构化版本。 forwarded 标头在 RFC 7239 中定义。 借助这些标头，您可以在路径中存在代理（或代理）时识别连接客户端的 IP 地址。例如，如果 IP 地址为 192.0.2.60 的客户端通过 HTTPS 连接到 Media CDN，则 forwarded 标头会按如下方式填充： forwarded: [for=192.0.2.60;proto=https] 如果有多个客户端代理，则与 Media CDN 连接的客户端是标头值中附加的最后一个地址。	✔
x-forwarded-for	forwarded 标头的非结构化事实标准版本。值通常以英文逗号分隔。 系统会在请求中发送这两个标头，以支持可能不知道 forwarded 标头的旧版源。	✔

请求标头和响应标头的标头键均采用小写形式，因为标头键不区分大小写。

您可以使用动态标头变量添加其他标头，包括边缘 PoP 位置和缓存状态（例如 hit 和 miss）。