開始使用

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

建立新的 Maven/Gradle 專案

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

Maven 依附元件如下:

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

Gradle 依附元件如下:

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

您也可以從原始碼開始建構。以本指南說明,我們假設專案設定具有必要的依附元件。

取得透過 API 進行驗證的憑證

您必須具備 OAuth 憑證和 Google Ads API 開發人員權杖,才能存取 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 Apps 網域使用者設定 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

驗證憑證

為確保所有設定正確無誤,我們會執行 Get 廣告活動範例

首先,前往 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 中的範例套件包含幾個實用的範例。大部分範例都需要參數。您可以將參數做為引數傳遞 (建議做法),或是編輯原始碼中的 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'