创建自定义标头

使用自定义请求和响应标头,您可以指定外部 HTTP(S) 负载平衡器在请求和响应中添加的额外标头。这些标头可以包含负载平衡器检测到的客户端连接信息,包括客户端的延迟时间、客户端 IP 地址的地理位置以及 TLS 连接的参数。

后端服务支持自定义请求标头,而后端服务和后端存储分区支持自定义响应标头。

默认情况下,HTTP(S) 负载平衡会将某些标头添加到其在后端和客户端之间代理的所有 HTTP(S) 请求和响应。如需了解详情,请参阅目标代理

准备工作

  • 如有必要,请更新到 Cloud SDK 的最新版本:

    gcloud components update
    

自定义标头的工作原理

自定义标头的工作原理如下:

  • 当外部 HTTP(S) 负载平衡器向后端发出请求时,负载平衡器会添加请求标头。

  • 外部 HTTP(S) 负载平衡器会在将响应返回给客户端之前设置响应标头。

请求和响应标头不会影响缓存或负载平衡器行为。

要启用自定义标头,您可以在后端服务或后端存储分区的属性中指定标头列表。

您可以将每个标头指定为 header-name:header-value 字符串。标头必须包含用于分隔标头名称和标头值的英文冒号。标头名称具有以下属性:

  • 标头名称必须是有效的 HTTP 标头字段名称定义(根据 RFC 7230)。
  • 标头名称不得为 X-User-IPCDN-Loop
  • 标头名称不得以 X-GoogleX-Goog-X-GFEX-Amz- 开头。
  • 标头名称不能在已添加标头的列表中出现多次。

标头值具有以下属性:

  • 标头值必须是有效的 HTTP 标头字段定义(根据 RFC 7230,不允许使用已过时的格式)。
  • 标头值可以为空。
  • 标头值可以包含一个或多个由花括号括起来的变量,这些变量可扩展为负载平衡器提供的值。标头值中允许使用的变量列表将在下一部分中介绍。

例如,您可以为客户端区域和客户端城市指定一个包含两个变量名称的标头。gcloud 命令行工具有一个用于指定请求标头 --custom-request-header 的标志。例如:

    --custom-request-header 'X-Client-Geo-Location:{client_region},{client_city}'

如果客户端位于加利福尼亚州山景城,则负载平衡器会添加如下所示的标头:

X-Client-Geo-Location:US,Mountain View

该标志的常规格式如下:

    --custom-request-header='HEADER_NAME:[HEADER_VALUE]'

标头值必须用花括号括起来。例如:

    --custom-request-header='X-PLACE:{client_city},{client_city_lat_long}'

请在此命令中仅使用直引号 (')。

可以出现在标头值中的变量

以下变量可以出现在自定义标头值中。

变量 说明
cdn_cache_id 用于传送请求的缓存实例的位置代码和 ID。此值与 Logging 中 Cloud CDN 请求日志的 jsonPayload.cacheId 字段中填充的值相同。
cdn_cache_status 当前缓存状态。对于启用 Cloud CDN 的后端传送的任何对象,值可以是 hitmissrevalidatedstaleuncacheabledisabled
origin_request_header 反映的是请求中跨域资源共享 (CORS) 用例的 Origin 标头的值。
client_rtt_msec 负载平衡器与 HTTP(S) 客户端之间的预计往返传输时间,以毫秒为单位。这是负载平衡器的 TCP 堆栈根据 RFC 2988 测量的平滑往返时间 (SRTT) 参数。
client_region 与客户端 IP 地址相关联的国家/地区(或区域)。这是一个 Unicode CLDR 区域代码,例如 USFR。(对于大多数国家/地区,这些代码直接对应于 ISO-3166-2 代码。)
client_region_subdivision 与客户端 IP 地址相关联的国家/地区的下属行政单位,例如省或州。这是一个 Unicode CLDR 下属行政单位 ID,例如 USCACAON。(这些 Unicode 代码从 ISO-3166-2 标准定义的下属行政单位派生而来。)
client_city 发起请求的城市名称,例如表示加利福尼亚州山景城的 Mountain View。此变量没有标准的有效值列表。城市名称可以包含 US-ASCII 字母、数字、空格和以下字符:!#$%&'*+-.^_`|~
client_city_lat_long 发出请求的城市的纬度和经度,例如 37.386051,-122.083851(表示请求来自山景城)。
tls_sni_hostname 由客户端在 TLS 或 QUIC 握手期间提供的服务器名称指示(如 RFC 6066 中所定义)。系统会将主机名转换为小写字母并移除结尾的任何英文句点。
tls_version 客户端与负载平衡器在 SSL 握手期间协商的 TLS 版本。可能的值包括 TLSv1TLSv1.1TLSv1.2TLSv1.3。如果客户端使用 QUIC(而不是 TLS)进行连接,则值将为 QUIC
tls_cipher_suite 在 TLS 握手期间协商的加密套件。该值是由 IANA TLS 加密套件注册表定义的四位十六进制数字,例如 009C 表示 TLS_RSA_WITH_AES_128_GCM_SHA256。对于 QUIC 和未加密的客户端连接,此值为空。

负载平衡器在无法确定变量值时会将变量扩展为空字符串。例如:

  • IP 地址的位置未知时的地理位置变量
  • 未使用 TLS 时的 TLS 参数
  • 请求不包含 Origin 标头时的 {origin_request_header}
  • 请求标头中包含时的 {cdn_cache_status} 标头

地理位置值(地区、下属行政单位和城市)是根据客户端 IP 地址估算的值。Google 会不时地更新提供这些值的数据,以便提高准确性并反映地理和政治方面的变化。

负载平衡器添加的标头会覆盖任何同名的现有标头。标头名称不区分大小写。当标头名称传递至 HTTP/2 后端时,HTTP/2 协议会将标头名称编码为小写。

在标头值中,前导空格和尾随空格无意义,因此不会传递至后端。为了允许在标头值中使用花括号,负载平衡器会将两个左花括号 ({{) 解释为一个左花括号 ({),而将两个右花括号 (}}) 解释为一个右花括号 (})。

使用自定义请求标头

控制台

要向现有后端服务添加自定义请求标头,请执行以下操作:

  1. 转到负载平衡摘要页面。
    转到“负载平衡”页面
  2. 点击后端
  3. 点击后端服务的名称。
  4. 点击修改
  5. 点击高级配置(会话粘性、连接排空超时时间、安全政策)
  6. 自定义请求标头下,点击添加标头 (Add header)。
  7. 输入自定义请求标头的标头名称标头值
  8. 输入其他任何自定义请求标头。
  9. 点击保存

要从后端服务中移除自定义请求标头,请执行以下操作:

  1. 转到负载平衡摘要页面。
    转到“负载平衡”页面
  2. 点击后端
  3. 点击后端服务的名称。
  4. 点击修改
  5. 点击高级配置(会话粘性、连接排空超时时间、安全政策)
  6. 点击您要移除的自定义请求标头名称旁边的 X
  7. 点击保存

gcloud

要使用自定义请求标头创建后端服务,请执行以下操作:

gcloud beta compute backend-services create BACKEND_SERVICE_NAME \
  --global-health-checks \
  --global \
  --protocol HTTPS \
  --health-checks https-basic-check \
  --custom-request-header 'HEADER_NAME:[HEADER_VALUE]'

要添加更多请求标头,请通过重复使用 --custom-request-header 标志来指定独一无二的标头名称和值。

要向现有后端服务添加自定义标头,请执行以下操作:

gcloud beta compute backend-services update BACKEND_SERVICE_NAME \
  --global \
  --custom-request-header 'HEADER_NAME:[HEADER_VALUE]' \
  --custom-request-header 'HEADER_NAME:[HEADER_VALUE]'

请注意,上述命令会将后端服务中已经存在的任何标头替换为您在该命令中指定的请求标头。

要从后端服务移除所有标头,请运行以下命令:

gcloud beta compute backend-services update BACKEND_SERVICE_NAME \
  --global \
  --no-custom-request-headers

API

backendServices.patch 方法发出 PATCH 请求。

PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/BACKEND_SERVICE_NAME
"customRequestHeaders": [
   "client_city:Mountain View"
]

使用自定义响应标头

控制台

目前不支持 Cloud Console。

gcloud

对于后端服务,请使用带有 --custom-response-header 标志的 gcloud beta compute backend-services creategcloud beta compute backend-services update 命令。

对于后端存储分区,请使用带有 --custom-response-header 标志的 gcloud beta compute backend-buckets creategcloud beta compute backend-buckets update 命令。

gcloud beta compute backend-services (create | update) BACKEND_SERVICE_NAME
    --custom-response-header='HEADER_NAME:[HEADER_VALUE]'
gcloud beta compute backend-buckets (create | update) BACKEND_BUCKET_NAME
    --custom-response-header='HEADER_NAME:[HEADER_VALUE]'

例如:

gcloud beta compute backend-buckets update gaming-lab \
    --custom-response-header='X-Frame-Options: DENY'

API

对于后端存储分区,请使用方法:backendBuckets.insert方法:backendBuckets.update API 调用。

对于后端服务,请使用方法:backendServices.insert方法:backendServices.update API 调用。

使用以下 API 调用之一:

POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/global/backendBuckets

PUT https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/global/backendBuckets/BACKEND_BUCKET_NAME

POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/global/backendServices

PUT https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/global/backendServices/BACKEND_SERVICE_NAME

将以下代码段添加到 JSON 请求正文:

"cdnPolicy": {
  "customResponseHeaders":HEADER_NAME:[HEADER_VALUE]
}

设置 Cloud Storage 的响应标头

如果您需要对来自 Cloud Storage 的响应(例如跨域资源政策、X-Frame-OptionsX-XSS-Protection 标头)设置其他 HTTP 标头,则可以使用 Google Cloud 提供的两个选项通过 Cloud Storage 为 Cloud CDN 设置自定义标头:

限制

自定义标头存在以下限制:

  • 您可以为每个后端服务指定最多 16 个自定义请求标头。
  • 您可以为每个后端服务指定最多 16 个自定义响应标头。
  • 每个后端服务的所有自定义请求标头(名称和值组合,以及在变量扩展之前)的总大小不能超过 8 KB。
  • 每个后端服务的所有自定义响应标头(名称和值组合,以及在变量扩展之前)的总大小不能超过 8 KB。

后续步骤