使用外掛程式或回呼為 ext-proc 型後端服務設定擴充功能時，您可以指定要轉送至這些服務的要求和連線屬性。本頁面說明支援的屬性，並指定各類擴充功能可用的屬性。
設定擴充功能轉送特定屬性後，即可達成下列目標：
- 決定動態路徑。
- 在要求標頭中加入用戶端資訊。
- 根據用戶端位置或 TLS 參數實作自訂安全性政策。
- 產生詳細的自訂記錄。
您可以在外掛程式和註解擴充功能的 YAML 設定中，使用 forwardAttributes 欄位指定屬性。舉例來說，如要瞭解流量擴充功能，請參閱「設定流量擴充功能」。
使用區域應用程式負載平衡器上的 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 參數。 | 授權 |
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 標準所定義的分區衍生出來的。 |
Edge |
source.client_city |
發出要求的城市名稱，例如加州山景城。Mountain View這個變數沒有有效值的標準清單。
城市名稱可包含 US-ASCII 字母、數字、空格和下列字元：!#$%&'*+-.^_`|~。 |
Edge |
source.client_city_lat_long |
發出要求的城市經緯度，例如，以 37.386051,-122.083851
表示從山景城發出的要求。 |
Edge |
connection.client_encrypted |
如果用戶端與負載平衡器之間的連線已加密 (使用 HTTPS、HTTP/2 或 HTTP/3)，值為 true；否則為 false。 |
路況 |
connection.protocol |
用戶端與負載平衡器之間通訊所用的 HTTP 通訊協定。可以是 HTTP/1.0、HTTP/1.1、HTTP/2 或 HTTP/3。 |
路況 |
destination.ip |
用戶端連線的負載平衡器 IP 位址。
如果多個負載平衡器共用常見後端，這個值就很有用。這與 X-Forwarded-For 標頭中的最後一個 IP 位址相同。 |
路況 |
destination.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 設為空字串。 |
授權、流量 |