定义自定义标头

借助媒体 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-geo {client_region} 变量，用于返回关联的国家/地区（或区域） 替换为客户端的 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]

如果有多个客户端代理，连接到 媒体 CDN 是标头中附加的最后一个地址 值。

 ✔
x-forwarded-for

非结构化的、实际上是标准版本的 forwarded 标头。值通常以英文逗号分隔。

系统会在请求中发送这两个标头，以支持可能不知道 forwarded 标头的旧版源。

 ✔

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

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