開始使用

建議您搭配使用 Apache Maven (或 Gradle) 與用戶端程式庫。

建立新的 Maven/Gradle 專案

在您選擇的 IDE 中建立新的 Maven/Gradle 專案。我們的構件會發布至 Maven 中央存放區

Maven 依附元件為:

<dependency>
  <groupId>com.google.api-ads</groupId>
  <artifactId>google-ads</artifactId>
  <version>38.0.0</version>
</dependency>

Gradle 依附元件為:

implementation 'com.google.api-ads:google-ads:38.0.0'

您也可以從來源建構。本指南假設您已設定專案,並提供必要的依附元件。

如果您是從來源建構,請務必在 IDE 中啟用註解處理。

取得憑證以向 API 進行驗證

如要存取 Google Ads API,必須具備 OAuth 憑證和 Google Ads API 開發人員符記。本節將說明這些項目是什麼、如何使用,以及如何取得。

開發人員權杖 (用於存取 API)

開發人員符記會連結至管理員帳戶,並顯示在 Google Ads 網頁介面中。

雖然開發人員符記會連結至管理員帳戶,但不會提供該帳戶的存取權。開發人員權杖授予的是一般 API 存取權,帳戶層級存取權則透過 OAuth 設定。

OAuth 憑證 (用於存取 Google Ads 帳戶)

如要以有權存取 Google Ads 帳戶的 Google 帳戶使用者身分授權,您必須提供一組 OAuth 憑證。

一般來說,有兩種 OAuth 流程:桌面 (已安裝) 應用程式或網頁應用程式。兩者的主要差異在於,桌面應用程式必須開啟系統瀏覽器,並提供本機重新導向 URI 來處理 Google 授權伺服器的回應,而網頁應用程式可以重新導向任意第三方瀏覽器來完成授權,並將憑證傳回伺服器。程式庫也支援較不常用的服務帳戶流程。

使用自己的憑證授權 (電腦應用程式流程)
請參閱 OAuth 電腦版應用程式流程。包括使用您自己的憑證授權時所需的所有詳細資料。
以第三方 Google 使用者身分授權 (網頁流程)
請參閱 OAuth 網頁應用程式流程。這個範例說明如何為任意第三方使用者設定 OAuth 授權。
如果您以 Google Apps 網域使用者身分授權 (服務帳戶流程)
請參閱 OAuth 服務帳戶流程。這個範例說明如何為 Google 應用程式網域使用者設定 OAuth 授權。

如果您的 Google Ads 客戶帳戶存取權是透過 Google Ads 管理員帳戶取得,您也必須指定登入客戶 ID,詳情請參閱下文。

登入客戶 ID (透過管理員帳戶存取 Google Ads 帳戶)

(選用) 指定可存取放送帳戶的管理員帳戶客戶 ID。如果透過管理員帳戶存取客戶帳戶,則必須指定這項資訊。您不必在客戶 ID 的路徑中指定所有管理員帳戶,只需指定用於存取權的頂層管理員 ID 即可。詳情請參閱相關說明文件

使用您的憑證設定用戶端程式庫

您可以透過設定檔、環境變數或以程式輔助方式設定用戶端程式庫。在本指南中,我們將使用設定檔方法,並著重於電腦和網頁流程。如果您只有一組憑證 (例如,您管理單一管理員下的帳戶),通常建議使用設定檔。

建立 ~/ads.properties 檔案,並加入以下內容:

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE

將預留位置替換為上個步驟中取得的憑證。

此外,如果您的重新整理權杖適用於管理員帳戶,請將該帳戶的客戶 ID 指定為登入客戶:

api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

驗證憑證

為確保所有設定皆正確無誤,我們會執行 GetCampaigns 範例

首先,請前往 google-ads-examples 目錄。

cd google-ads-examples

這個範例需要 --customerId 參數,值為不含破折號的 Google Ads 帳戶客戶 ID。

如要使用 Gradle 執行:

./gradlew -q runExample --example="basicoperations.GetCampaigns --customerId INSERT_CUSTOMER_ID_HERE"

查看其他範例

google-ads-examples 中的 examples 套件包含多個實用範例。大多數範例都需要參數。您可以將參數做為引數傳遞 (建議),或編輯原始碼中的 INSERT_XXXXX_HERE 值。如要查看使用聲明範例,請傳遞 --help 做為唯一引數。

使用 Gradle:

./gradlew -q runExample --example="basicoperations.GetCampaigns --help"

您也可以在 Gradle 中使用 listExamples 工作,列出所有範例、子目錄中的範例,或說明中包含搜尋字詞的範例。

# List all examples:
./gradlew -q listExamples
# List examples in the 'basicoperations' subdirectory:
./gradlew -q listExamples --subdirectory='basicoperations'
# Search for examples where the description includes 'Performance Max':
./gradlew -q listExamples --searchTerm='Performance Max'