他の Google API と同様に、Google Ads API では、認証および承認に OAuth 2.0 プロトコルを使用しています。OAuth 2.0 を使うことで、Google Ads API クライアント アプリケーションは、ユーザーのログイン情報を保存したり処理したりしなくてもユーザーの Google 広告アカウントにアクセスできるようになります。
このガイドでは、最も一般的な 3 つの OAuth 2.0 フローを使用して Google Ads API 認証用に Java クライアント ライブラリを構成する方法と、必要な認証情報について説明します。
Google Ads API アクセス モデルの詳細については、Google 広告アクセス モデル ガイドをご覧ください。
認証情報
Google Ads API にアクセスするには、OAuth 2.0 認証情報が必要です。場合によっては、ログイン用のお客様 ID も必要になります。
OAuth 2.0 認証情報
Google 広告アカウントにアクセスできる Google アカウント ユーザーとして承認するには、OAuth 2.0 認証情報のセットを指定する必要があります。必要な認証情報の種類は、使用する OAuth 2.0 フローによって異なります。
ライブラリは次の 3 つのフローをサポートしています。
- サービス アカウント フロー
- シングルユーザー認証フロー
- マルチユーザー認証フロー
Google Ads API の OAuth フローの詳細については、OAuth の概要をご覧ください。必要な認証情報を取得するには、ニーズに最適なフローの手順に沿って操作してください。
ログイン用のお客様 ID
必要に応じて、広告配信中アカウントへのアクセス権を持つ 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=PRIVATE_KEY_JSON_FILE_PATH
# Only add this key if you are using impersonation to access an account
# other than the service account itself.
# 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 広告アカウントを管理するために、実行時にユーザー認証を取得する方法を示すコマンドライン コード サンプルです。このコードサンプルを参考にして、ユーザー認証を必要とするデスクトップ アプリを構築できます。
次のコードを ads.properties ファイルに追加します。
api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
詳細については、マルチユーザー認証のワークフロー ガイドを ご覧ください。
ユーザーが複数のアカウントを管理している場合はどうすればよいですか？
ユーザーが複数の Google 広告アカウントを管理していることはよくあります。アカウントに直接アクセスする場合と、Google 広告 MCC アカウント経由でアクセスする場合があります。Java クライアント ライブラリには、このようなケースを処理する方法を示す次のコードサンプルが用意されています。
- GetAccountHierarchy コードサンプルは、Google 広告 MCC アカウントの下にあるすべてのアカウントのリストを 取得する方法を示しています。
- ListAccessibleCustomers コードサンプルは、ユーザーが直接アクセスできるすべてのアカウントのリストを取得する方法を示しています。これらのアカウントは、
LoginCustomerId設定の有効な値として使用できます。
アプリケーションのデフォルト認証情報
Java クライアント ライブラリでは、アプリケーションのデフォルト 認証情報を使用した認証もサポートされています。
これは、ローカル開発や、さまざまな Google API に対する開発に特に便利です。正しい OAuth 2.0 スコープにアクセスできる場合は、同じ認証情報を再利用できます。
Google Ads API の場合、アプリケーションのデフォルト認証情報が https://www.googleapis.com/auth/adwords OAuth 2.0 スコープにアクセスできることを確認してください。
アプリケーションのデフォルト認証情報を使用するには、ads.properties ファイルで api.googleads.useApplicationDefaultCredentials オプションを true に設定します。アプリケーションのデフォルト認証情報を使用する場合、クライアント ID、クライアント シークレット、更新トークンは設定しないでください。