支援的屬性

使用外掛程式或呼叫設定擴充功能時，您可以指定要轉送至擴充功能服務的要求和連線屬性。本頁面說明支援的屬性，並指出每種擴充功能類型可用的屬性。

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

  • 動態決定對話流程。
  • 在要求標頭中加入用戶端資訊。
  • 根據用戶端位置或 TLS 參數，實施自訂安全性政策。
  • 產生詳細的自訂記錄。

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

請使用 forwardAttributes 為下列類型的擴充功能指定屬性：

  • 全域外部應用程式負載平衡器的 Cloud Load Balancing 邊緣擴充功能 (LbEdgeExtension)
  • 應用程式負載平衡器的 Cloud Load Balancing 路由和流量擴充功能 (LbRouteExtension、LbTrafficExtension)
  • 在應用程式負載平衡器上使用 ext_proc 的授權擴充功能 (AuthzExtension)
  • Media CDN Edge Cache 服務的 Media CDN 邊緣擴充功能 (CdnEdgeExtension)

要求屬性

您可以從要求中擷取及轉送下列屬性：

屬性 類型 LbEdge LbRoute LbTraffic Authz CdnEdge 說明和行為差異
request.method 字串 ✓ ✓ ✓ ✓ ✓ HTTP 要求方法，例如 GET 或 POST。
request.host 字串 ✓ ✓ ✓ ✓ ✓ 功用相當於 request.headers['host']。
request.path 字串 ✓ ✓ ✓ ✓ ✓ 要求的 HTTP 網址路徑。
request.query 字串 ✓ ✓ ✓ ✓ ✓ HTTP 網址查詢，格式為 name1=value&name2=value2。
request.scheme 字串 ✓ ✓ ✓ ✓ ✓ HTTP 網址配置 (http 或 https)。值須為小寫。
request.origin 字串 — — ✓ ✓ — 跨源資源共享 (CORS) 用途的 Origin 要求標頭值。
request.user_agent_family 字串 ✓ — ✓ — — 剖析後的使用者代理程式系列字串。僅適用於全域外部應用程式負載平衡器。
request.device_request_type 字串 ✓ — ✓ — — 裝置分類類別。僅適用於全域外部應用程式負載平衡器。
request.backend_service_name 字串 — — ✓ ✓ — 目標後端服務。不適用於邊緣擴充功能 (LbEdgeExtension 或 CdnEdgeExtension)。
request.backend_service_project_number 整數 — — ✓ ✓ — Shared VPC 中後端服務的專案編號。不適用於 Edge 擴充功能。
request.mcp_method 字串 — — — ✓ — Model Context Protocol (MCP) 方法名稱。

連線屬性

您可以從連線中擷取及轉送下列屬性：

屬性 類型 LbEdge LbRoute LbTraffic Authz CdnEdge 說明和行為差異
source.ip 字串 ✓ ✓ ✓ ✓ — 用戶端 IP 位址。
source.port 整數 ✓ ✓ ✓ ✓ ✓ 用戶端來源通訊埠號碼。
source.client_region 字串 ✓ — ✓ — ✓ 與用戶端 IP 位址相關聯的雙字母 ISO-3166-1 或 CLDR 區域代碼 (例如 US 或 DE)。
source.client_region_subdivision 字串 ✓ — ✓ — — 區域細分代碼，例如州或省。 僅適用於全域外部應用程式負載平衡器。
source.client_city 字串 ✓ — ✓ — — 與用戶端 IP 位址相關聯的城市。僅適用於全域外部應用程式負載平衡器。
source.client_city_lat_long 字串 ✓ — ✓ — — 與用戶端城市相關聯的經緯度。 僅適用於全域外部應用程式負載平衡器。
destination.ip 字串 — — ✓ ✓ — 用戶端連線的負載平衡器 IP 位址。
destination.port 整數 — — ✓ ✓ — 用戶端連線的目的地通訊埠編號。
connection.client_encrypted bool — — ✓ ✓ — 如果用戶端和負載平衡器之間的連線已加密 (使用 HTTPS、HTTP/2 或 HTTP/3)，則值為 true，否則為 false。
connection.protocol 字串 — — ✓ ✓ — 用於通訊的 HTTP 通訊協定 (HTTP/1.0、HTTP/1.1、HTTP/2 或 HTTP/3)。
connection.sni 字串 ✓ — ✓ ✓ ✓ 下游 TLS 連線要求的伺服器名稱指示 (SNI)。
connection.tls_version 字串 ✓ — ✓ ✓ ✓ 與用戶端協商的 TLS 版本 (TLSv1、TLSv1.1、TLSv1.2、TLSv1.3 或 QUIC)。
connection.tls_cipher_suite 字串 — — ✓ ✓ — TLS 握手期間協商的四位數十六進位加密套件，例如 009C。
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_rtt_msec 整數 — — ✓ ✓ — 用戶端封包往返時間 (RTT)，以毫秒為單位。
connection.sha256_peer_certificate_digest 字串 ✓ — ✓ ✓ — 十六進位編碼的 SHA-256 對等互連憑證雜湊。
connection.client_cert_present bool — — ✓ ✓ — 如果用戶端在 TLS 握手期間提供憑證，則值為 true，否則為 false。
connection.client_cert_chain_verified bool — — ✓ ✓ — 如果用戶端憑證鏈結已根據設定的 TrustStore 進行驗證，則值為 true；否則為 false。
connection.client_cert_error 字串 — — ✓ ✓ — 代表 mTLS 錯誤狀況的預先定義字串。詳情請參閱「mTLS 用戶端驗證模式」。
connection.client_cert_serial_number 字串 — — ✓ ✓ — 用戶端憑證的序號。
connection.client_cert_spiffe_id 字串 — — ✓ ✓ — 主體別名 (SAN) 欄位中的 SPIFFE ID。
connection.client_cert_uri_sans 字串 — — ✓ ✓ — 從用戶端憑證擷取的 URI SAN 擴充功能清單，以半形逗號分隔並採用 Base64 編碼。
connection.client_cert_dnsname_sans 字串 — — ✓ ✓ — 從用戶端憑證擷取的 DNSName SAN 擴充功能清單，以半形逗號分隔並採用 Base64 編碼。
connection.client_cert_valid_not_before 字串 — — ✓ ✓ — 用戶端憑證生效前的時間戳記 (RFC 3339 格式)。
connection.client_cert_valid_not_after 字串 — — ✓ ✓ — 用戶端憑證失效的時間戳記 (RFC 3339 格式)。
connection.client_cert_issuer_dn 字串 — — ✓ ✓ — 憑證 Issuer 欄位的 Base64 編碼 DER 編碼。
connection.client_cert_subject_dn 字串 — — ✓ ✓ — 憑證 Subject 欄位的 Base64 編碼 DER 編碼。
connection.client_cert_leaf 字串 — — ✓ ✓ — 已建立並驗證的 mTLS 連線 (RFC 9440) 的 Base64 編碼用戶端分葉憑證。
connection.client_cert_chain 字串 — — ✓ ✓ — 以逗號分隔、採用 Base64 編碼的用戶端憑證鏈結，依標準 TLS 順序排列，不含分葉憑證 (RFC 9440)。

限制

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

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

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

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