Authentication

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

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

Google Ads API を効果的に使用するには、Google Ads のアクセスモデルの仕組みを理解する必要があります。Google 広告アクセスモデル ガイドを参照してください。

OAuth ワークフロー

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

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

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

PHP ライブラリは次のように構成できます。

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withJsonKeyFilePath('INSERT_PATH_TO_JSON_KEY_FILE_HERE')
    // Optional in v32.1.0 and later (defaults to
    // 'https://www.googleapis.com/auth/adwords').
    ->withScopes('https://www.googleapis.com/auth/adwords')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

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

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

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

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

ライブラリは、ユーザーの OAuth 2.0 認証情報を使用して次のように初期化できます。

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withClientId('INSERT_CLIENT_ID_HERE')
    ->withClientSecret('INSERT_CLIENT_SECRET_HERE')
    ->withRefreshToken('INSERT_REFRESH_TOKEN_HERE')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->withLoginCustomerId('INSERT_LOGIN_CUSTOMER_ID_HERE')
    ->build();

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

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

これは、ユーザーがログインして、アプリがユーザーの代わりに Google 広告アカウントを管理することを承認できるアプリにおすすめのワークフローです。アプリは、認証されたユーザー セッションごとに OAuth 2.0 ユーザー認証情報を動的に構築して管理します。ライブラリは、ログインしたユーザーの認証情報を使用して次のように初期化できます。

// Construct credentials dynamically per authenticated user session.
$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withClientId('INSERT_CLIENT_ID_HERE')
    ->withClientSecret('INSERT_CLIENT_SECRET_HERE')
    ->withRefreshToken($userRefreshToken)
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->withLoginCustomerId($userLoginCustomerId)
    ->build();

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

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

PHP クライアント ライブラリは、アプリケーションのデフォルト認証情報（ADC）を使用した認証もサポートしています。OAuth2TokenBuilder にアプリケーション モード（clientId、clientSecret、refreshToken）とサービス アカウント モード（jsonKeyFilePath）の認証情報が設定されていない場合、build() を呼び出すと、自動的にアプリケーションのデフォルト認証情報にフォールバックします。

$oAuth2Credential = (new OAuth2TokenBuilder())->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->withLoginCustomerId('INSERT_LOGIN_CUSTOMER_ID_HERE')
    ->build();

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

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

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