Como criar e vincular subcontas do Google AdWords e do Merchant Center

1. Introdução

Neste codelab, você vai aprender algumas noções básicas sobre como trabalhar com a API Content for Shopping e a API AdWords e criar um aplicativo que use as duas. Em especial, você desenvolverá um aplicativo de linha de comando que criará e vinculará uma conta do Google AdWords a uma conta do Merchant Center.

O que você vai aprender

• Como criar contas do Google AdWords gerenciadas por uma conta de administrador.
• Como criar contas do Merchant Center gerenciadas por uma conta de múltiplos clientes.
• Como solicitar a vinculação de uma conta do Merchant Center a uma do Google Ads.
• Como aceitar uma vinculação pendente do Merchant Center em uma conta do Google AdWords.

O que é necessário

• Uma conta de administrador do Google AdWords
• Uma conta de múltiplos clientes do Merchant Center
• Java 7 ou mais recente
• Maven
• Código de amostra
• Um editor de texto (é recomendado um ambiente de desenvolvimento integrado que entenda projetos do Maven, como Eclipse ou IntelliJ)

2. Etapas da configuração

Faça o download do código.

Clique no link abaixo para fazer o download de todo o código para este codelab:

Fazer o download do código-fonte

Descompacte o arquivo ZIP transferido por download. Isso vai descompactar uma pasta raiz (shopping-account-linking-master), que contém um projeto Maven com todos os recursos necessários. Os subdiretórios a seguir são particularmente importantes:

• src/main/java é a raiz do projeto do Maven e contém um esqueleto de código para você trabalhar.
• src/main/java/solution contém a solução concluída.

Instalar os pacotes e o build necessários

Se você estiver usando um ambiente de desenvolvimento integrado com reconhecimento do Maven, como Eclipse ou IntelliJ, importe a pasta extraída como um projeto Maven e compile o projeto normalmente.

Se você estiver usando o Maven na linha de comando, execute o comando a seguir para recuperar os pacotes necessários e compilar o projeto na pasta raiz do projeto descompactado (shopping-account-linking-master):

mvn compile

3. Configurar a autenticação

Nesta etapa, não vamos programar, mas configurar arquivos que contêm tokens de autenticação adequados para a API Google Ads e a API Content para o Shopping.

Configurar a autentificação da API Google AdWords

Este codelab usa o mesmo carregamento de credenciais da biblioteca de cliente. Portanto, se você já usou a biblioteca de cliente das APIs do Google Ads para Java com sua conta de administrador, a configuração já está pronta. Caso contrário, siga as etapas de 1 a 3 para começar a usar a biblioteca de cliente das APIs do Google Ads para Java.

Configurar a autenticação da API Content

Se você ainda não tiver uma chave de conta de serviço:

1. Acesse o Merchant Center da sua conta de múltiplos clientes e selecione API Content no menu flutuante:
2. Selecione Autenticação e clique no botão azul +:
3. Depois de aceitar os Termos de Serviço do Google Cloud Platform e das APIs do Google, seu navegador fará automaticamente o download de um arquivo JSON com a nova chave da conta de serviço.

Agora, siga as instruções para configurar a autenticação dos exemplos do Shopping com uma conta de serviço. Ou seja, uma cópia da chave da sua conta de serviço precisa estar localizada no seguinte caminho do seu diretório principal: shopping-samples/content/service-account.json. Você não precisa definir a configuração de exemplos, a menos que tenha interesse em testar os exemplos após concluir este codelab.

Faça um teste

Agora que os tokens de autenticação estão nos lugares certos, tente executar as amostras. Se você estiver usando o Maven na linha de comando, execute os seguintes comandos:

mvn compile

Observação:se você mudar qualquer um dos arquivos em src/main/resources, mesmo que não faça nenhuma mudança no código (como nesta etapa), recompile antes de executar os exemplos para copiar os recursos alterados para o destino.

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

Se você receber uma mensagem de erro sobre objetos de sessão não fornecidos, seus tokens de autenticação estão no lugar e funcionando corretamente! Caso contrário, a mensagem de erro vai aparecer informando quais credenciais não funcionaram e qual arquivo corrigir.

Importante: a estrutura fornecida presume que sua conta de serviço da API Content está listada apenas como um usuário na sua conta de múltiplos clientes. Se você receber um erro informando que sua conta de serviço tem acesso a mais de uma conta, siga as etapas acima para gerar uma chave de conta de serviço específica para sua conta de múltiplos clientes.

4. Conectar-se às APIs

Agora que você tem tokens de autenticação válidos para as duas APIs que vamos usar, vamos começar a preencher o código. Vamos começar criando objetos de sessão usando nossos tokens de autenticação. Nas próximas etapas, acessaremos os diversos serviços e métodos que cada API fornece usando esses objetos de sessão.

Criar um objeto de sessão da API Content

Para criar uma sessão da API Content, vamos criar um objeto ShoppingContent.Builder que será usado para gerar o objeto ShoppingContent apropriado. Felizmente, tudo o que precisamos para construir o primeiro já está disponível no esqueleto do código, então só precisamos reuni-lo desta forma:

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

Observação: os comentários iniciais neste e nos exemplos de código a seguir já existem no esqueleto de código. Procure-os para ver onde essas linhas devem ser adicionadas.

Também omitimos todas as declarações de importação necessárias para as classes da API Google Ads e da API Content que usamos nesses snippets. Se você não estiver usando um ambiente de desenvolvimento integrado que possa adicionar automaticamente as importações corretas, verifique o código no pacote solution para encontrar as importações necessárias.

A definição de um nome de aplicativo não é estritamente necessária, mas mostra como definir as opções desejadas usando o objeto ShoppingContent.Builder antes de chamar o método build().

Criar um objeto de sessão da API AdWords

Da mesma forma, há uma classe AdWordsSession.Builder para criar objetos AdWordsSession. A principal diferença aqui é que, em vez de definir opções de configuração diretamente no builder, vamos usar o método fromFile() para carregá-las do arquivo ads.properties que configuramos na etapa anterior.

SolutionRunner.java

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

Faça um teste

Vamos usar os mesmos comandos da última seção para recriar e executar o projeto Maven, caso você o execute na linha de comando:

mvn compile

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

Desta vez, você não vai receber erros, mas também não vai receber nenhuma saída interessante. Adicionaremos isso quando chamarmos as APIs para criar e vincular as novas contas.

5. Criar uma nova conta gerenciada do Google AdWords

Agora que criamos os objetos de sessão da API, vamos criar as contas que queremos vincular. Vamos começar com o AdWords e criar uma conta de teste na nossa conta de administrador.

Observação:todos os snippets de código nesta seção foram adicionados ao mesmo local no esqueleto do código na ordem apresentada. Por isso, só mostraremos o comentário (// TODO...), que marca onde ele deve ser colocado no primeiro). Portanto, nesta e etapas futuras, se você vir snippets de código sem um comentário introdutório, eles vão imediatamente após o snippet anterior.

Acessar o ManagedCustomerService

Na Google AdWords API, acessamos os diversos serviços disponíveis recuperando primeiro uma instância da classe AdWordsServices usando o método estático getInstance(). Usando essa instância, podemos criar clientes para esses serviços usando o método get(), que recebe dois argumentos: a sessão para criar o cliente e a interface do serviço desejado.

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

Aqui, acessamos o ManagedCustomerService, que permite gerenciar "clientes" (contas) do AdWords em uma determinada conta de administrador.

Especificar as novas configurações da conta

Primeiro, criaremos um objeto ManagedCustomer que contém as configurações da nova conta. Vamos criar uma conta de teste para este codelab, definindo a moeda como USD e o fuso horário como o da costa oeste dos EUA.

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

Também criamos um número aleatório que é incluído no nome da conta. Isso é apenas para que possamos associar a conta do AdWords que vamos criar aqui com a conta do Merchant Center que vamos criar mais tarde. Assim, podemos inspecionar visualmente as duas contas quando a solução estiver concluída e garantir que elas estejam vinculadas.

Crie a nova conta gerenciada

Para criar a nova conta, usaremos ManagedCustomerOperation para especificar uma operação ADD:

SolutionRunner.java

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

Em seguida, vamos executar a operação usando o método mutate() do objeto ManagedCustomerService. Esse método usa uma matriz de operações para realizar, mas aqui queremos realizar apenas uma operação. O resultado do método mutate() é um valor que contém uma lista de ManagedCustomers. haverá uma lista com um cliente, a nova conta que criamos. Vamos recuperar o ID dessa nova conta para uso futuro e também imprimi-lo para que possamos vê-lo como parte da saída da nossa solução.

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

Testar

Como antes, tente executar a solução. Se você estiver usando o Maven na linha de comando:

mvn compile

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

Se tudo correr bem, você ainda não verá erros e, dessa vez, veremos o ID da nova conta do Google AdWords que criamos. Verifique o site do AdWords da sua conta de administrador. Você também verá a nova conta listada lá.

Observação: a partir desse ponto, cada execução da solução vai gerar novas contas. Você pode cancelar qualquer conta do Google Ads criada no site do Google Ads depois de concluir a execução da solução. Afinal, nosso esquema de nomenclatura para essas contas facilita a visualização de quais foram criadas pelo nosso código.

6. Criar uma nova subconta do Merchant Center

Nesta etapa, vamos criar a subconta do Merchant Center que será vinculada à conta do AdWords criada na última etapa. Em vez de solicitar a vinculação separadamente depois de criar a subconta, podemos solicitar a vinculação durante a criação, pois já temos o ID da conta do Google AdWords correspondente.

Especificar as configurações da nova subconta

Ao contrário da API AdWords, os setters da classe de modelo Account retornam o objeto. Assim, podemos encadear nossas chamadas para eles no novo objeto Account. Também usaremos o número aleatório gerado durante a criação da conta do Google AdWords no nome da nova conta do Google 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")));

Como mencionado na introdução desta etapa, já que temos o ID do AdWords para a nova conta gerenciada, podemos adicionar esse ID à lista de AdwordsLinks da nova subconta. Quando a nova subconta for criada, esse vínculo será solicitado e disponibilizado automaticamente na API do AdWords.

Criar a nova subconta

Na API Content, chamamos o método accounts() do objeto de sessão para acessar o serviço Accounts. Em seguida, chamamos o método insert() diretamente, em vez de configurar um objeto de operação. Esse método usa dois argumentos: o ID da conta de múltiplos clientes em que a nova subconta será criada e o objeto Account que contém as configurações desejadas:

SolutionRunner.java

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

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

O método insert() retorna um objeto Account que contém as configurações da nova subconta. Substituímos o objeto Account original porque a versão retornada inclui uma informação importante: o ID da nova subconta. Isso é exibido na saída da nossa solução para que possamos executar a solução e verificar se a nova subconta existe no Merchant Center.

Testar

Como antes, tente executar a solução. Se você estiver usando o Maven na linha de comando:

mvn compile

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

Se tudo correr bem, você não vai encontrar erros e vai ver os IDs da nova conta do AdWords e do Merchant Center. Verifique o Merchant Center da sua conta de múltiplos clientes para encontrar a nova subconta.

Observação: assim como no Google AdWords, cada execução da solução vai gerar novas contas do Merchant Center. É possível excluir as subcontas criadas no Merchant Center depois de concluir a solução.

7. Aceitar a vinculação na conta do Google AdWords

Na última etapa, criamos uma nova subconta do Merchant Center e solicitamos o vínculo com a nova conta do Google AdWords ao mesmo tempo. Nesta etapa, concluiremos o processo usando a API AdWords para aceitar a vinculação solicitada.

Acesse o CustomerService.

Como antes, vamos usar a classe AdWordsServices para conseguir um cliente para o CustomerService. No entanto, antes de criar o cliente, primeiro alteramos o objeto da sessão do Google AdWords para que os usos futuros ocorram na nova conta gerenciada, e não na conta de administrador. Afinal, a conta do Merchant Center solicitou uma vinculação à conta gerenciada, não à conta de administrador.

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

Especificar o link solicitado

Assim como fizemos com a conta do AdWords, vamos criar um objeto ServiceLink que contém as configurações de vinculação e um objeto ServiceLinkOperation que descreve a operação desejada. Aqui, queremos selecionar o link de serviço pendente para uma conta do MERCHANT_CENTER e SET para ACTIVE. Para a configuração serviceLinkId, usaremos o ID da conta do Merchant Center que acabamos de criar, já que ele é usado para o ID da vinculação de serviço no AdWords.

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

Aceitar a vinculação

Por fim, chamamos o método mutateServiceLinks() do objeto CustomerService para realizar a operação. Como antes, ele usa uma matriz de operações de vinculação de serviço. Desta vez, o método retorna uma lista de links de serviço (possivelmente alterados) diretamente. Portanto, apenas imprimiremos o resultado da solução ao repetir essa lista. Como especificamos apenas uma operação, você espera que apenas um link seja impresso na saída.

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

Faça um teste

Como antes, tente executar a solução. Se você estiver usando o Maven na linha de comando:

mvn compile

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

Se tudo correr bem, você não vai encontrar erros e, desta vez, também vai aparecer uma observação informando que o link do serviço foi atualizado para ficar ativo. Verifique o Google Ads e o Merchant Center e confira se as contas estão realmente vinculadas.

8. Variações em um tema

Parabéns por concluir o codelab. Agora que você tem uma solução totalmente funcional, vamos conferir alguns exemplos de modificação ou extensão dela para usar mais APIs apresentadas neste codelab.

Crédito extra: atualize uma conta do Merchant Center para solicitar uma vinculação ao Google AdWords

No codelab, criamos a conta do Google AdWords de forma inteligente para que pudéssemos usar as informações dela para solicitar a vinculação ao criar a conta do Merchant Center. No entanto, se a conta do Merchant Center já existir, será necessário atualizar a configuração dela. Altere seu código para criar a conta do Merchant Center primeiro, depois volte depois de criar a conta do Google AdWords e atualize a configuração para solicitar a vinculação.

Observação:é recomendável usar o método Accounts.update ou Accounts.patch. Na verdade, teste uma versão com cada um para entender a diferença.

Importante: uma nova conta do Merchant Center pode não ficar disponível imediatamente após a chamada para Accounts.insert. Até que a nova conta esteja disponível, você vai receber um erro HTTP 401 nas tentativas de acesso ou modificação. As amostras do Shopping têm um exemplo de uso de espera exponencial para métodos de repetição em AccountWorkflow.java, que usa o método retryFailures de BaseWorkflowSample.java.

Crédito extra: verifique a criação da vinculação recuperando as informações da conta do Google AdWords e do Merchant Center

Atualmente, o aplicativo trata apenas a ausência de erros de chamadas de API como um sinal de êxito. Tente estender o exemplo para verificar as informações de vinculação das novas contas do Google Merchant Center e do Google AdWords e verificar se a vinculação está realmente ativa.

Observação: na API Content, você vai querer conferir o método Accounts.get. No lado do Google AdWords, convém usar o método getServiceLinks do objeto CustomerServiceInterface.

O mundo é uma aventura

Se você pensar em outras mudanças que poderia fazer, experimente! Se você precisar de um código de referência para ter ideias, confira os exemplos do Google Shopping e o diretório examples na código-fonte da biblioteca de cliente Java do Google Ads.