Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

認証と承認

他の Google API と同様に、Google Ads API は認証と認可に OAuth 2.0 プロトコルを使用します。OAuth 2.0 を使用すると、Google 広告 API クライアントアプリは、ユーザーのログイン情報を処理または保存することなく、ユーザーの Google 広告アカウントにアクセスできます。

このガイドでは、3 つの最も一般的な OAuth 2.0 フローを使用して Google Ads API 認証用の Java クライアントライブラリを構成する方法と、必要な認証情報について説明します。

Google Ads API のアクセスモデルの詳細については、Google Ads アクセスモデルガイドをご覧ください。

認証情報

Google Ads API にアクセスするには、OAuth 2.0 認証情報と、場合によってはログイン顧客 ID が必要です。

OAuth 2.0 認証情報

Google 広告アカウントにアクセスできる Google アカウントユーザーとして認可するには、OAuth 2.0 認証情報のセットを指定する必要があります。必要な認証情報のタイプは、使用する OAuth 2.0 フローによって異なります。

このライブラリは、次の 3 つのフローをサポートしています。

サービスアカウントのフロー
シングルユーザー認証フロー
マルチユーザー認証フロー

Google Ads API の OAuth フローの詳細については、OAuth の概要を参照してください。必要な認証情報を取得するには、ニーズに最適なフローの手順に沿って操作してください。

必要に応じて、広告配信中アカウントへのアクセス権を付与するクライアントセンター（MCC）アカウントの顧客 ID を指定します。顧客アカウントへのアクセスが MCC アカウント経由である場合は、これを指定する必要があります。顧客 ID へのパスで、すべてのクライアントセンター（MCC）アカウントを指定する必要はありません。アクセス権限に使用している最上位の MCC ID のみを指定します。詳細については、関連ドキュメントをご覧ください。

クライアントライブラリでは、ログインするお客様 ID は ads.properties ファイルの api.googleads.loginCustomerId キーで指定します。

構成

クライアントライブラリは、ads.properties ファイル、環境変数、またはプログラムで構成できます。このガイドでは、ads.properties ファイルの使用に焦点を当てます。すべてのオプションの詳細については、構成ガイドをご覧ください。

ads.properties ファイルを使用する場合は、ホームディレクトリ ~/ads.properties に配置します。

OAuth ワークフロー

Google Ads API を使用する際に使用される一般的なワークフローは 3 つあります。

サービスアカウントのフロー

ワークフローでユーザーの操作が必要ない場合は、このワークフローをおすすめします。このワークフローでは、ユーザーがサービスアカウントを Google 広告アカウントに追加する構成手順が必要です。アプリは、サービスアカウントの認証情報を使用して、ユーザーの Google 広告アカウントを管理できます。

秘密鍵の JSON ファイルを入手したら、ads.properties ファイルに次の内容を追加します。

api.googleads.serviceAccountSecretsPath=INSERT_PATH_TO_JSON_HERE
# Only add this key if you are using Google Workspace domain-wide delegation
# to impersonate a user who has access to the Google Ads account.
# api.googleads.serviceAccountUser=USER_EMAIL_TO_IMPERSONATE

詳細については、サービスアカウントのワークフローガイドをご覧ください。

シングルユーザー認証フロー

このワークフローは、サービスアカウントを使用できない場合に使用できます。このワークフローには、次の 2 つの構成手順が必要です。

Google Ads API を使用して管理するすべてのアカウントへのアクセス権を 1 人のユーザーに付与します。一般的な方法としては、Google Ads API の MCC アカウントへのアクセス権をユーザーに付与し、その MCC アカウントにすべての対象 Google 広告アカウントをリンクします。
ユーザーが gcloud CLI や GenerateUserCredentials コード例などのコマンドラインツールを実行して、ユーザーに代わってすべての Google 広告アカウントを管理する権限をアプリに付与します。

認証情報を取得したら、ads.properties ファイルに次の内容を追加します。

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE

詳しくは、シングルユーザー認証のワークフローガイドを参照してください。

マルチユーザー認証フロー

アプリでユーザーがログインし、アプリがユーザーの代わりに Google 広告アカウントを管理することを承認できるようにする場合は、このワークフローをおすすめします。GenerateUserCredentials コード例は、実行時にユーザー認証を取得して、ユーザーに代わって Google 広告アカウントを管理する方法を示すコマンドラインツールです。このコード例は、ユーザー認証を必要とするデスクトップアプリやウェブアプリを構築する際の参考として使用できます。

マルチユーザーアプリケーションの場合は、アプリケーションの OAuth 2.0 クライアント ID とクライアントシークレットを ads.properties（または別の構成ストア）に保存し、各エンドユーザーの更新トークンをアプリケーションデータベースに安全に保存して、UserCredentials と GoogleAdsClient をビルドするときに実行時にプログラムで渡します。

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE

詳しくは、マルチユーザー認証のワークフローガイドを参照してください。

複数のアカウントを管理する

ユーザーが複数の Google 広告アカウントを管理することはよくあります。アカウントに直接アクセスする場合もあれば、Google 広告クライアントセンター（MCC）アカウントを使用する場合もあります。Java クライアントライブラリには、このようなケースの処理方法を示す次のコード例が用意されています。

GetAccountHierarchy コード例は、Google 広告 MCC アカウントのすべてのアカウントのリストを取得する方法を示しています。
ListAccessibleCustomers コード例は、ユーザーが直接アクセスできるすべてのアカウントのリストを取得する方法を示しています。これらのアカウントは、loginCustomerId 設定の有効な値として使用できます。

アプリケーションのデフォルト認証情報

Java クライアントライブラリは、アプリケーションのデフォルト認証情報を使用した認証もサポートしています。

これは、必要な OAuth 2.0 スコープにアクセスできる同じ認証情報を再利用できるため、ローカル開発やさまざまな Google API に対する開発に特に便利です。

Google Ads API の場合は、アプリケーションのデフォルト認証情報が https://www.googleapis.com/auth/adwords OAuth 2.0 スコープにアクセスできることを確認してください。

アプリケーションのデフォルト認証情報を使用するには、ads.properties ファイルで api.googleads.useApplicationDefaultCredentials オプションを true に設定します（または、GoogleAdsClient.newBuilder() で .enableApplicationDefaultCredentials() を呼び出します）。アプリケーションのデフォルト認証情報を使用する場合、クライアント ID、クライアントシークレット、更新トークンは設定しないでください。