システム パラメータ

Google の API プラットフォームは、API キー、レスポンス フィールド マスク、割り当ての帰属、JSON 形式など、REST API と gRPC API 全体で共通の機能を制御するシステム パラメータを定義します。 プロトコルに応じて、システム パラメータを URL クエリ パラメータまたは HTTP ヘッダーとしてサービスに渡します。 これらのパラメータは、カスタムコードを作成するときに直接指定できますが、 Google 提供の クライアント ライブラリなどのツールでは、多くの場合、 自動的に処理されます。

HTTP マッピング

HTTP リクエストの場合、システム パラメータは URL クエリ パラメータまたは HTTP リクエスト ヘッダーとして送信されます。たとえば、システム パラメータ $foo がある場合、URL で ?$foo=xxx として送信されます。URL エンコードされている場合は ?%24foo=xxx として送信されます。詳しくは、以下の表をご覧ください。

gRPC マッピング

gRPC リクエストの場合、システム パラメータは小文字のキーを持つ HTTP リクエスト ヘッダーとして送信されます。詳しくは、以下の表をご覧ください。

定義

次の表は、すべてのシステム パラメータとその定義を示しています。

URL クエリ パラメータ HTTP/gRPC ヘッダー 説明
Authorization 認証情報詳細については、認証の概要をご覧ください。
$alt、
alt		 レスポンスの代替形式。サポートされている値は json、media、proto、sse（JSON ストリーム）です。デフォルトは json です。
$apiVersion X-Goog-Api-Version 使用する API バージョン。すべての API がこのパラメータをサポートしているわけではありません。使用する前に API ドキュメントをご確認ください。
$.xgafv JSON エラーの形式。サポートされている値は 1、2（デフォルト）です。エラー形式 1 は、Google API クライアント ライブラリでのみ使用する必要があります。
$callback、
callback		 JSONP コールバック パラメータ。
$ct Content-Type HTTP Content-Type リクエスト ヘッダーのオーバーライド。
$fields、
fields		 X-Goog-FieldMask レスポンスのフィルタリングに使用される FieldMask。特に明記されている場合を除き、空の場合はすべてのフィールドが返されます。
X-HTTP-Method-Override リクエストの目的の HTTP メソッド。一部のネットワーク プロキシは、すべての HTTP メソッドを受け入れません。
$key、
key		 X-Goog-Api-Key Google API キーです。詳しくは、https://cloud.google.com/docs/authentication/api-keys をご覧ください。
passwd、
password		 ユーザーが URL でパスワードを入力しないように予約されています。
$prettyPrint、
prettyPrint		 JSON レスポンスを書式付きで出力します。サポートされている値は true（デフォルト）、false です。
quotaUser X-Goog-Quota-User ユーザーの割り当てごとに課金するための疑似ユーザー ID。指定しない場合は、認証済みのプリンシパルが使用されます。認証済みのプリンシパルが存在しない場合は、クライアントの IP アドレスが使用されます。指定すると、サービス制約がある有効な API キーを使用して、割り当てプロジェクトを識別する必要があります。それ以外の場合、このパラメータは無視されます。
$outputDefaults JSON レスポンスに対して proto のデフォルト値を強制的に出力します。
$unique リクエスト キャッシングを無効にするための一意のクエリ パラメータ。
X-Goog-Api-Client API クライアントの識別子。値は NAME "/" SEMVER 文字列のスペース区切りリストであり、NAME には小文字、数字、「-」のみが含まれ、SEMVER はセマンティック バージョン文字列である必要があります。たとえば、X-Goog-Api-Client: python/3.5.0 grpc-google-pubsub-v1/0.1.0-beta2 linux/2.7.0 です。
X-Goog-Request-Reason リクエストを行う理由が含まれており、この理由は監査ログに記録されます。理由の例としては、サポート ケースのチケット番号などがあります。監査ログの場合、理由の文字によって、ログエントリに添付される前に理由が base64 でエンコードされるかどうかが決まります。文字、数字、スペースのみを含む理由は、書式なしテキストで保持されます。他の文字を含む理由は base64 でエンコードされます。
$userProject X-Goog-User-Project 割り当てと課金を目的とした呼び出し元指定のプロジェクト。呼び出し元には、プロジェクトに対する serviceusage.services.use 権限が必要です。
X-Server-Timeout サーバーがリクエストの処理を完了するときのタイムアウト（秒単位、浮動小数点値）。このシステム パラメータは、クライアント側のタイムアウトが適用されない REST API にのみ適用されます。
x-goog-request-params gRPC リクエストに追加のパラメータを渡します。値は URL クエリ文字列でエンコードする必要があります（例: key1=value1&key2=value2）。

このヘッダー内でサポートされる特定のキーと値は、呼び出される個々の Google API サービスとメソッドによって異なります。このヘッダーのパラメータの単一のユニバーサル セットはありません。サポートされているパラメータまたは必須パラメータを確認するには、操作する特定の API のドキュメントを必ず参照してください。

一般的な用途は次のとおりです。
  • ルーティング情報: 地域化されたサービスの場合、このヘッダーには、GFE がリクエストを正しいリージョンのバックエンドにルーティングするのに役立つパラメータが含まれていることがよくあります。これには、リソース名の一部に一致するキー（name=projects/my-proj/locations/us-central1、parent=projects/my-proj/locations/us-central1 など）や、明示的なロケーション パラメータ（grpc-location=locations/us-central1 など）が含まれることがよくあります。
  • API 固有の機能: たとえば、BigQuery Storage Write API は、米国以外のマルチリージョン gRPC 呼び出しにこのヘッダー内の write_stream パラメータを使用します（例: x-goog-request-params: write_stream=projects/myproject/datasets/myds/tables/mytable/streams/mystream）。
例:
x-goog-request-params: name=projects/my-project/locations/us-central1&foo=bar

変更履歴

  • 2026-10: X-Goog-Api-Version のドキュメントを公開しました。
  • 2026-06: x-goog-request-params のドキュメントを更新しました。
  • 2021-11: x-goog-request-params のドキュメントを公開しました。
  • 2021-02: quotaUser のドキュメントを公開しました。
  • 2020-07: OAuth 2.0 クエリ パラメータを廃止しました。
  • 2019-10: X-Server-Timeout システム パラメータを導入しました。
  • 2017-10: X-Goog-User-Project システム パラメータを導入しました。