支援的屬性

使用外掛程式或回呼為以 ext-proc 為基礎的後端服務設定擴充功能時，您可以指定要轉送至這些服務的要求和連線屬性。本頁面說明支援的屬性，並指定各類擴充功能可用的屬性。

設定擴充功能轉送特定屬性後，即可達成下列目標：

• 做出動態路徑決策。
• 在要求標頭中加入用戶端資訊。
• 根據用戶端位置或 TLS 參數實作自訂安全性政策。
• 產生詳細的自訂記錄。

您可以在外掛程式和摘要額外資訊的 YAML 設定中，使用 forwardAttributes 欄位指定屬性。舉例來說，如要瞭解流量擴充功能，請參閱「設定流量擴充功能」。

授權、邊緣、路徑和流量擴充功能支援使用 forwardAttributes 指定屬性。您可以在下列產品上，使用 Wasm 外掛程式或呼出 (搭配 ext_proc 通訊協定) 實作 forwardAttributes：

• 區域性外部應用程式負載平衡器
• 區域性內部應用程式負載平衡器
• 全域外部應用程式負載平衡器
• 跨區域內部應用程式負載平衡器

下表列出支援的屬性和擴充功能：

屬性	說明	擴充功能
request.origin	跨源資源共享 (CORS) 用途的請求中，來源標頭的值。	流量
request.method	HTTP 要求方法，例如 GET 或 POST。	授權、邊緣、路徑、流量
request.mcp_method	HTTP 要求方法，例如 GET 或 POST。	授權
request.host	相當於 request.headers['host'] 的便利性。	授權、邊緣、路徑、流量
request.path	要求的 HTTP 網址路徑。	授權、邊緣、路徑、流量
request.query	HTTP 網址查詢，格式為 name1=value&name2=value2，如 HTTP 要求的首行所示。未執行解碼作業。	授權、邊緣、路徑、流量
request.scheme	HTTP 網址配置，例如 HTTP 或 HTTPS。這項屬性的值為小寫。	授權、邊緣、路徑、流量
request.backend_service_name	要求預計轉送到的後端服務。	授權、流量
request.backend_service_project_number	使用 Shared VPC 時，要求預計轉送到的後端服務專案數量。	授權、流量
request.mcp_param	MCP 參數。	授權
request.user_agent_family	用戶端瀏覽器類型，衍生自 User-Agent 標頭值。這些值是指傳入的 HTTP 用戶端 (例如網路瀏覽器、行動應用程式或自動化工具) 在標準 HTTP User-Agent 要求標頭中傳送的原始文字字串。	邊緣、流量 (僅適用於全域外部應用程式負載平衡器和區域性外部應用程式負載平衡器)
request.device_request_type	用戶端的裝置類型。這個屬性的可能值為 APPLE、APPLEWEBKIT、BLACKBERRY、DOCOMO、GECKO、GOOGLE、KHTML、KOREAN、MICROSOFT、MSIE、NETFRONT、NOKIA、OBIGO、OPERA、OPENWAVE、OTHER、POLARIS、SEMC、SMIT、TELECA 或 USER_DEFINED。	邊緣、流量 (僅適用於全域外部應用程式負載平衡器和區域外部應用程式負載平衡器)
request.header_order	用戶端要求中 HTTP 標頭的順序，以半形逗號分隔的標頭名稱字串表示，例如 host,accept,cookie。這項屬性支援下列標頭：accept、accept-charset、accept-encoding、accept-language、connection、content-length、content-type、cookie、host、if-modified-since、ping-from、ping-to、pragma、referer、user-agent、via 和 x-forwarded-for。	流量 (僅適用於全域外部應用程式負載平衡器)
response.cdn_cache_id	用於處理要求的快取執行個體位置代碼和 ID。這個值與 Cloud CDN 要求記錄的 jsonPayload.cacheId 欄位中填入的值相同。	流量 (僅適用於全域外部應用程式負載平衡器)
response.cdn_cache_status	用於處理要求的快取執行個體目前狀態。這個屬性的可能值為 hit、miss、revalidated、stale、uncacheable 或 disabled。	流量 (僅適用於全域外部應用程式負載平衡器)
source.ip	用戶端的 IP 位址。	edge、route、traffic
source.port	用戶端的來源通訊埠。	edge、route、traffic
source.client_region	與用戶端 IP 位址相關聯的國家/地區。 值為 Unicode CLDR 區域代碼，例如 US 或 FR。在大多數國家/地區，這些代碼會直接對應至 ISO-3166-2 代碼。	邊緣、流量 (僅適用於全域外部應用程式負載平衡器和區域性外部應用程式負載平衡器)
source.client_region_subdivision	與用戶端 IP 位址相關聯的國家/地區的細分區域 (例如省或州)。這是 Unicode CLDR 細分 ID，例如 USCA 或 CAON。這些 Unicode 代碼是根據 ISO-3166-2 標準定義的細分區域而來。	邊緣、流量 (僅適用於全域外部應用程式負載平衡器)
source.client_city	發出要求的城市名稱。例如Mountain View加州山景城。這個變數沒有標準的有效值清單。 城市名稱可包含 US-ASCII 字母、數字、空格和下列字元：!#$%&'*+-.^_`|~.	邊緣、流量 (僅適用於全域外部應用程式負載平衡器)
source.client_city_lat_long	要求來源城市的經緯度，例如山景城的要求為 37.386051,-122.083851。	邊緣、流量 (僅適用於全域外部應用程式負載平衡器)
connection.client_encrypted	如果用戶端與負載平衡器之間的連線已加密 (使用 HTTPS、HTTP/2 或 HTTP/3)，值為 true；否則為 false。	流量
connection.client_rtt_msec	負載平衡器與 HTTP(S) 用戶端之間的預估往返傳輸時間 (以毫秒為單位)。這是負載平衡器 TCP 堆疊測量的平滑封包往返時間 (SRTT) 參數 (如 RFC 2988 所定義)。	流量 (僅適用於全域外部應用程式負載平衡器)
connection.client_protocol	用戶端與負載平衡器之間通訊所用的 HTTP 通訊協定。可以是 HTTP/1.0、HTTP/1.1、HTTP/2 或 HTTP/3。	流量
connection.server_ip_address	用戶端連線的負載平衡器 IP 位址。 如果多個負載平衡器共用常見後端，這個值就很有用。這與 X-Forwarded-For 標頭中的最後一個 IP 位址相同。	流量
connection.server_port	用戶端連線的目標通訊埠編號。	流量
connection.sni	伺服器名稱指示 (如 RFC 6066 所定義)，如果用戶端在 TLS 或 QUIC 握手期間提供。主機名稱會轉換為小寫，並移除任何尾隨的點。	授權、邊緣、流量
connection.tls_version	用戶端與負載平衡器在 SSL 握手期間交涉的 TLS 版本。可能的值包括：TLSv1、TLSv1.1、TLSv1.2 和 TLSv1.3。如果用戶端使用 QUIC (而非 TLS) 連線，這個值為 QUIC。	邊緣、流量
connection.sha256_peer_certificate_digest	下游 TLS 連線中對等互連憑證的十六進位編碼 SHA256 雜湊 (如有)。	授權、邊緣、流量
connection.tls_cipher_suite	TLS 握手期間交涉的加密套件。這個值是 IANA TLS 加密套件登錄檔定義的四位數十六進位數字，例如 009C 代表 TLS_RSA_WITH_AES_128_GCM_SHA256。如果是 QUIC 和未加密的用戶端連線，這個值會是空白。	流量
connection.tls_ja3_fingerprint	如果用戶端使用 HTTPS、HTTP/2 或 HTTP/3 連線，則為 JA3 TLS/SSL 指紋。	流量
connection.tls_ja4_fingerprint	如果用戶端使用 HTTPS、HTTP/2 或 HTTP/3 連線，系統會提供 JA4 TLS/SSL 指紋。	邊緣、流量
connection.client_cert_present	如果用戶端在 TLS 握手期間提供憑證，值為 true；否則為 false。	授權、流量
connection.client_cert_chain_verified	如果系統已根據設定的 TrustStore 驗證用戶端憑證鏈結，值為 true；否則為 false。	授權、流量
connection.client_cert_error	代表錯誤情況的預先定義字串。如要進一步瞭解錯誤字串，請參閱「mTLS 用戶端驗證模式」。	授權、流量
connection.client_cert_serial_number	用戶端憑證的序號。如果序號長度超過 50 個位元組，client_cert_error 會設為 client_cert_serial_number_exceeded_size_limit，序號則會設為空白字串。	授權、流量
connection.client_cert_spiffe_id	主體別名 (SAN) 欄位中的 SPIFFE ID。如果值無效或超過 2048 個位元組，SPIFFE ID 會設為空白字串。如果 SPIFFE ID 長度超過 2048 個位元組，client_cert_error 會設為 client_cert_spiffe_id_exceeded_size_limit。	授權、流量
connection.client_cert_uri_sans	以半形逗號分隔，並採用 Base64 編碼的 SAN 擴充功能清單，類型為 URI。系統會從用戶端憑證擷取 SAN 擴充功能。SPIFFE ID 不會包含在 client_cert_uri_sans 欄位中。如果 client_cert_uri_sans 長度超過 512 個位元組，client_cert_error 會設為 client_cert_uri_sans_exceeded_size_limit，而以半形逗號分隔的清單會設為空字串。	授權、流量
connection.client_cert_dnsname_sans	以半形逗號分隔，並採用 Base64 編碼的 SAN 擴充功能清單，類型為 DNSName。系統會從用戶端憑證擷取 SAN 擴充功能。如果 client_cert_dnsname_sans 長度超過 512 個位元組，client_cert_error 會設為 client_cert_dnsname_sans_exceeded_size_limit，而以半形逗號分隔的清單會設為空字串。	授權、流量
connection.client_cert_valid_not_before	時間戳記 (RFC 3339 日期字串格式)，指出用戶端憑證失效的時間，例如 2022-07-01T18:05:09+00:00。	授權、流量
connection.client_cert_valid_not_after	用戶端憑證失效的時間戳記 (採用 RFC 3339 日期字串格式)，例如 2022-07-01T18:05:09+00:00。	授權、流量
connection.client_cert_issuer_dn	憑證中完整 Issuer 欄位的 Base64 編碼 DER 編碼。如果 client_cert_issuer_dn 長度超過 512 個位元組，系統會將字串 client_cert_issuer_dn_exceeded_size_limit 新增至 client_cert_error，並將 client_cert_issuer_dn 設為空字串。	授權、流量
connection.client_cert_subject_dn	憑證中完整 Subject 欄位的 Base64 編碼 DER 編碼。如果 client_cert_subject_dn 長度超過 512 個位元組，系統會將字串 client_cert_subject_dn_exceeded_size_limit 新增至 client_cert_error，並將 client_cert_subject_dn 設為空字串。	授權、流量
connection.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 設為空白字串。	授權、流量
connection.client_cert_chain	以半形逗號分隔的憑證清單 (採用標準 TLS 順序)，適用於已建立的 mTLS 連線，且用戶端憑證已通過驗證，但不包括葉子憑證。憑證編碼符合 RFC 9440 規定。如果 Base64 編碼前 client_cert_leaf 和 client_cert_chain 的合併大小超過 16 KB，系統會將 client_cert_validated_chain_exceeded_size_limit 字串新增至 client_cert_error，並將 client_cert_chain 設為空字串。	授權、流量

限制

• 屬性適用情形：並非所有屬性都支援所有類型的擴充功能。詳情請參閱本頁的表格。

• 必要設定：如要將屬性傳送至擴充功能，您必須在擴充功能設定的 forwardAttributes 欄位中，明確列出這些屬性。如果未在這個欄位中列出屬性，負載平衡器就不會將該特定屬性轉送至擴充功能。

• 大小限制：單一擴充功能最多可設定 16 個屬性。

• mTLS 屬性：只有在啟用 mTLS 且用戶端提供憑證時，系統才會在傳遞至擴充功能的資料中填入用戶端憑證屬性 (connection.client_cert_*)。