システム パラメータ

Google の API プラットフォームでは、このプラットフォームを使用してビルドされたすべての Google API 対して一連の一般的な機能が提供されます。このような機能を使用して制御するために、プラットフォームでは、「システム パラメータ」と呼ばれる特別なパラメータ セットが事前に定義されています。これらのパラメータは、すべての Google REST API と gRPC API で使用できます。システム パラメータは、HTTP クエリ パラメータや HTTP ヘッダーを使用して指定できます。Google gRPC API では、HTTP ヘッダーのみがサポートされます。

ほとんどのユーザーはこれらのパラメータを使用する必要はありません。ただし、これらのパラメータは Google によって提供されるクライアント ライブラリによってよく使用されます。カスタムコードを作成して Google API に直接アクセスする必要がある場合、JSON 書式付き出力の制御や API キーの指定などで、システム パラメータが役立つことがあります。

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 ストリーム）です。
$.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 リクエストを行う理由が含まれており、この理由は監査ログに記録されます。理由の例としては、サポートケースのチケット番号が挙げられます。
$userProject X-Goog-User-Project 割り当てと課金を目的とした呼び出し元指定のプロジェクト。呼び出し元には、プロジェクトに対する serviceusage.services.use 権限が必要です。
X-Server-Timeout サーバーがリクエストの処理を完了するときのタイムアウト（秒単位、浮動小数点値）。このシステム パラメータは、クライアント側のタイムアウトが適用されない REST API にのみ適用されます。
x-goog-request-params gRPC リクエストの追加パラメータを URL クエリ形式で渡します。例: x-goog-request-params: service=pubsub.googleapis.com&release=2021-11-01r0

変更履歴

  • 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 システム パラメータを導入しました。