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

1. 简介

在此 Codelab 中，您将学习使用 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
• 示例代码
• 文本编辑器（建议使用能够理解 Eclipse 或 IntelliJ 等 Maven 项目的 IDE）

2. 准备工作

下载 code

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

下载源代码

解压下载的 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 和 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. 选择 Authentication，然后点击蓝色的 + 按钮：
3. 接受 Google Cloud Platform 和 Google API 服务条款后，您的浏览器将自动下载包含新服务账号密钥的 JSON 文件。

现在，请按照使用服务账号为购物示例设置身份验证的说明进行操作。也就是说，您的服务账号密钥的副本应位于主目录的以下路径下：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.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 对象，其中包含新账号的设置。我们将为此 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");

我们还创建一个随机数字，将其包含在账号名称中。这样，我们就能将我们在这里创建的 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 网站上查看，您应该也会看到列出的新账号！

注意：此时，每次运行解决方案都会生成新账号。运行解决方案后，您可以通过 AdWords 网站取消创建的所有 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 中查看多客户账号，以查看新的子账号。

注意：与 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 将用作 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"

如果一切顺利，您应该仍然看不到任何错误，这一次，我们还会看到一条说明，说明服务链接已更新为有效。查看 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 账号和 Google Ads 账号的关联信息，看看关联是否确实有效。

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

随心所欲

如果您想到其他可以进行的更改，不妨试一试！如果您需要参考代码来实现自己的想法，请查看 Google 购物示例以及 Google Ads Java 客户端库源代码中的 examples 目录。