割り当てプロジェクトを設定する

このページでは、クライアントベースの API の割り当てプロジェクトを設定する方法について説明します。割り当てプロジェクトの概要、割り当て API の設定方法、割り当てプロジェクトの決定方法については、割り当てプロジェクトについてをご覧ください。

クライアントベースの API にリクエストを送信するときに、割り当てプロジェクトを特定できない場合、リクエストは失敗します。

割り当てプロジェクトは複数の方法で設定できます。プロジェクトは、次のオプションを確認することで検証されます。優先度の高い順に説明します。

環境またはリクエストに設定された割り当てプロジェクト。
API キーを使用してリクエストの認証情報を提供する場合は、API キーに関連付けられたプロジェクトが割り当てプロジェクトとして使用されます。
Google Cloud CLI を使用してアクセストークンを取得し、ユーザー認証情報で gcloud CLI に対して認証を行っている場合は、gcloud CLI 共有プロジェクトが割り当てプロジェクトとして使用されることがあります。すべてのクライアントベースの API が共有プロジェクトにフォールバックするわけではありません。
API 呼び出しのプリンシパルがサービスアカウントの場合（権限借用などにより）、サービスアカウントに関連付けられたプロジェクトが割り当てプロジェクトとして使用されます。
API のプリンシパルが Workforce Identity 連携ユーザーの場合、Workforce プールのユーザープロジェクトが割り当てプロジェクトとして使用されます。

上記のいずれにも該当しない場合、リクエストは失敗します。

割り当てプロジェクトを設定するには、いくつかの方法があります。割り当てプロジェクトが複数の方法で指定されている場合は、次の優先順位が適用されます。

プログラム
環境変数
リクエストの認証に使用する認証情報

割り当てプロジェクトをプログラマティックに設定する

アプリケーションで割り当てプロジェクトを明示的に設定できます。この方法は、ほかのすべての定義をオーバーライドします。リクエストの認証に使用されるプリンシパルには、指定された割り当てプロジェクトに対して必要な権限が付与されている必要があります。

割り当てプロジェクトをプログラムで設定する方法は、クライアントライブラリ、gcloud CLI、REST リクエストのどれを使用するのかによって異なります。

クライアントライブラリ

割り当てプロジェクトの値は、クライアントの作成時にクライアントオプションを使用して設定できます。この方法は、実行環境に関係なく、アプリケーションから割り当てプロジェクトの値を制御する場合に適しています。

クライアントオプションの実装について詳しくは、クライアントライブラリのドキュメントをご覧ください。

gcloud CLI

gcloud CLI の構成で billing/quota_project プロパティを使用して、すべての gcloud CLI コマンドに割り当てプロジェクトを設定できます。--billing-project フラグを使用して、特定のコマンドに割り当てプロジェクトを設定することもできます。このフラグは、構成プロパティよりも優先されます。

gcloud CLI の構成の詳細については、gcloud 構成ファイルのリファレンスページをご覧ください。--billing-project フラグの詳細については、グローバルフラグのリファレンスをご覧ください。

REST リクエスト

x-goog-user-project ヘッダーを使用して、REST リクエストで割り当てプロジェクトを指定できます。リクエストを行うプリンシパルには、割り当てプロジェクトに対する必要な権限が付与されている必要があります。

詳細とサンプルコードについては、REST リクエストを使用して割り当てプロジェクトを設定するをご覧ください。

環境変数を使用して割り当てプロジェクトを設定する

一部の言語のクライアントライブラリでは、環境変数を使用した割り当てプロジェクトの設定がサポートされています。この方法は、シェルごとに異なる割り当てプロジェクトを設定する場合や、認証情報に関連付けられた割り当てプロジェクトをオーバーライドする場合に役立ちます。リクエストのプリンシパルには、環境変数で指定された割り当てプロジェクトに対して必要な権限が付与されている必要があります。

環境変数は言語に依存します。

言語	環境変数
C++	`GOOGLE_CLOUD_CPP_USER_PROJECT`
C#	`GOOGLE_CLOUD_QUOTA_PROJECT`
Go	`GOOGLE_CLOUD_QUOTA_PROJECT`
Java	`GOOGLE_CLOUD_QUOTA_PROJECT`
Node.js	`GOOGLE_CLOUD_QUOTA_PROJECT`
Python	`GOOGLE_CLOUD_QUOTA_PROJECT`
PHP	`GOOGLE_CLOUD_QUOTA_PROJECT`
Ruby	利用不可

認証情報を使用して割り当てプロジェクトを設定する

割り当てプロジェクトが指定されていない場合、認証ライブラリは、リクエストに使用された認証情報から割り当てプロジェクトの特定を試みます。このプロセスは、リクエストの認証に使用された認証情報の種類によって異なります。

サービスアカウント - サービスアカウントに関連付けられたプロジェクトが、割り当てプロジェクトとして使用されます。
ユーザー認証情報 - ローカル開発環境の場合、アプリケーションのデフォルト認証情報を使用して、ローカル ADC ファイルからユーザー認証情報を検索します。このファイルに割り当てプロジェクトを指定することもできます。Google Cloud CLI の構成ファイルでプロジェクトが設定され、そのプロジェクトに対して必要な権限がある場合は、ローカル ADC ファイルの作成時に割り当てプロジェクトがデフォルトで設定されます。auth application-default set-quota-project コマンドを使用して ADC 割り当てプロジェクトを設定することもできます。
API キー - API キーを使用してリクエストの認証情報を提供すると、その API キーに関連付けられたプロジェクトが割り当てプロジェクトとして使用されます。

割り当てプロジェクトの設定と使用に必要な権限

プロジェクトを割り当てプロジェクトとして設定するのに必要な権限を取得するか、またはリクエストでその割り当てプロジェクトを使用するには、プロジェクトに対する Service Usage ユーザー（roles/serviceusage.serviceUsageConsumer）IAM ロールを付与するよう管理者に依頼してください。ロールの付与の詳細については、アクセス権の管理をご覧ください。

この事前定義ロールには、 serviceusage.services.use 権限が含まれています。この権限は、プロジェクトを割り当てプロジェクトとして設定するか、リクエストでその割り当てプロジェクトを使用するために必要です。

カスタムロールや他の事前定義ロールを使用して、この権限を取得することもできます。

作成したプロジェクトを割り当てプロジェクトとして使用する場合は権限が必要です。

権限の詳細については、割り当ての権限をご覧ください。

割り当てユーザーを設定する

一部の API では、ユーザーごとのリクエスト数にも上限が設定されます。これは、このページの前のセクションで説明したプロジェクトごとの割り当てとは異なります。

デフォルトでは、システムは認証済みのプリンシパルを使用します。認証済みのプリンシパルが存在しない場合、システムはクライアントの IP アドレスを使用します。

割り当てユーザーをオーバーライドする必要がある場合は、Cloud API システムパラメータを使用して quotaUser パラメータを設定できます。quotaUser または X-Goog-Quota-User を指定する場合、IP アドレス制限のある有効な API キーを使用して、割り当てプロジェクトを識別する必要があります。それ以外の場合、quotaUser パラメータは無視されます。

Cloud API システムパラメータとそれらの定義の詳細については、システムパラメータの定義の表をご覧ください。

次のステップ

割り当てプロジェクトについて
アプリケーションのデフォルト認証情報について学習する
認証の詳細を確認する
割り当てについて学習する