创建和关联 AdWords 子账号与 Merchant Center 子账号

1. 简介

在此 Codelab 中，您将学习使用 Content API for Shopping 和 AdWords API 的一些基础知识，并构建一个同时使用这两者的应用。具体来说，您将构建一个命令行应用，用于创建和关联 AdWords 账号和 Merchant Center 账号。

学习内容

• 如何创建由经理账号管理的 AdWords 账号。
• 如何创建由多客户账号管理的 Merchant Center 账号。
• 如何从 Merchant Center 账号向 AdWords 账号请求关联。
• 如何在 AdWords 账号中接受待处理的 Merchant Center 关联。

所需条件

• AdWords 经理账号
• 一个 Merchant Center 多客户账号
• Java 7 及更高版本
• Maven
• 示例代码
• 文本编辑器（建议使用了解 Maven 项目的 IDE，例如 Eclipse 或 IntelliJ）

2. 准备工作

下载代码

点击下面的链接可下载此 Codelab 的所有代码：

下载源代码

解压下载的 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 身份验证

此 Codelab 使用与客户端库相同的凭据加载方式，因此如果您已将 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 示例。也就是说，服务账号密钥的副本应位于主目录中的以下路径：shopping-samples/content/service-account.json。您无需设置示例配置，除非您有兴趣在完成本 Codelab 后试用这些示例！

开始测试

现在，您已将身份验证令牌放置在正确的位置，请尝试运行示例。如果您在命令行中使用 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 类的所有必需的 import 语句。如果您使用的 IDE 无法自动添加正确的导入，请检查 solution 软件包中的代码，了解所需的导入。

设置应用名称并非绝对必要，但它展示了如何在调用 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 项目（如果您是从命令行运行该项目）：

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 对象。在此 Codelab 中，我们将创建一个测试账号，并将其币种设置为美元，时区设置为与美国西海岸相同的时区。

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

我们还会创建一个随机数，并将其添加到账号名称中。这只是为了让我们能够将在此处创建的 Google Ads 账号与稍后创建的 Merchant Center 账号相关联，以便在解决方案完成后直观地检查这两个账号，并确保它们确实已关联。

创建新的受管理的账号

如需实际创建新账号，我们将使用 ManagedCustomerOperation 来指定 ADD 操作：

SolutionRunner.java

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

然后，我们将使用 ManagedCustomerService 对象的 mutate() 方法执行操作。此方法接受要执行的操作数组，但在此示例中，我们只想执行一项操作。mutate() 方法的结果是一个包含 ManagedCustomer 列表的值；在此示例中，该列表将包含一个客户，即我们创建的新账号。我们将检索该新账号的 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 子账号，并将其与我们在上一步中创建的 AdWords 账号相关联。我们无需在创建子账号后单独请求关联，而是可以在创建过程中请求关联，因为我们已经拥有相应 AdWords 账号的 ID。

指定新子账号的设置

与 AdWords API 不同，Account 模型类的 setter 会返回对象，因此我们可以对新的 Account 对象链接调用这些 setter。我们还会在新 Merchant Center 账号的名称中使用在创建 Google Ads 账号期间生成的随机数。

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 子账号，同时请求与新的 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 账号 SET 到 ACTIVE。对于 serviceLinkId 设置，我们将使用刚刚创建的 Merchant Center 账号的 ID，因为该 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. 主题变奏

恭喜您完成了此 Codelab！现在，您已经拥有一个完全可行的解决方案，接下来我们来看一些示例，了解如何修改或扩展该解决方案，以便使用您在此 Codelab 中看到的一些 API。

加分题：更新现有 Merchant Center 账号以请求关联 AdWords 账号

在 Codelab 中，我们巧妙地先创建了 Google Ads 账号，这样在创建 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 目录。