驗證與授權

如同其他 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 帳戶。

以下說明如何在 Perl 用戶端程式庫中，使用服務帳戶和您自己的憑證設定 OAuth2，以存取 API：

  1. 建立 OAuth 2 憑證：

    按照操作說明產生服務帳戶和 *.JSON檔案。

  2. 設定用戶端程式庫：

    在設定中設定私密金鑰 JSON 路徑。如果您使用 googleads.properties 檔案，請新增下列程式碼：

    jsonKeyFilePath=PRIVATE_KEY_FILE_PATH

    如果您使用環境變數，請在 Bash 設定或環境中新增下列項目：

    export GOOGLE_ADS_JSON_KEY_FILE_PATH=PRIVATE_KEY_FILE_PATH

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

單一使用者驗證流程

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

  1. 授予單一使用者存取所有待管理帳戶的權限，以便透過 Google Ads API 管理這些帳戶。常見做法是授予使用者 Google Ads API 管理員帳戶的存取權，並連結該管理員帳戶下的所有 Google Ads 帳戶。
  2. 使用者執行generate_user_credentials.pl程式碼範例，授權應用程式代表他們管理所有 Google Ads 帳戶。

下列步驟會執行互動式程式碼範例，然後要求您提供輸入內容。

  1. 在終端機中，執行 examples 目錄中的 generate_user_credentials.pl 範例。您可以先修改範例中的 INSERT_XXX_HERE 值，再執行範例，也可以使用指令列引數 -client_id (用戶端 ID) 和 -client_secret (用戶端密碼)。

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

  2. 這個程式碼範例會提示您前往網址，授權應用程式代為存取 Google Ads 帳戶。

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

    在私密瀏覽工作階段或無痕視窗中前往該網址。 使用您用來存取 Google Ads 的 Google 帳戶登入。通常，這個電子郵件帳戶有權存取 Google Ads 管理員帳戶，其中包含您需要在帳戶階層中管理的所有帳戶。在 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 Ads 帳戶，建議採用這個工作流程。您的應用程式會建構及管理 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 Ads 帳戶，方法包括直接存取帳戶，或是透過 Google Ads 管理員帳戶存取。Perl 用戶端程式庫提供範例，說明如何處理這類情況。

  1. get_account_hierarchy.pl 範例顯示如何擷取 Google Ads 管理員帳戶下的所有帳戶清單。
  2. list_accessible_customers.pl 範例說明如何擷取使用者可直接存取的所有帳戶清單。然後，這些帳戶就能做為 googleads.properties 檔案中 LoginCustomerId 設定或 GOOGLE_ADS_LOGIN_CUSTOMER_ID 環境變數的有效值。