本頁面由 Cloud Translation API 翻譯而成。

在後端服務中建立自訂標頭

本頁說明如何設定傳統型應用程式負載平衡器所用後端服務中的自訂標頭。

自訂要求和回應標頭可讓您指定其他標頭，供負載平衡器新增至 HTTP(S) 要求和回應。視負載平衡器偵測到的資訊而定，這些標頭可能包含下列資訊：

用戶端延遲時間
用戶端 IP 位址的地理位置
TLS 連線的參數

後端服務支援自訂要求標頭，後端服務和後端值區則支援自訂回應標頭。

負載平衡器預設會為後端與用戶端之間代理的所有 HTTP(S) 要求和回應，新增特定標頭。詳情請參閱「目標 Proxy」。

事前準備

請視需要更新至最新版 Google Cloud CLI：
```
gcloud components update
```
注意： 請確認您使用的是 gcloud CLI 309.0.0 以上版本。

自訂標頭的運作方式

自訂標頭的運作方式如下：

負載平衡器將要求轉送至後端時，會新增要求標頭。

負載平衡器只會將自訂要求標頭新增至用戶端要求，不會新增至健康狀態檢查探測。如果後端需要授權專用的標頭，但健康狀態檢查封包中沒有，健康狀態檢查可能會失敗。
負載平衡器會在將回應傳回給用戶端前，設定回應標頭。

如要啟用自訂標頭，請在後端服務或後端值區的屬性中指定標頭清單。

您可以將標題當做 header-name:header-value 字串來指定。標頭必須包含一個冒號，用於分隔標頭名稱和標頭值。

標頭名稱必須符合下列規定：

標頭名稱必須是有效的 HTTP 標頭欄位名稱定義 (根據 RFC 7230 的規定)。
標頭名稱不得為 X-User-IP 或 CDN-Loop。
不得使用下列逐一躍點標頭：Keep-Alive、Transfer-Encoding、TE、Connection、Trailer 和 Upgrade。根據 RFC 2616，這些標頭不會儲存在快取中，也不會由目標 Proxy 傳播。
標頭名稱不得以 X-Google、X-Goog-、X-GFE 或 X-Amz- 開頭。
標頭名稱在新增標頭清單中不可出現超過一次。

標頭值必須符合下列規定：

標頭值必須是有效的 HTTP 標頭欄位定義 (根據 RFC 7230 的規定，您將無法使用已過時的表單)。
標題值可以空白。
標頭值可以包含一個或多個變數 (由大括號括住)，以囊括負載平衡器提供的值。標題值中允許包含的變數清單將於下節進一步說明。

gcloud 指令列工具有一個可用於指定要求標頭的標記，也就是 --custom-request-header。請務必使用這個標記，將標頭名稱和標頭值放在直式單引號 (') 中。

標記的格式大致如下：

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

以下是標題值的範例，其中包含以大括號括住的兩個變數：client_region 和 client_city。

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

負載平衡器會對位於加州山景城的用戶端新增以下的標頭：

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

如要建立含自訂標頭的後端服務，請參閱「設定自訂要求標頭」。

標頭值支援的變數

以下變數可以出現在自訂標頭值中。

變數	說明
`cdn_cache_id`	用於處理要求的快取執行個體位置代碼和 ID。這與 Logging 中 Cloud CDN 要求記錄的 `jsonPayload.cacheId` 欄位所填入的值相同。
`cdn_cache_status`	目前的快取狀態。值可以是 `hit`、`miss`、`revalidated`、`stale`、`uncacheable` 或 `disabled`，適用於 Cloud CDN 啟用後端服務的任何物件。
`origin_request_header`	反映要求中 `Origin` 標頭的值，適用於跨源資源共享 (CORS) 用例。
`client_rtt_msec`	負載平衡器與 HTTP(S) 用戶端之間的預估往返傳輸時間，以毫秒為單位。這是負載平衡器的 TCP 堆疊根據 RFC 2988 測量出的順暢往返時間 (SRTT) 參數。平滑 RTT 是一種演算法，可處理 RTT 測量中可能發生的變化和異常狀況。
`client_region`	與用戶端 IP 位址關聯的國家 (或地區)。這是 Unicode CLDR 地區代碼，例如 `US` 或 `FR`。(大部分國家的代碼都可以與 ISO-3166-2 代碼直接對應)。
`client_region_subdivision`	與客戶 IP 位址關聯的國家分區，例如省或州。這是 Unicode CLDR 分區 ID，例如 `USCA` 或 `CAON`。(這些 Unicode 代碼是從 ISO-3166-2 標準所定義的分區衍生出來的)。
`client_city`	發出要求的城市名稱，例如加州山景城。`Mountain View`這個變數沒有有效值的標準清單。城市名稱可包含 US-ASCII 字母、數字、空格及下列字元：!#$%&'*+-.^_`\|~。
`client_city_lat_long`	發出要求的城市經緯度，例如，以「37.386051,-122.083851」表示從山景城發出的要求。`37.386051,-122.083851`
`client_ip_address`	用戶端的 IP 位址。除非用戶端使用 Proxy 或 `X-Forwarded-For` 標頭遭到竄改，否則這通常與用戶端 IP 位址相同，也就是 `X-Forwarded-For` 標頭中倒數第二個位址。
`client_port`	用戶端的來源通訊埠。
`client_encrypted`	`true` 如果用戶端與負載平衡器之間的連線已加密 (使用 HTTPS、HTTP/2 或 HTTP/3)；否則為 `false`。
`client_protocol`	用戶端與負載平衡器之間通訊所用的 HTTP 通訊協定。只能設為以下任一種：`HTTP/1.0`、`HTTP/1.1`、`HTTP/2` 或 `HTTP/3`。
`device_request_type`	用戶端的裝置，衍生自 `User-Agent` 標頭值。可能的值如下： `DESKTOP`、`GAME_CONSOLE`、 `GAME_CONSOLE`、 `MOBILE`、`SET_TOP_BOX`、 `SMART_SPEAKER`、`SMART_TV`、 `TABLET`、`UNDETERMINED`、 `WEARABLE`。
`server_ip_address`	用戶端連線的負載平衡器 IP 位址。如果多個負載平衡器共用後端，這個做法就非常實用。這與 `X-Forwarded-For` 標頭中的最後一個 IP 位址相同。
`server_port`	用戶端連線的目標通訊埠編號。
`tls_sni_hostname`	伺服器名稱指標 (如 RFC 6066 中的定義)，如果用戶端在 TLS 或 QUIC 交握期間提供。系統會將主機名稱轉換為小寫，並移除任何的尾隨點。
`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 的值為 `009C`。對於 QUIC 和未加密的用戶端連線，該值為空。
`tls_ja3_fingerprint`	JA3 TLS/SSL 指紋 (如果用戶端使用 HTTPS、HTTP/2 或 HTTP/3 連線)。
`user_agent_family`	用戶端瀏覽器類型，衍生自 `User-Agent` 標頭值。可能的值如下： `APPLE`、`APPLEWEBKIT`、`BLACKBERRY`、 `DOCOMO`、`GECKO`、`GOOGLE`、 `KHTML`、`KOREAN`、`MICROSOFT`、 `MSIE`、`NETFRONT`、`NOKIA`、 `OBIGO`、`OPERA`、`OPENWAVE`、 `OTHER`、`POLARIS`、`SEMC`、 `SMIT`、`TELECA`、`USER_DEFINED`。

當負載平衡器無法確定變數的值時，會將其代換為空字串。例如：

IP 位址位置不明時的地理位置變數
未使用 TLS 時的 TLS 參數
要求未包含 Origin 標頭時的 {origin_request_header}
要求標頭中包含的 {cdn_cache_status} 標頭

地理值 (地區、分區和城市) 是根據用戶端 IP 位址判斷的預估值。Google 會不時更新這些值的資料，以提高準確度及反映地理和政治上的變化。即使原始 X-Forwarded-For 標頭包含有效的位置資訊，Google 仍會使用負載平衡器收到的封包所含來源 IP 位址資訊，估算用戶端位置。

負載平衡器新增的標頭會覆寫任何名稱相同的既有標頭。標頭名稱不區分大小寫。標頭名稱傳送至 HTTP/2 後端時，HTTP/2 通訊協定會將標頭名稱轉換成小寫編碼。

標頭值中的前置空格及後置空格無關緊要，系統並不會將其傳送至後端。為了能在標頭值中使用大括號，負載平衡器會將雙左大括號 ({{) 解譯成單左括號 ({)，並將雙右大括號 (}}) 解譯成單右括號 (})。

雙向傳輸層安全標準 (TLS) 自訂標頭

如果在負載平衡器的 TargetHttpsProxy 上設定相互 TLS (mTLS)，則可以使用下列額外標頭變數。

變數	說明
`client_cert_present`	`true` 如果用戶端在 TLS 交握期間提供憑證；否則為 `false`。
`client_cert_chain_verified`	`true` (如果已根據設定的 `TrustStore` 驗證用戶端憑證鏈結)；否則為 `false`。
`client_cert_error`	代表錯誤情況的預先定義字串。如要進一步瞭解錯誤字串，請參閱「mTLS 用戶端驗證模式」。
`client_cert_sha256_fingerprint`	用戶端憑證的 Base64 編碼 SHA-256 指紋。
`client_cert_serial_number`	用戶端憑證的序號。如果序號長度超過 50 個位元組，`client_cert_error` 會設為 `client_cert_serial_number_exceeded_size_limit`，序號則會設為空白字串。
`client_cert_spiffe_id`	主體別名 (SAN) 欄位中的 SPIFFE ID。如果值無效或超過 2048 個位元組，SPIFFE ID 會設為空白字串。如果 SPIFFE ID 超過 2048 個位元組，`client_cert_error` 會設為 `client_cert_spiffe_id_exceeded_size_limit`。
`client_cert_uri_sans`	以逗號分隔的 Base64 編碼清單，列出 URI 類型的 SAN 擴充功能。系統會從用戶端憑證擷取 SAN 擴充功能。 SPIFFE ID 不會包含在 `client_cert_uri_sans` 欄位中。如果 `client_cert_uri_sans` 長度超過 512 個位元組，`client_cert_error` 會設為 `client_cert_uri_sans_exceeded_size_limit`，而以半形逗號分隔的清單則會設為空字串。
`client_cert_dnsname_sans`	以逗號分隔的 Base64 編碼清單，列出 DNSName 類型的 SAN 擴充功能。系統會從用戶端憑證擷取 SAN 擴充功能。如果 `client_cert_dnsname_sans` 長度超過 512 個位元組，`client_cert_error` 會設為 `client_cert_dnsname_sans_exceeded_size_limit`，而以半形逗號分隔的清單則會設為空字串。
`client_cert_valid_not_before`	時間戳記 (RFC 3339 日期字串格式)，指出用戶端憑證失效的時間。例如：`2022-07-01T18:05:09+00:00`。
`client_cert_valid_not_after`	用戶端憑證失效的時間戳記 (RFC 3339 日期字串格式)。例如：`2022-07-01T18:05:09+00:00`。
`client_cert_issuer_dn`	憑證中完整「簽發者」欄位的 Base64 編碼 DER 編碼。如果 `client_cert_issuer_dn` 長度超過 512 個位元組，系統會將字串 `client_cert_issuer_dn_exceeded_size_limit` 新增至 `client_cert_error`，並將 `client_cert_issuer_dn` 設為空字串。
`client_cert_subject_dn`	憑證中完整「主體」欄位的 Base64 編碼 DER 編碼。如果 `client_cert_subject_dn` 長度超過 512 個位元組，系統會將字串 `client_cert_subject_dn_exceeded_size_limit` 新增至 `client_cert_error`，並將 `client_cert_subject_dn` 設為空字串。
`client_cert_leaf`	已建立 mTLS 連線的用戶端葉子憑證，且該憑證已通過驗證。憑證編碼符合 RFC 9440 規範。也就是說，二進位 DER 憑證會使用 Base64 編碼，並以半形冒號做為兩側的分隔符。如果 `client_cert_leaf` 超過 16 KB (未編碼)，系統會將字串 `client_cert_validated_leaf_exceeded_size_limit` 新增至 `client_cert_error`，並將 `client_cert_leaf` 設為空字串。
`client_cert_chain`	以半形逗號分隔的憑證清單，採用標準 TLS 順序，列出已建立 mTLS 連線的用戶端憑證鏈結 (不含葉憑證)，且用戶端憑證已通過驗證。憑證編碼符合 RFC 9440 規範。如果 `client_cert_leaf` 和 `client_cert_chain` 在 Base64 編碼前的總大小超過 16 KB，系統會在 `client_cert_error` 中加入字串 `client_cert_validated_chain_exceeded_size_limit`，並將 `client_cert_chain` 設為空字串。

設定自訂要求標頭

主控台

如要將自訂要求標頭新增至現有的後端服務：

前往「Load balancing」(負載平衡) 摘要頁面。
前往「Load balancing」(負載平衡) 頁面
點選「後端」。
按一下後端服務的名稱。
按一下「編輯」圖示。
按一下 [Advanced configurations (Session affinity, connection draining timeout, security policies)] (進階設定 (工作階段相依性、連線排除逾時、安全性政策))。
在「Custom request headers」(自訂要求標頭) 下方，按一下 [Add header] (新增標頭)。
輸入自訂要求標頭的「Header name」(標頭名稱) 和「Header value」(標頭值)。
輸入任何其他自訂要求標頭。
按一下 [Save] (儲存)。

如要從後端服務移除自訂要求標頭：

前往「Load balancing」(負載平衡) 摘要頁面。
前往「Load balancing」(負載平衡) 頁面
點選「後端」。
按一下後端服務的名稱。
按一下「編輯」圖示。
按一下 [Advanced configurations (Session affinity, connection draining timeout, security policies)] (進階設定 (工作階段相依性、連線排除逾時、安全性政策))。
按一下要移除的自訂要求標頭名稱旁邊的「X」X。
按一下 [儲存]。

gcloud

如要指定自訂要求標頭，請使用 gcloud compute backend-services create 或 gcloud compute backend-services update 指令，並加上 --custom-request-header 標記。

如要建立含自訂要求標頭的後端服務：

gcloud 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 compute backend-services update BACKEND_SERVICE_NAME \
    --global \
    --custom-request-header='HEADER_1_NAME:[HEADER_1_VALUE]' \
    --custom-request-header='HEADER_2_NAME:[HEADER_2_VALUE]'

上一步驟會將後端服務中已存在的標頭，替換為您在指令中指定的要求標頭。

如要從後端服務移除所有標頭：

gcloud 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"
]

Terraform

如需建立含自訂標頭負載平衡器的 Terraform 指令碼，請參閱全域外部應用程式負載平衡器的 Terraform 範例。

設定自訂回應標頭

主控台

如要將自訂回應標頭新增至現有的後端服務：

前往「Load balancing」(負載平衡) 摘要頁面。
前往「Load balancing」(負載平衡) 頁面
點選「後端」。
按一下後端服務的名稱。
按一下「編輯」圖示。
按一下 [Advanced configurations (Session affinity, connection draining timeout, security policies)] (進階設定 (工作階段相依性、連線排除逾時、安全性政策))。
在「Custom response headers」(自訂回應標頭) 下方，按一下「Add header」(新增標頭)。
輸入自訂回應標頭的「Header name」(標頭名稱) 和「Header value」(標頭值)。
輸入任何其他自訂回應標頭。
按一下 [儲存]。

如要從後端服務移除自訂回應標頭：

前往「Load balancing」(負載平衡) 摘要頁面。
前往「Load balancing」(負載平衡) 頁面
點選「後端」。
按一下後端服務的名稱。
按一下「編輯」圖示。
按一下 [Advanced configurations (Session affinity, connection draining timeout, security policies)] (進階設定 (工作階段相依性、連線排除逾時、安全性政策))。
按一下要移除的自訂回應標頭名稱旁邊的「X」X。
按一下 [儲存]。

gcloud

如果是後端服務，請使用 gcloud compute backend-services create 或 gcloud compute backend-services update 指令，並加上 --custom-response-header 旗標。

如果是後端 bucket，請使用 gcloud compute backend-buckets create 或 gcloud compute backend-buckets update 指令，並加上 --custom-response-header 旗標。

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

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

使用 X-Frame-Options 標頭的範例：

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

使用 Strict-Transport-Security 標頭的範例：

以下範例說明如何新增自訂回應標頭，以支援 HTTP 嚴格傳輸安全性 (HSTS)：

gcloud compute backend-services update customer-bs-name \
    --global \
    --custom-response-header='Strict-Transport-Security: max-age=63072000'

API

如果是後端 bucket，請使用 Method: backendBuckets.insert 或 Method: backendBuckets.update API 呼叫。

如果是後端服務，請使用 Method: backendServices.insert 或 Method: backendServices.update API 呼叫。

請使用下列其中一個 API 呼叫：

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

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

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

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

在 JSON 要求主體中新增下列程式碼片段：

"customResponseHeaders":HEADER_NAME:[HEADER_VALUE]

Terraform

如需建立含自訂標頭負載平衡器的 Terraform 指令碼，請參閱全域外部應用程式負載平衡器的 Terraform 範例。

設定 Cloud Storage 的回應標頭

如需在 Cloud Storage 的回應中設定 HTTP 標頭 (例如跨來源資源政策、X-Frame-Options 或 X-XSS-Protection 標頭)，Google Cloud 提供使用 Cloud Storage 自訂 Cloud CDN 標頭的選項。如要這麼做，請在負載平衡器後端 bucket 層級設定自訂標頭，如本頁所述。

只有在用戶端要求傳送至負載平衡器 IP 位址時，系統才會在回應中新增後端 bucket 層級設定的自訂回應標頭。如果用戶端直接向 Cloud Storage API 發出要求，系統不會在回應中加入自訂標頭。

搭配 Google Cloud Armor 使用自訂標頭

設定 Google Cloud Armor 安全性政策時，您可以設定 Google Cloud Armor 插入自訂標頭和值。如果 Google Cloud Armor 安全性政策設定插入的自訂標頭名稱，與全域外部應用程式負載平衡器或傳統版應用程式負載平衡器的自訂標頭相同，則 Google Cloud Armor 安全性政策中指定的標頭值會遭到負載平衡器填入的值覆寫。如不想覆寫 Google Cloud Armor 政策，請勿使用相同名稱。

限制

搭配使用自訂標頭與全域負載平衡器時，有以下限制：

每個後端服務的所有自訂要求標頭加總起來的大小 (變數代換前名稱和值的總和) 不能超過 8KB 或 16 個要求標頭。
每個後端服務的所有自訂回應標頭加總起來的大小 (變數代換前名稱和值的總和) 不得超過 8 KB 或 16 個回應標頭。

後續步驟

如需使用案例範例，請參閱「設定具備外部後端的負載平衡器」。

在後端服務中建立自訂標頭 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

自訂標頭的運作方式

標頭值支援的變數

雙向傳輸層安全標準 (TLS) 自訂標頭

設定自訂要求標頭

主控台

gcloud

API

Terraform

設定自訂回應標頭

主控台

gcloud

API

Terraform

設定 Cloud Storage 的回應標頭

搭配 Google Cloud Armor 使用自訂標頭

限制

後續步驟

在後端服務中建立自訂標頭