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

1. 簡介

在本程式碼研究室中，您將學習如何使用 Content API for Shopping 和 AdWords API 的基礎知識，並建構同時使用這兩種 API 的應用程式。具體來說，您將建構指令列應用程式，用於建立及連結 AdWords 帳戶和 Merchant Center 帳戶。

課程內容

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

軟硬體需求

• AdWords 管理員帳戶
• Merchant Center 多重客戶帳戶
• Java 7 以上
• Maven
• 程式碼範例
• 文字編輯器 (建議使用可解讀 Maven 專案的 IDE，例如 Eclipse 或 IntelliJ)

2. 開始設定

下載 code

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

下載原始碼

將下載的 ZIP 檔案解壓縮。這會解壓縮根資料夾 (shopping-account-linking-master)，其中包含 Maven 專案和您需要的所有資源。請特別注意下列子目錄：

• src/main/java 是 Maven 專案的原始根目錄，其中包含可供您使用的程式碼架構。
• src/main/java/solution 包含完成的解決方案。

安裝必要套件並進行建構

如果您使用 Eclipse 或 IntelliJ 等支援 Maven 的 IDE，可以將已解壓縮的資料夾匯入為 Maven 專案，然後正常編譯專案。

如果您是透過指令列使用 Maven，可以執行下列指令來擷取必要的套件，並從已解壓縮專案的根目錄 (shopping-account-linking-master) 編譯專案：

mvn compile

3. 設定驗證方法

在這個步驟中，我們不會撰寫任何程式碼，而是設定檔案，其中包含適當的驗證權杖，用於 AdWords API 和 Google 購物 Content API。

設定 AdWords API 驗證

這個程式碼研究室與用戶端程式庫使用相同的憑證載入方式，因此如果您已使用管理員帳戶搭配 Google Ads API Java 用戶端程式庫，則應已完成設定。否則，請按照步驟 1 至 3 開始使用適用於 Java 的 Google Ads API 用戶端程式庫。

設定 Content API 認證

如果您還沒有服務帳戶金鑰，請按照下列步驟操作：

1. 前往多重客戶帳戶的 Merchant Center，然後從溢出選單中選取「Content API」：
2. 選取「驗證」，然後按一下藍色「+」按鈕：
3. 接受 Google Cloud Platform 和 Google API 服務條款後，瀏覽器會自動下載含有新服務帳戶金鑰的 JSON 檔案。

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

測試

驗證權杖已放置在正確的位置，現在請嘗試執行範例。如果您在指令列中使用 Maven，請執行下列指令：

mvn compile

注意：如果您變更 src/main/resources 中的任何檔案，即使您未進行任何程式碼變更 (如本步驟所述)，也請在執行範例前重新編譯，將變更的資源複製到目標。

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

如果您收到有關未提供工作階段物件的錯誤訊息，表示驗證權杖已就位並正常運作！否則，系統會在錯誤訊息中指出哪些憑證無法運作，以及要修正哪些檔案。

重要事項：我們提供的架構假設您的 Content API 服務帳戶只會在多用戶帳戶中列為使用者。如果您收到錯誤訊息，指出您的服務帳戶可存取多個帳戶，請按照上述步驟取得專屬於多重客戶帳戶的服務帳戶金鑰。

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

注意：本程式碼範例中的初始註解已存在於程式碼架構中。請查看這些標記，瞭解應在何處加入這些行。

我們也省略了在這些程式碼片段中使用的 AdWords API 和 Content API 類別所需的任何匯入陳述式。如果您使用的 IDE 無法自動新增正確的匯入項目，請檢查 solution 套件中的程式碼，找出所需的匯入項目。

設定應用程式名稱並非必要，但這會說明如何在呼叫 build() 方法前，透過 ShoppingContent.Builder 物件設定所需的任何選項。

建立 AdWords API 工作階段物件

同樣地，也有一個 AdWordsSession.Builder 類別可用來建構 AdWordsSession 物件。這裡的主要差異在於，我們不會直接在建構工具上設定設定選項，而是會使用 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 開始，並在管理員帳戶下建立測試帳戶。

注意：本節中的所有程式碼片段會依照所列順序，新增至骨架程式碼中的相同位置。因此，我們只會顯示註解 (// TODO...))，標示在第一個註解中的位置。因此，在本步驟和後續步驟中，如果您看到沒有說明性註解的程式碼片段，請將這些片段放在前一個片段的後面。

存取 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，讓我們在解決方案的輸出內容中看到該 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 網站查看管理員帳戶，您應該會在該處看到新帳戶！

注意：此時，每次執行解決方案都會產生新的帳戶。執行解決方案後，您可以透過 AdWords 網站取消任何已建立的 AdWords 帳戶。畢竟，我們為這些帳戶建立的命名慣例，可讓您輕鬆查看哪些帳戶是由程式碼建立的！

6. 建立新的 Merchant Center 子帳戶

在這個步驟中，我們會建立 Merchant Center 子帳戶，並連結至上一個步驟中建立的 Google Ads 帳戶。我們已取得對應 AdWords 帳戶的 ID，因此可以直接在建立子帳戶時要求連結，而不需要在建立後另外提出要求。

指定新子帳戶的設定

與 AdWords API 不同，Account 模型類別的 setter 會傳回物件，因此我們可以在新的 Account 物件上連結對這些物件的呼叫。我們也會使用在建立 Google Ads 帳戶時產生的隨機號碼，做為新 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，即可看到新的子帳戶。

注意：與 AdWords 一樣，現在每次執行解決方案都會產生新的 Merchant Center 帳戶。執行完解決方案後，您可以透過 Merchant Center 刪除任何已建立的子帳戶。

7. 接受來自 AdWords 帳戶的連結

在最後一個步驟中，我們建立了新的 Merchant Center 子帳戶，並同時要求連結至新的 Google Ads 帳戶。在這個步驟中，我們會使用 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 帳戶，並將其SET至 ACTIVE。針對 serviceLinkId 設定，我們會使用剛建立的 Merchant Center 帳戶 ID，因為這會用於 Google Ads 中的服務連結 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"

如果一切順利，您應該還是不會看到任何錯誤，而且這次我們也會看到服務連結已更新為有效的連結。檢查 AdWords 和 Merchant Center，確認帳戶已連結。

8. 主題變化版本

恭喜您完成程式碼研究室！您現在已擁有完整運作的解決方案，接下來我們將舉例說明如何修改或擴充該解決方案，以便使用本程式碼研究室中介紹的更多 API。

加分題：更新現有的 Merchant Center 帳戶，要求連結 AdWords

在程式碼研究室中，我們先巧妙地建立 AdWords 帳戶，這樣在建立 Merchant Center 帳戶時，就能使用該帳戶的資訊來要求連結。不過，如果 Merchant Center 帳戶已存在，則必須改為更新其設定。請嘗試修改程式碼，先建立 Merchant Center 帳戶，然後在建立 AdWords 帳戶後返回，並更新其設定來要求連結。

注意：您可以使用 Accounts.update 或 Accounts.patch 方法。事實上，您可以試試各個版本，瞭解兩者的差異！

重要事項：呼叫 Accounts.insert 後，可能無法立即使用新的 Merchant Center 帳戶。在新的帳戶啟用前，您嘗試存取或修改帳戶時，系統會顯示 401 HTTP 錯誤。購物範例包含使用指數輪詢來重試 AccountWorkflow.java 中方法的範例，該方法會使用 BaseWorkflowSample.java 中的 retryFailures 方法。

額外獎勵：擷取 AdWords 和 Merchant Center 帳戶資訊，驗證連結建立作業

目前，應用程式只會將 API 呼叫沒有錯誤視為成功的徵兆。請嘗試擴充範例，檢查新 Merchant Center 和 AdWords 帳戶的連結資訊，確認連結確實有效。

注意：在 Content API 方面，您需要查看 Accounts.get 方法。在 AdWords 端，您需要使用 CustomerServiceInterface 物件的 getServiceLinks 方法。

世界就是你的寶藏

如果您想到其他可行的變更，歡迎嘗試看看！如果您需要參考程式碼來發想構想，請參閱 Google 購物範例和 Google Ads Java 用戶端程式庫來源中的 examples 目錄。