Authentication

與其他 Google API 相同，Google Ads API 也使用 OAuth 2.0 通訊協定進行驗證及授權。OAuth 2.0 可讓 Google Ads API 用戶端應用程式存取使用者的 Google Ads 帳戶，不必處理或儲存使用者的登入資訊。

瞭解 Google Ads 存取模式

如要有效使用 Google Ads API，請先瞭解 Google Ads 存取模式的運作方式。請參閱 Google Ads 存取權模式指南。

OAuth 工作流程

使用 Google Ads API 時，通常會用到三種工作流程。

服務帳戶流程

如果工作流程不需要任何人為互動，建議採用這個工作流程。這項工作流程需要設定步驟，使用者必須將服務帳戶新增至 Google Ads 帳戶。應用程式隨後就能使用服務帳戶的憑證，管理使用者的 Google Ads 帳戶。

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();

如要瞭解詳情，請參閱服務帳戶工作流程指南。

單一使用者驗證流程

如果無法使用服務帳戶，可以採用這個工作流程。這項工作流程需要完成兩個設定步驟：

  1. 使用 Google Ads API 授權單一使用者存取所有要管理的帳戶。常見做法是授予使用者 Google Ads API 管理員帳戶的存取權，並連結該管理員帳戶下的所有 Google Ads 帳戶。
  2. 接著，該使用者會執行指令列工具 (例如 GenerateUserCredentials)，授權您的應用程式代表他們管理所有 Google Ads 帳戶。

您可以使用使用者的 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 Ads 帳戶，建議採用這個工作流程。應用程式會為每個已驗證的使用者工作階段，動態建構及管理 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 Ads 帳戶，可能是直接存取帳戶，也可能是透過 Google Ads 管理員帳戶。PHP 用戶端程式庫提供下列程式碼範例，說明如何處理這類情況：

  1. GetAccountHierarchy 程式碼範例說明如何擷取 Google Ads 管理員帳戶下的所有帳戶清單。
  2. ListAccessibleCustomers 程式碼範例說明如何擷取使用者可直接存取的所有帳戶清單。這些帳戶隨後可用於 loginCustomerId 設定的有效值。