建立並連結 AdWords 和 Merchant Center 子帳戶

1. 簡介

在本程式碼研究室中,您將瞭解使用 Content API for ShoppingAdWords API 的基本概念,以及如何建立兩者都使用的應用程式。具體來說,您將建立指令列應用程式,以便建立並連結 AdWords 帳戶和 Merchant Center 帳戶。

課程內容

  • 如何建立由管理員帳戶管理的 AdWords 帳戶。
  • 如何建立由多重客戶帳戶管理的 Merchant Center 帳戶。
  • 如何向 Merchant Center 帳戶要求連結 AdWords 帳戶。
  • 如何在 AdWords 帳戶中接受待處理的 Merchant Center 連結。

軟硬體需求

2. 開始設定

下載影片

點選下方連結即可下載這個程式碼研究室的所有程式碼:

將下載的 ZIP 檔案解壓縮。這麼做會將根資料夾 (shopping-account-linking-master) 解壓縮,根資料夾含有 Maven 專案和所有必要資源。下列子目錄需特別注意:

  • src/main/java 是 Maven 專案的來源根,當中包含程式碼架構。
  • src/main/java/solution 包含已完成的解決方案。

安裝必要套件並建構

如果您使用 Maven 感知 IDE (例如 Eclipse 或 IntelliJ),可以將擷取的資料夾匯入為 Maven 專案,然後正常編譯專案。

如果您透過指令列使用 Maven,可以執行下列指令來擷取必要的套件,然後從解壓縮的專案的根資料夾 (shopping-account-linking-master) 編譯專案:

mvn compile

3. 設定驗證機制

在這個步驟中,我們不會執行任何程式碼,只是為了建立含有 AdWords API 和 Content API for Shopping 正確驗證權杖的檔案。

設定 AdWords API 驗證

本程式碼研究室採用的憑證載入方式與用戶端程式庫相同,因此如果您已透過管理員帳戶使用 Java 專用 Google Ads API 用戶端程式庫,應該就已經完成設定了。否則,請按照步驟 1 到 3 開始使用 Java 專用的 Google Ads API 用戶端程式庫。

設定 Content API 驗證

如果您還沒有服務帳戶金鑰:

  1. 前往 Merchant Center 管理多重客戶帳戶,然後從溢位選單中選取「Content API」89507d635c51a3dc.png
  2. 選取「Authentication」,然後按一下藍色的「+」按鈕:c465d8dc314ec158.png
  3. 接受《Google Cloud Platform 和 Google API 服務條款》後,瀏覽器就會自動下載內含新服務帳戶金鑰的 JSON 檔案。

接著,按照操作說明為使用服務帳戶的購物範例設定驗證機制。也就是說,服務帳戶金鑰副本應位於主目錄的以下路徑:shopping-samples/content/service-account.json。您不需要設定範例設定,除非您想在完成本程式碼研究室後試用範例!

測試

現在您已在正確的位置取得驗證權杖,請嘗試執行範例。如果您在指令列使用 Maven,請執行下列指令:

mvn compile
mvn exec:java -Dexec.mainClass="SolutionRunner"

如果收到有關工作階段物件的錯誤訊息,表示驗證權杖已就緒,可正常運作!否則,系統會顯示錯誤訊息,指出哪些憑證無法運作和修正的檔案。

4. 連結至 API

您現已取得我們目前要使用的兩個 API 的有效驗證權杖,接著讓我們開始填寫實際的程式碼。我們會先使用我們的驗證權杖建立工作階段物件。在後續步驟中,我們會存取各個 API 透過這些工作階段物件提供的各種服務及方法。

建立 Content API 工作階段物件

如要建立 Content API 工作階段,我們會建構 ShoppingContent.Builder 物件,然後使用該物件建構適當的 ShoppingContent 物件。幸好,程式碼架構中已提供建構前者所需的資源,因此只需像下方這樣一起提取即可:

SolutionRunner.java

// TODO(sessions): Create a ShoppingContent object using ShoppingContent.Builder.
contentApiSession =
    new ShoppingContent.Builder(httpTransport, jsonFactory, contentApiCredential)
        .setApplicationName("Linking AdWords and Merchant Center Accounts Codelab")
        .build();

您不一定要設定應用程式名稱,但會示範如何在呼叫 build() 方法之前,透過 ShoppingContent.Builder 物件設定任何所需選項。

建立 AdWords API 工作階段物件

同樣地,有一個用於建構 AdWordsSession 物件的 AdWordsSession.Builder 類別。主要的差別在於,我們會使用 fromFile() 方法,從先前步驟中設定的 ads.properties 檔案載入設定選項,而不是直接在建構工具上設定設定選項。

SolutionRunner.java

// TODO(sessions): Create a AdWordsSession object using AdWordsSession.Builder.
adWordsSession =
    new AdWordsSession.Builder()
        .fromFile()
        .withOAuth2Credential(adwordsOAuth2Credential)
        .build();

測試

如果您是透過指令列執行 Maven 專案,我們會使用上一節的相同指令來重建及執行 Maven 專案:

mvn compile
mvn exec:java -Dexec.mainClass="SolutionRunner"

此時應該不會有任何錯誤,不過您也無法取得有趣的輸出內容。並在呼叫 API 時新增此項目,以建立並連結新帳戶。

5. 建立新的 AdWords 客戶帳戶

我們已建立 API 工作階段物件,接下來我們會逐步完成並建立要連結的帳戶。我們先從 AdWords 著手,在管理員帳戶下建立測試帳戶。

存取 ManagedCustomerService

在 AdWords API 中,我們先使用靜態 getInstance() 方法擷取 AdWordsServices 類別的例項,以便存取各種可用的服務。接下來,我們就能透過 get() 方法為這些服務建立用戶端,該方法會使用兩個引數:用於建立用戶端的工作階段,以及所需服務的介面。

SolutionRunner.java

// TODO(newAWaccount): Using the ManagedCustomerService, create a new testing AdWords account
// under the given manager account.

AdWordsServicesInterface adWordsServices = AdWordsServices.getInstance();

ManagedCustomerServiceInterface managedCustomerService =
    adWordsServices.get(adWordsSession, ManagedCustomerServiceInterface.class);

這裡則是 ManagedCustomerService,用來管理 AdWords 的「客戶」即可。

指定新的帳戶設定

首先,我們會建立 ManagedCustomer 物件,其中包含新帳戶的設定。我們會為本程式碼研究室建立測試帳戶,並將幣別設為美金,時區則設為美國西部相同。

SolutionRunner.java

Random rand = new Random();
long run = rand.nextLong();

ManagedCustomer newAdWordsAccount = new ManagedCustomer();
newAdWordsAccount.setName(String.format("AdWords Account Created by Run %d", run));
newAdWordsAccount.setTestAccount(true);
newAdWordsAccount.setCurrencyCode("USD");
newAdWordsAccount.setDateTimeZone("America/Los_Angeles");

我們也會建立一組隨機號碼,其中包含在帳戶名稱中。這有助於我們將 AdWords 帳戶對應至稍後建立的 Merchant Center 帳戶,以便在解決方案完成後目視檢查項目,並確認帳戶確實連結至帳戶。

建立新的客戶帳戶

如要實際建立新帳戶,請使用 ManagedCustomerOperation 指定 ADD 作業:

SolutionRunner.java

ManagedCustomerOperation operation = new ManagedCustomerOperation();
operation.setOperand(newAdWordsAccount);
operation.setOperator(Operator.ADD);

接著,我們會使用 ManagedCustomerService 物件的 mutate() 方法執行這項作業。此方法會使用一系列作業,但這裡我們只需執行單一作業。mutate() 方法的結果是包含 ManagedCustomer 清單的值;這裡將列出一個客戶,也就是剛剛建立的新帳戶我們會擷取新帳戶的 ID 供日後使用,我們也會印出這個 ID,以便在解決方案的輸出結果中看見。

SolutionRunner.java

ManagedCustomerReturnValue result =
    managedCustomerService.mutate(new ManagedCustomerOperation[] {operation});
Long adWordsId = result.getValue()[0].getCustomerId();
System.out.printf("Created new AdWords account %d%n", adWordsId);

測試

和先前一樣,嘗試執行解決方案。如果您透過指令列使用 Maven:

mvn compile
mvn exec:java -Dexec.mainClass="SolutionRunner"

如果一切順利,您應該還是沒看到任何錯誤,而這次我們會列出我們新建的 AdWords 帳戶 ID。請前往 AdWords 網站查看您的管理員帳戶,這裡應該也會列出新帳戶!

6. 建立新的 Merchant Center 子帳戶

在這個步驟中,我們會建立 Merchant Center 子帳戶,並將帳戶連結至我們在上一個步驟中建立的 AdWords 帳戶。建立子帳戶後,我們可以提出連結要求,而不用另外要求連結,因為我們已經有對應 AdWords 帳戶的 ID。

指定新子帳戶的設定

與 AdWords API 不同,Account 模型類別的 setter 會傳回物件,以便我們在新的 Account 物件上鏈結對其的呼叫。我們也會使用您在建立 AdWords 帳戶期間產生的隨機數字,做為新的 Merchant Center 帳戶名稱。

SolutionRunner.java

Account newMcAccount = new Account()
    .setName(String.format("Merchant Center Account Created by Run %d", run))
    .setAdwordsLinks(
        ImmutableList.of(
            new AccountAdwordsLink()
                .setAdwordsId(BigInteger.valueOf(adWordsId))
                .setStatus("active")));

如這個步驟簡介所述,由於我們已擁有新客戶帳戶的 AdWords ID,因此我們可以立即將這個 ID 加入新子帳戶的 AdwordsLinks 清單中。建立新的子帳戶後,系統會自動要求這個連結,並在 AdWords API 中提供。

建立新的子帳戶

在 Content API 中,我們會呼叫工作階段物件的 accounts() 方法以存取 Accounts 服務,然後直接呼叫 insert() 方法,而不是設定作業物件。這個方法使用兩個引數:建立新子帳戶的多重客戶帳戶 ID,以及包含所需設定的 Account 物件:

SolutionRunner.java

newMcAccount = contentApiSession.accounts().insert(mcaId, newMcAccount).execute();

System.out.printf("Created new Merchant Center account %s%n", newMcAccount.getId());

insert() 方法會傳回 Account 物件,其中包含新子帳戶的設定。我們覆寫了原始的 Account 物件,因為傳回的版本包含重要的資訊:新子帳戶的 ID。我們會將這項資訊印出解決方案的輸出內容,以便執行解決方案,然後驗證 Merchant Center 中是否有新的子帳戶。

測試

和先前一樣,嘗試執行解決方案。如果您透過指令列使用 Maven:

mvn compile
mvn exec:java -Dexec.mainClass="SolutionRunner"

如果一切順利,您應該應該不會再看到任何錯誤,而這次我們會同時看到新 AdWords 帳戶和新 Merchant Center 帳戶的 ID。前往 Merchant Center 找出所需的多重客戶帳戶,在其中查看新的子帳戶。

7. 接受 AdWords 帳戶中的連結

在最後一個步驟中,我們建立了新的 Merchant Center 子帳戶,並要求一併連結新的 AdWords 帳戶。在這個步驟中,我們會使用 AdWords API 接受要求的連結,以便完成整個程序。

存取 CustomerService

和先前一樣,我們會使用 AdWordsServices 類別取得 CustomerService 的用戶端。不過,在建立客戶帳戶前,我們會先變更 AdWords 工作階段物件,以便日後使用新的客戶帳戶 (而非管理員帳戶) 進行操作。畢竟,Merchant Center 帳戶已要求連結至受管理帳戶,而「不是」管理員帳戶。

SolutionRunner.java

// TODO(acceptLink): Using the mutateServiceLinks method in CustomerService, accept the
// proposed link between the new AdWords account and the new Merchant Center account.

adWordsSession.setClientCustomerId(adWordsId.toString());

CustomerServiceInterface customerService =
    adWordsServices.get(adWordsSession, CustomerServiceInterface.class);

就像建立新的 AdWords 帳戶時,我們會建立包含連結設定的 ServiceLink 物件,然後建立用來描述所需操作的 ServiceLinkOperation 物件。在此,我們要將待處理服務連結至 MERCHANT_CENTER 帳戶,並將該連結 SETACTIVE。針對 serviceLinkId 設定,我們會使用剛剛建立的 Merchant Center 帳戶 ID,就像在 AdWords 中服務連結的 ID。

SolutionRunner.java

ServiceLink serviceLink = new ServiceLink();
serviceLink.setServiceLinkId(newMcAccount.getId().longValue());
serviceLink.setLinkStatus(ServiceLinkLinkStatus.ACTIVE);
serviceLink.setServiceType(ServiceType.MERCHANT_CENTER);

ServiceLinkOperation op = new ServiceLinkOperation();
op.setOperator(Operator.SET);
op.setOperand(serviceLink);

最後,我們會呼叫 CustomerService 物件的 mutateServiceLinks() 方法來執行作業。和之前一樣,您需要執行服務連結作業的陣列。這次,這個方法會直接傳回服務連結清單 (可能已變更),因此我們直接循環顯示解決方案的結果。當然,由於我們僅指定一項作業,因此您預期輸出結果中只會顯示一個連結。

SolutionRunner.java

ServiceLink[] mutatedServiceLinks =
    customerService.mutateServiceLinks(new ServiceLinkOperation[] {op});
for (ServiceLink mutatedServiceLink : mutatedServiceLinks) {
  System.out.printf(
      "Service link with service link ID %d, type '%s' updated to status: %s.%n",
      mutatedServiceLink.getServiceLinkId(),
      mutatedServiceLink.getServiceType(),
      mutatedServiceLink.getLinkStatus());
}

測試

和先前一樣,嘗試執行解決方案。如果您透過指令列使用 Maven:

mvn compile
mvn exec:java -Dexec.mainClass="SolutionRunner"

如果一切順利,系統應該不會再顯示任何錯誤,而且這次我們還會看到注意,服務連結已更新為有效。檢查 AdWordsMerchant Center,並再次確認帳戶是否確實連結。

8. 主題變化版本

恭喜您完成本程式碼研究室的課程!現在您已擁有完善的解決方案,接下來請看看如何修改或擴充解決方案,以使用您在本程式碼研究室中看到的更多 API。

在本程式碼研究室中,我們先是巧妙地建立 AdWords 帳戶,方便我們在建立 Merchant Center 帳戶時使用該資訊來要求連結。但如果已有 Merchant Center 帳戶,請改為更新帳戶設定。請嘗試修改程式碼來建立 Merchant Center 帳戶,然後再建立 AdWords 帳戶並更新其設定,以要求連結。

目前,應用程式只會將 API 呼叫中缺少錯誤視為成功的跡象。嘗試延伸範例,檢查新的 Merchant Center 和 AdWords 帳戶連結資訊,看看連結是否確實有效。

成為你的舞台

如果您認為還有什麼改變,可以試試看!如需提案參考程式碼,請查看 Google Ads Java 用戶端程式庫原始碼中的 Google 購物範例examples 目錄。