ext-proc ベースのバックエンド サービスにプラグインまたはコールアウトを使用して拡張機能を構成する場合は、それらのサービスに転送するリクエスト属性と接続属性を指定できます。このページでは、サポートされている属性と、各拡張機能タイプで使用可能な属性について説明します。
特定の属性を転送するように拡張機能を構成すると、次のことが可能になります。
- 動的ルーティングの決定を行います。
- クライアント情報でリクエスト ヘッダーを拡充します。
- クライアントの場所または TLS パラメータに基づいてカスタム セキュリティ ポリシーを実装します。
- 詳細なカスタムログを生成します。
プラグイン拡張機能とコールアウト拡張機能の YAML 構成で forwardAttributes フィールドを使用して属性を指定できます。たとえば、トラフィック拡張機能については、トラフィック拡張機能を構成するをご覧ください。
forwardAttributes を使用した属性の指定は、認可、エッジ、ルート、トラフィックの拡張機能でサポートされています。forwardAttributes は、次のプロダクトで Wasm プラグインまたはコールアウト（ext_proc プロトコルを使用）を使用して実装できます。
- リージョン外部アプリケーション ロードバランサ
- リージョン内部アプリケーション ロードバランサ
- グローバル外部アプリケーション ロードバランサ
- クロスリージョン内部アプリケーション ロードバランサ
次の表に、サポートされている属性と拡張機能を示します。
| 属性 | 説明 | 拡張機能 |
|---|---|---|
request.origin |
クロスオリジン リソース シェアリング（CORS）のユースケースのリクエストに含まれる送信元ヘッダーの値。 | トラフィック |
request.method |
GET や POST などの HTTP リクエスト メソッド。 |
承認、エッジ、ルート、トラフィック |
request.mcp_method |
GET や POST などの HTTP リクエスト メソッド。 |
authorization |
request.host |
request.headers['host'] と同等の利便性。 |
承認、エッジ、ルート、トラフィック |
request.path |
リクエストした HTTP URL パス。 | 承認、エッジ、ルート、トラフィック |
request.query |
HTTP リクエストの 1 行目に現れるような、name1=value&name2=value2 形式の HTTP URL クエリ。デコードは行われません。 |
承認、エッジ、ルート、トラフィック |
request.scheme |
HTTP URL スキーム（HTTP、HTTPS など）。この属性の値はすべて小文字です。 |
承認、エッジ、ルート、トラフィック |
request.backend_service_name |
リクエストが転送されるバックエンド サービス。 | 認証、トラフィック |
request.backend_service_project_number |
共有 VPC を使用する場合の、リクエストが転送されるバックエンド サービスのプロジェクト番号。 | 認証、トラフィック |
request.mcp_param |
MCP パラメータ。 | authorization |
request.user_agent_family |
User-Agent ヘッダー値から取得されるクライアントのブラウザタイプ。これらの値は、受信 HTTP クライアント（ウェブブラウザ、モバイルアプリ、自動化ツールなど）が標準の HTTP User-Agent リクエスト ヘッダーで送信する未加工のテキスト文字列を指します。 |
edge、traffic（グローバル外部アプリケーション ロードバランサとリージョン外部アプリケーション ロードバランサの場合のみ） |
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 です。 |
edge、traffic（グローバル外部アプリケーション ロードバランサとリージョン外部アプリケーション ロードバランサの場合のみ） |
request.header_order |
クライアント リクエストの HTTP ヘッダーの順序。ヘッダー名のカンマ区切り文字列（例: host,accept,cookie）。この属性は、accept、accept-charset、accept-encoding、accept-language、connection、content-length、content-type、cookie、host、if-modified-since、ping-from、ping-to、pragma、referer、user-agent、via、x-forwarded-for の各ヘッダーをサポートしています。 |
トラフィック（グローバル外部アプリケーション ロードバランサの場合のみ） |
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 コードに直接対応しています。 |
edge、traffic（グローバル外部アプリケーション ロードバランサとリージョン外部アプリケーション ロードバランサの場合のみ） |
source.client_region_subdivision |
クライアントの IP アドレスに関連付けられる国の下位地域区分（都道府県や州など）。これは Unicode CLDR サブディビジョン ID です（USCA や CAON など）。この Unicode コードは、ISO-3166-2 標準で定義されている下位地域区分から派生しています。 |
edge、traffic（グローバル外部アプリケーション ロードバランサの場合のみ） |
source.client_city |
リクエスト送信元の市区町村の名前。たとえば、カリフォルニア州のマウンテン ビューは Mountain View です。この変数について有効な値の正規リストはありません。都市名には、US-ASCII 文字、数字、スペース、!#$%&'*+-.^_`|~ を含めることができます。 |
edge、traffic（グローバル外部アプリケーション ロードバランサの場合のみ） |
source.client_city_lat_long |
リクエスト送信元の都市の緯度と経度。たとえば、Mountain View からのリクエストの場合は 37.386051,-122.083851 です。 |
edge、traffic（グローバル外部アプリケーション ロードバランサの場合のみ） |
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 handshake 中にクライアントによって提供された場合）。ホスト名は小文字に変換され、末尾のドットはすべて削除されます。 | 認証、エッジ、トラフィック |
connection.tls_version |
SSL handshake 中にクライアントとロードバランサの間でネゴシエートされた TLS バージョン。有効な値は、TLSv1、TLSv1.1、TLSv1.2、TLSv1.3 などです。クライアントが TLS ではなく QUIC を使用して接続した場合、値は QUIC です。 |
edge、traffic |
connection.sha256_peer_certificate_digest |
ダウンストリーム TLS 接続内のピア証明書の 16 進数でエンコードされた SHA256 ハッシュ（存在する場合）。 | 認証、エッジ、トラフィック |
connection.tls_cipher_suite |
TLS handshake 中にネゴシエートされた暗号スイート。値は、IANA TLS Cipher Suite Registry で定義された 4 桁の 16 進数です。たとえば、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 フィンガープリント。 |
edge、traffic |
connection.client_cert_present |
TLS handshake 中にクライアントが証明書を提供した場合は 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。値が無効であるか、2, 048 バイトを超える場合、SPIFFE ID は空の文字列に設定されます。SPIFFE ID が 2, 048 バイトを超える場合、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 |
Base64 でエンコードされた証明書の完全な Issuer フィールドの 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 |
Base64 でエンコードされた証明書の完全な Subject フィールドの 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 に準拠しています。Base64 エンコード前の client_cert_leaf と client_cert_chain の合計サイズが 16 KB を超えると、文字列 client_cert_validated_chain_exceeded_size_limit が client_cert_error に追加され、client_cert_chain が空の文字列に設定されます。 |
認証、トラフィック |
制限事項
属性の利用可能性: すべての属性がすべての拡張機能タイプでサポートされているわけではありません。詳しくは、このページの表をご覧ください。
必須の構成: 属性を拡張機能に送信するには、拡張機能の構成の
forwardAttributesフィールドで属性を明示的にリストする必要があります。このフィールドに属性を指定しない場合、ロードバランサはその特定の属性を拡張機能に転送しません。サイズの上限: 1 つの拡張機能に最大 16 個の属性を構成できます。
mTLS 属性: mTLS を有効にしていて、クライアントが証明書を提示している場合にのみ、クライアント証明書属性（
connection.client_cert_*）が拡張機能に渡されるデータに設定されます。