定义自定义标头

媒体 CDN 可让您指定自定义请求和响应标头。

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

  • 返回有关客户端的地理位置数据，例如国家/地区、区域或城市 您可以用它显示本地化内容。
  • 确定响应是通过缓存提供的（全部还是部分）以及 以及从哪个缓存位置提供该资源
  • 移除、替换请求标头和响应标头，或者向其附加内容。

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

设置自定义标头

标头在每条路线上设置，以便您添加和移除 例如清单或视频片段

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

如需覆盖现有值，请将 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) 客户端（以毫秒为单位）。这是经过平滑处理的往返时间 (SRTT) 参数，由 CDN 的 TCP 堆栈测量， RFC 2988。 ✔ ✔
device_request_type 客户端使用的设备类型。这些是 值：DESKTOP、MOBILE、 TABLET、SMART_TV、 GAME_CONSOLE、WEARABLE、 和 UNDETERMINED。 ✔ ✔
original_request_id 分配给最初的请求的唯一标识符 生成了这条回答。仅当此值与此值不同时填充 request_id 表示已缓存的响应。 ✔
origin_name 提供响应的 EdgeCacheOrigin 资源 被代理。 ✔
origin_request_header 反映跨源请求中 Origin 标头的值 资源共享 (CORS) 用例。 ✔
proxy_status 响应路径中中间 HTTP 代理的列表。值 由 RFC 9209。 EdgeCacheService 资源由 Google-Edge-Cache.如果响应是从源站提取的 EdgeCacheOrigin 资源由 Google-Edge-Cache-Origin 表示。 ✔
tls_sni_hostname 服务器名称指示（如 RFC 6066），如果 由客户端在 TLS 或 QUIC 握手期间提供。主机名为 转换为小写，并且所有结尾的句点都会被移除。 ✔ ✔
tls_version 客户端与负载均衡器之间协商的 TLS 版本 在 SSL 握手时发送。可能的值包括 TLSv1、 TLSv1.1、TLSv1.2和 TLSv1.3。如果客户端使用 QUIC 而不是 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。

  • 媒体 CDN 使用支持的 变量，即使由客户端或源设置也是如此。这样， 您可以从客户端（例如视频播放器）或源设置动态标头 基础架构。 媒体 CDN 不会展开请求路径上的变量。

  • 例如，根据前面所述的规则，X-Goog- 和 系统会保留 X-Amz- 标头并将其转换为小写形式。

缓存状态值

{cdn_cache_status} 标头变量可以返回多个值 与提供响应的缓存层级相对应。考虑使用 以下是有关如何解读 {cdn_cache_status} 标头变量的准则：

  • 如果标头包含 hit，则检索到请求的内容 从缓存中移除
  • 如果标头包含 miss，则表示请求的内容不是 在缓存节点中发现，必须从上游节点检索。
  • 如果标头包含 fetch，则请求的内容为： 。

  • 如果标头包含 uncacheable，则请求的内容为： 被缓存的部分或全部组件视为不可缓存 基础架构

    • 如果标头还包含 hit 或 miss，则 请求的内容被某些缓存组件视为不可缓存 并可供其他人缓存
    • 如果标头没有同时包含 hit 或 miss，请求的内容被视为不可缓存 并且系统会提取针对该内容的所有请求 。为了确保您的内容得到正确缓存，请查看 媒体 CDN 来源 要求。

默认标头

媒体 CDN 将以下请求和响应标头添加到 来源请求和客户端响应。

标题 说明 请求 响应
x-request-id 指定请求的唯一标识符。此值也会 作为 jsonPayload.requestId 添加到请求日志中， 可让您将客户端请求/响应与日志条目相关联。 ✔
age

返回缓存对象的存在时间（该对象已停留的秒数） 在缓存中）。年龄通常是根据 对象最初缓存在长尾（护盾）缓存位置。

不含 age 标头的响应不会来自 缓存。

 ✔
via

将 Google 标识为中间代理。

它已设为1.1 google，因此无法更改。

 ✔ ✔
server 已设置为 Google-Edge-Cache。 ✔
cdn-loop

标识循环，例如，其中源主机是 与面向用户的（边缘）主机相同。

根据google RFC 8586。无法更改令牌。

 ✔
forwarded

x-forwarded-for 标头的结构化版本。 forwarded 标头为 已定义 （位于 RFC 7239）。

这些标头可让您标识连接的 IP 地址， 当路径中包含一个或多个代理时，该客户端会通知客户端。例如，如果 IP 地址为 192.0.2.60 的客户端连接到 基于 HTTPS 的媒体 CDN，forwarded 标头的填充内容如下：

forwarded: [for=192.0.2.60;proto=https]

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

 ✔
x-forwarded-for

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

这两个标头都在请求中发送，以支持可能 不知道 forwarded 标头。

 ✔

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

其他标头，包括边缘入网点 (PoP) 位置和缓存 状态（例如 hit 和 miss），使用 动态标头变量。