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

1. Introdução

Neste codelab, você vai aprender alguns conceitos básicos sobre como trabalhar com a API Content for Shopping e a API AdWords e criar um aplicativo que usa as duas. Em particular, você vai criar um aplicativo de linha de comando que vai criar e vincular uma conta do AdWords e uma do Merchant Center.

O que você vai aprender

• Como criar contas do AdWords gerenciadas por uma conta de administrador.
• Como criar contas do Merchant Center gerenciadas por uma conta de múltiplos clientes.
• Como solicitar uma vinculação de uma conta do Merchant Center a uma do Google AdWords.
• 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 Ads
• Uma conta de múltiplos clientes do Merchant Center
• Java 7 ou mais recente
• Maven
• Código de amostra
• Um editor de texto (recomenda-se um ambiente de desenvolvimento integrado que entenda projetos do Maven, como Eclipse ou IntelliJ)

2. Etapas da configuração

Baixe o 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 descompacta uma pasta raiz (shopping-account-linking-master), que contém um projeto Maven com todos os recursos necessários. Os seguintes subdiretórios são de particular importância:

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

Instalar pacotes e criar

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

Se você estiver usando o Maven na linha de comando, execute o seguinte comando 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 nada, mas configurar arquivos que contêm tokens de autenticação adequados para a API AdWords e a API Content for Shopping.

Configurar a autenticação da API AdWords

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

Configurar a autenticação da API Content

Se você ainda não tiver uma chave da 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 vai baixar automaticamente um arquivo JSON com a chave da nova conta de serviço.

Agora siga as instruções para configurar a autenticação para as amostras do Shopping com uma conta de serviço. Ou seja, uma cópia da chave da conta de serviço precisa estar localizada no seguinte caminho do diretório inicial: shopping-samples/content/service-account.json. Não é necessário configurar a configuração de amostras, a menos que você queira testar as amostras depois de concluir este codelab.

Teste

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

mvn compile

Observação:se você mudar algum dos arquivos em src/main/resources, mesmo que não faça mudanças 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 informando que os objetos de sessão não foram fornecidos, os tokens de autenticação estão no lugar certo e funcionando corretamente. Caso contrário, a mensagem de erro vai informar quais credenciais não funcionaram e qual arquivo precisa ser corrigido.

Importante: a estrutura que fornecemos pressupõe que sua conta de serviço da API Content só esteja listada 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 receber 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 real. Vamos começar criando objetos de sessão usando nossos tokens de autenticação. Nas etapas posteriores, vamos acessar os vários serviços e métodos que cada API oferece usando esses objetos de sessão.

Criar um objeto de sessão da API Content

Para criar uma sessão da API Content, vamos construir um objeto ShoppingContent.Builder e usá-lo para criar o objeto ShoppingContent adequado. Felizmente, tudo o que precisamos para construir o primeiro já está disponível no esqueleto de código. Basta juntar tudo assim:

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 do código. Procure-os para saber onde essas linhas devem ser adicionadas.

Também omitimos todas as instruções de importação necessárias para as classes da API AdWords e da API Content que usamos nesses snippets. Se você não estiver usando uma IDE que possa adicionar automaticamente as importações corretas, verifique o código no pacote solution para as importações necessárias.

Definir um nome de aplicativo não é estritamente necessário, 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();

Teste

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

mvn compile

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

Desta vez, você não vai receber nenhum erro, mas também não vai ter uma saída interessante. Vamos adicionar 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 Google AdWords e criar uma conta de teste na nossa conta de administrador.

Observação:todos os snippets de código nesta seção são adicionados ao mesmo lugar no código de esqueleto na ordem apresentada. Por isso, vamos mostrar apenas o comentário // TODO...) que marca onde colocar os elementos no primeiro. Portanto, nesta e nas próximas etapas, se você encontrar snippets de código sem um comentário introdutório, eles vão imediatamente após o snippet anterior.

Acessar o ManagedCustomerService

Na API AdWords, primeiro recuperamos uma instância da classe AdWordsServices usando o método estático getInstance() para acessar os vários serviços disponíveis. Usando essa instância, podemos criar clientes para esses serviços com o método get(), que usa 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 Google AdWords de uma determinada conta de administrador.

Especificar as novas configurações da conta

Primeiro, vamos criar um objeto ManagedCustomer que contenha 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 mesmo 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ímos no nome da conta. Isso é apenas para que possamos corresponder a conta do Google Ads que vamos criar aqui com a conta do Merchant Center que vamos criar mais tarde. Assim, podemos inspecioná-las visualmente quando nossa solução estiver concluída e garantir que ela realmente vinculou as duas.

Criar a nova conta gerenciada

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

SolutionRunner.java

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

Em seguida, vamos realizar a operação usando o método mutate() do objeto ManagedCustomerService. Esse método usa uma matriz de operações a serem realizadas, mas aqui só queremos realizar uma única operação. O resultado do método mutate() é um valor que contém uma lista de ManagedCustomers. Aqui, será 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 ele apareça 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);

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ê ainda não vai ver erros, e desta vez vamos mostrar o ID da nova conta do Google Ads que criamos. Verifique o site do AdWords para sua conta de administrador. A nova conta também vai aparecer lá.

Observação:a partir deste ponto, cada execução da solução vai gerar novas contas. Você pode cancelar as contas do AdWords criadas no site do AdWords depois de concluir a execução da solução. Afinal, nosso esquema de nomenclatura para essas contas facilita a identificação das que foram criadas pelo nosso código.

6. Criar uma subconta do Merchant Center

Nesta etapa, vamos criar a subconta do Merchant Center que será vinculada à conta do Google Ads criada na etapa anterior. Em vez de solicitar uma vinculação separadamente após criar a subconta, podemos fazer isso durante a criação, já que temos o ID da conta do Google AdWords correspondente.

Especifique 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 a eles no novo objeto Account. Vamos usar o número aleatório gerado durante a criação da conta do Google Ads no nome da nova conta do Merchant Center também.

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á temos o ID do Google Ads para a nova conta gerenciada. Portanto, podemos adicionar esse ID à lista de AdwordsLinks para a nova subconta agora. Quando a nova subconta for criada, essa vinculação será solicitada automaticamente e estará disponível na API AdWords.

Crie a nova subconta.

Na Content API, chamamos o método accounts() do objeto de sessão para acessar o serviço Accounts e, 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 nosso objeto Account original porque a versão retornada inclui uma informação importante: o ID da nova subconta. Imprimimos isso na saída da nossa solução. Assim, podemos executar a solução e verificar se a nova subconta existe no Merchant Center.

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 der certo, você não vai encontrar erros. Desta vez, vamos ver os IDs da nova conta do Google Ads e do Merchant Center. Verifique o Merchant Center da sua conta de múltiplos clientes para conferir a nova subconta.

Observação:assim como no AdWords, cada execução da solução vai gerar novas contas do Merchant Center. Você pode excluir as subcontas criadas no Merchant Center depois de concluir a execução da solução.

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

Na última etapa, criamos uma subconta do Merchant Center e solicitamos a vinculação à nossa nova conta do Google Ads ao mesmo tempo. Nesta etapa, vamos concluir o processo usando a API AdWords para aceitar a vinculação solicitada.

Acesse o CustomerService

Como antes, vamos usar a classe AdWordsServices para receber um cliente para o CustomerService. No entanto, antes de criar o cliente, mudamos o objeto da sessão do AdWords para que os usos futuros operem na nova conta gerenciada em vez da conta de administrador. Afinal, a conta do Merchant Center pediu 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);

Especifique o link solicitado

Assim como quando criamos uma 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 levar a vinculação de serviço pendente para uma conta MERCHANT_CENTER e SET para ACTIVE. Para a configuração serviceLinkId, vamos usar 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 Google Ads.

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 o link

Por fim, vamos chamar o método mutateServiceLinks() do objeto CustomerService para realizar a operação. Como antes, ele usa uma matriz de operações de link de serviço. Desta vez, o método retorna uma lista de links de serviço (possivelmente alterados) diretamente. Portanto, vamos apenas imprimir o resultado da nossa solução fazendo um loop nessa 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());
}

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 der certo, você não vai encontrar erros. Desta vez, também vamos ver uma observação informando que o link do serviço foi atualizado para ficar ativo. Verifique o AdWords e o Merchant Center e confira se as contas estão vinculadas.

8. Variações de um tema

Parabéns por concluir o codelab! Agora que você tem uma solução totalmente funcional, vamos conferir alguns exemplos de como modificar ou estender essa solução para usar mais das APIs que você viu neste codelab.

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

No codelab, criamos primeiro a conta do AdWords para usar as informações dela e solicitar a vinculação ao criar a conta do Merchant Center. No entanto, se a conta do Merchant Center já existir, atualize a configuração dela. Tente alterar seu código para criar primeiro a conta do Merchant Center e, depois, volte após criar a conta do AdWords e atualize a configuração dela para solicitar a vinculação.

Observação:use 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 estar disponível imediatamente após a chamada para Accounts.insert. Até que a nova conta esteja disponível, você vai receber um erro de HTTP 401 ao tentar acessar ou modificar a conta. Os exemplos do Shopping têm um exemplo de uso de espera exponencial para tentar novamente métodos 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 Ads e do Merchant Center

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

Observação:na API Content, consulte o método Accounts.get. No AdWords, use o método getServiceLinks do objeto CustomerServiceInterface.

O mundo é seu

Se você pensar em outras mudanças que pode fazer, tente! Se você precisar de código de referência para suas ideias, confira as amostras do Google Shopping e o diretório examples na fonte da biblioteca de cliente Java do Google Ads.