支持的属性

通过插件或标注为基于 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	使用共享 VPC 时，向其转发请求的后端服务的项目编号。	授权、流量
request.mcp_param	MCP 参数。	授权
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 标准定义的下属行政单位派生而来。	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	由客户端在 TLS 或 QUIC 握手期间提供的服务器名称指示（如 RFC 6066 中所定义）。系统会将主机名转换为小写字母并移除结尾的任何英文句点。	授权、边缘、流量
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 加密套件注册系统定义的四位十六进制数字，例如表示 TLS_RSA_WITH_AES_128_GCM_SHA256 的 009C。对于 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	以逗号分隔的 URI 类型 SAN 扩展的 Base64 编码列表。SAN 扩展从客户端证书中提取。client_cert_uri_sans 字段中不包含 SPIFFE ID。如果 client_cert_uri_sans 长度超过 512 字节，则将 client_cert_error 设置为 client_cert_uri_sans_exceeded_size_limit，并将英文逗号分隔列表设置为空字符串。	授权、流量
connection.client_cert_dnsname_sans	以逗号分隔的 DNSName 类型 SAN 扩展的 Base64 编码列表。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	已建立的 mTLS 连接（客户端证书在其中通过了验证）的客户端证书链的英文逗号分隔证书列表（按标准 TLS 顺序排列），不包括叶证书。证书编码符合 RFC 9440 标准。如果 client_cert_leaf 和 client_cert_chain 的总大小在 Base64 编码之前超过 16 KB，则将字符串 client_cert_validated_chain_exceeded_size_limit 添加到 client_cert_error，并将 client_cert_chain 设置为空字符串。	授权、流量