定义自定义标头

媒体 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_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) 用例请求中的来源标头值。			✔
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 和 {2。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	标识循环，例如，源主机与面向用户的（边缘）主机相同。 根据 RFC 8586，标头中会附加一个令牌 google。无法更改令牌。	✔
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）。