支援的屬性

使用外掛程式或回呼為 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。	邊緣、流量 (僅適用於全域外部應用程式負載平衡器和區域性外部應用程式負載平衡器)
response.cdn_cache_id	用於處理要求的快取執行個體位置代碼和 ID。這個值與 Cloud CDN 要求記錄的 jsonPayload.cacheId 欄位中填入的值相同。	流量 (僅適用於全域外部應用程式負載平衡器)
response.cdn_cache_status	用於處理要求的快取執行個體目前狀態。這個屬性的可能值為 hit、miss、revalidated、stale、uncacheable 或 disabled。	流量 (僅適用於全域外部應用程式負載平衡器)
source.ip	用戶端的 IP 位址。	邊緣、路線、流量
source.port	用戶端的來源通訊埠。	邊緣、路線、流量
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 編碼清單，列出 URI 類型的 SAN 擴充功能。系統會從用戶端憑證擷取 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 編碼清單，列出 DNSName 類型的 SAN 擴充功能。系統會從用戶端憑證擷取 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 規範。如果 client_cert_leaf 和 client_cert_chain 在 Base64 編碼前的總大小超過 16 KB，系統會將 client_cert_validated_chain_exceeded_size_limit 字串加到 client_cert_error，並將 client_cert_chain 設為空字串。	授權、流量

限制

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

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

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

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