使用插件或标注配置扩展程序时，您可以指定要转发到扩展程序服务的请求和连接属性。本页面介绍了支持的属性，并指出了每种扩展程序类型可用的属性。
通过将扩展程序配置为转发特定属性，您可以实现以下目标：
- 做出动态路由决策。
- 使用客户端信息丰富请求标头。
- 根据客户端位置或 TLS 参数实施自定义安全政策。
- 生成详细的自定义日志。
您可以在插件和标注扩展程序的 YAML 配置中使用 forwardAttributes 字段指定属性。例如，对于流量扩展，请参阅配置流量扩展。
为以下类型的扩展程序指定具有 forwardAttributes 的属性：
- 全球外部应用负载均衡器上的 Cloud Load Balancing 边缘扩展程序 (
LbEdgeExtension) - 应用负载均衡器上的 Cloud Load Balancing 路由和流量扩展程序（
LbRouteExtension、LbTrafficExtension） - 在应用负载均衡器上使用
ext_proc的授权扩展 (AuthzExtension) - 媒体 CDN 边缘缓存服务上的媒体 CDN 边缘扩展程序 (
CdnEdgeExtension)
请求属性
您可以从请求中提取并转发以下属性：
| 属性 | 类型 | LbEdge |
LbRoute |
LbTraffic |
Authz |
CdnEdge |
说明和行为差异 |
|---|---|---|---|---|---|---|---|
request.method |
字符串 | ✓ | ✓ | ✓ | ✓ | ✓ | HTTP 请求方法，例如 GET 或 POST。 |
request.host |
字符串 | ✓ | ✓ | ✓ | ✓ | ✓ | 等同于 request.headers['host'] 的便捷方法。 |
request.path |
字符串 | ✓ | ✓ | ✓ | ✓ | ✓ | 所请求的 HTTP 网址路径。 |
request.query |
字符串 | ✓ | ✓ | ✓ | ✓ | ✓ | 采用 name1=value&name2=value2 格式的 HTTP 网址查询。 |
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 |
整数 | — | — | ✓ | ✓ | — | 共享 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 |
布尔值 | — | — | ✓ | ✓ | — | 如果客户端和负载均衡器之间的连接已加密（使用 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 |
字符串 | — | — | ✓ | — | — | JA3 TLS/SSL 指纹（如果客户端使用 HTTPS、HTTP/2 或 HTTP/3 进行连接）。 |
connection.tls_ja4_fingerprint |
字符串 | ✓ | — | ✓ | — | — | JA4 TLS/SSL 指纹（如果客户端使用 HTTPS、HTTP/2 或 HTTP/3 进行连接）。 |
connection.client_rtt_msec |
整数 | — | — | ✓ | ✓ | — | 客户端往返时间 (RTT)，以毫秒为单位。 |
connection.sha256_peer_certificate_digest |
字符串 | ✓ | — | ✓ | ✓ | — | 十六进制编码的 SHA-256 对等证书哈希。 |
connection.client_cert_present |
布尔值 | — | — | ✓ | ✓ | — | 如果客户端在 TLS 握手期间提供了证书，则值为 true；否则为 false。 |
connection.client_cert_chain_verified |
布尔值 | — | — | ✓ | ✓ | — | 如果根据配置的 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 连接的 Base64 编码客户端叶证书 (RFC 9440)。 |
connection.client_cert_chain |
字符串 | — | — | ✓ | ✓ | — | 采用 Base64 编码的客户端证书链，以英文逗号分隔，按标准 TLS 顺序排列，不包括叶证书 (RFC 9440)。 |
限制
属性可用性：并非所有属性都支持所有扩展程序类型。如需了解详情，请参阅本页中的表格。
必需配置：如需将属性发送到扩展程序，您必须在扩展程序配置的
forwardAttributes字段中明确列出这些属性。如果您未在此字段中列出某个属性，则负载均衡器或 Media CDN 不会将该特定属性转发到您的扩展程序。大小限制：您最多可以为单个扩展程序配置 16 个属性。
mTLS 属性：仅当您启用了 mTLS 且客户端出示了证书时，系统才会在传递给扩展程序的数据中填充客户端证书属性 (
connection.client_cert_*)。