認証と認可

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

Google 広告のアクセスモデルについて

Google Ads API を効果的に使用するには、Google 広告のアクセスモデルの仕組みを理解する必要があります。Google 広告のアクセスモデルのガイドを読むことをおすすめします。

OAuth ワークフロー

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

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

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

Perl クライアント ライブラリでサービス アカウントを使用して独自の認証情報で API アクセス用に OAuth2 を設定する方法は次のとおりです。

  1. OAuth2 認証情報を作成します。

    手順に沿ってサービス アカウントと *.JSON ファイルを生成します。

  2. クライアント ライブラリを設定します。

    構成で秘密鍵の JSON パスを設定します。googleads.properties ファイルを使用している場合は、次のように追加します。

    jsonKeyFilePath=PRIVATE_KEY_FILE_PATH

    環境変数を使用している場合は、Bash 構成または環境に次の内容を追加します。

    export GOOGLE_ADS_JSON_KEY_FILE_PATH=PRIVATE_KEY_FILE_PATH

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

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

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

  1. Google 広告 API を使用して管理するすべてのアカウントへのアクセス権を 1 人のユーザーに付与します。一般的な方法としては、ユーザーに Google Ads API MCC アカウントへのアクセス権を付与し、その MCC アカウントの下にすべての Google 広告アカウントをリンクします。
  2. ユーザーが generate_user_credentials.pl コード例を実行して、ユーザーに代わってすべての Google 広告アカウントを管理する権限をアプリに付与します。

次の手順では、インタラクティブなコード例を実行します。このコード例では、入力の提供が必要になります。

  1. ターミナルで、examples ディレクトリの generate_user_credentials.pl の例を実行します。実行する前に例の INSERT_XXX_HERE 値を変更するか、クライアント ID に -client_id、クライアント シークレットに -client_secret のコマンドライン引数を使用できます。

    perl generate_user_credentials.pl -client_id {client_id} -client_secret {client_secret}

  2. このコード例では、URL にアクセスして、アプリがユーザーの代わりに Google 広告アカウントにアクセスすることを承認するよう求められます。

    Paste this url in your browser:
https://accounts.google.com/o/oauth2/v2/auth?response_type=code&access_type=offline&client_id=...

    プライベート ブラウザ セッションまたはシークレット ウィンドウで URL に移動します。Google 広告へのアクセスに使用している Google アカウントでログインします。通常、これは、管理する必要があるすべてのアカウントがアカウント階層に含まれている Google 広告クライアント センター（MCC）アカウントにアクセスできるメール アカウントです。OAuth 2.0 同意画面で [続行] をクリックします。

    OAuth 2.0 同意画面

    認証が成功したことを示すメッセージが表示されたページにリダイレクトされます。

    Authorization code was successfully retrieved.

  3. コード例を実行しているコンソールに戻ります。コード例が完了し、更新トークンといくつかの手順が表示されます。その後に、クライアント ライブラリを構成するために必要な手順が表示されます。

    Replace the following keys and values in your googleads.properties configuration file:

clientId==***********************apps.googleusercontent.com
clientSecret=****
refreshToken=****

  4. [Ctrl + C] を押してプロセスを終了します。生成された更新トークンとクライアント ID、クライアント シークレットを googleads.properties ファイルにコピーするか、ランタイムにライブラリをインスタンス化する場合に使用するために別の場所に保存します。

ライブラリは、googleads.properties で次の設定を行うことで、ユーザーの OAuth 2.0 認証情報を使用して初期化できます。

clientId=OAUTH_CLIENT_ID
clientSecret=OAUTH_CLIENT_SECRET
refreshToken=REFRESH_TOKEN
developerToken=DEVELOPER_TOKEN
loginCustomerId=LOGIN_CUSTOMER_ID

または、環境変数を使用します。

export GOOGLE_ADS_CLIENT_ID=OAUTH_CLIENT_ID
export GOOGLE_ADS_CLIENT_SECRET=OAUTH_CLIENT_SECRET
export GOOGLE_ADS_REFRESH_TOKEN=REFRESH_TOKEN
export GOOGLE_ADS_DEVELOPER_TOKEN=DEVELOPER_TOKEN
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

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

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

アプリでユーザーがログインし、ユーザーの代わりに Google 広告アカウントを管理する権限をアプリに付与できるようにする場合、このワークフローをおすすめします。アプリが OAuth 2.0 ユーザー認証情報をビルドして管理します。

Perl の場合、通常は、アプリケーションが OAuth 2.0 リダイレクトとトークン管理を処理するウェブ アプリケーション フローを実装します。ユーザーはアプリケーションを通じて認証を行い、アプリケーションはユーザーの更新トークンを保存して使用し、ユーザーに代わって API 呼び出しを行います。

取得した認証情報を使用するための構成は、シングル ユーザー認証フローの場合と同じです。

clientId=OAUTH_CLIENT_ID
clientSecret=OAUTH_CLIENT_SECRET
refreshToken=REFRESH_TOKEN
developerToken=DEVELOPER_TOKEN
loginCustomerId=LOGIN_CUSTOMER_ID

または、環境変数を使用します。

export GOOGLE_ADS_CLIENT_ID=OAUTH_CLIENT_ID
export GOOGLE_ADS_CLIENT_SECRET=OAUTH_CLIENT_SECRET
export GOOGLE_ADS_REFRESH_TOKEN=REFRESH_TOKEN
export GOOGLE_ADS_DEVELOPER_TOKEN=DEVELOPER_TOKEN
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

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

ユーザーが複数のアカウントを管理している場合はどうなりますか？

ユーザーがアカウントに直接アクセスするか、Google 広告クライアント センター（MCC）アカウントを介して、複数の Google 広告アカウントを管理することは一般的です。Perl クライアント ライブラリには、このようなケースを処理する方法を示す例が用意されています。

  1. get_account_hierarchy.pl の例では、Google 広告クライアント センター（MCC）アカウントに属するすべてのアカウントのリストを取得する方法を示します。
  2. list_accessible_customers.pl の例では、ユーザーが直接アクセスできるすべてのアカウントのリストを取得する方法を示します。これらのアカウントは、googleads.properties ファイルの LoginCustomerId 設定または GOOGLE_ADS_LOGIN_CUSTOMER_ID 環境変数の有効な値として使用できます。