Cómo crear y vincular cuentas secundarias de AdWords y Merchant Center

1. Introducción

En este codelab, aprenderás algunos conceptos básicos para trabajar con la Content API for Shopping y la API de AdWords, y compilarás una aplicación que use ambas. En particular, compilarás una aplicación de línea de comandos que creará y vinculará una cuenta de AdWords y una de Merchant Center.

Qué aprenderás

• Cómo crear cuentas de AdWords administradas por una cuenta de administrador
• Cómo crear cuentas de Merchant Center administradas por una cuenta de varios clientes
• Cómo solicitar una vinculación de una cuenta de Merchant Center a una cuenta de AdWords
• Cómo aceptar una vinculación pendiente de Merchant Center en una cuenta de AdWords

Requisitos

• Una cuenta de administrador de AdWords
• Una cuenta de varios clientes de Merchant Center
• Java 7 y versiones posteriores
• Maven
• El código de muestra
• Un editor de texto (se recomienda un IDE que comprenda los proyectos de Maven, como Eclipse o IntelliJ)

2. Cómo prepararte

Descarga el código

Haz clic en el siguiente vínculo para descargar todo el código de este codelab:

Descargar código fuente

Descomprime el archivo zip descargado. Se descomprimirá una carpeta raíz (shopping-account-linking-master), que contiene un proyecto de Maven junto con todos los recursos que necesitarás. Los siguientes subdirectorios son de especial importancia:

• src/main/java es la raíz de origen del proyecto de Maven y contiene un esqueleto de código en el que puedes trabajar.
• src/main/java/solution contiene la solución terminada.

Cómo instalar los paquetes requeridos y compilar

Si usas un IDE compatible con Maven, como Eclipse o IntelliJ, puedes importar la carpeta extraída como un proyecto de Maven y, luego, compilar el proyecto normalmente.

Si usas Maven desde la línea de comandos, puedes ejecutar el siguiente comando para recuperar los paquetes necesarios y compilar el proyecto desde la carpeta raíz del proyecto desempaquetado (shopping-account-linking-master):

mvn compile

3. Configura la autenticación

En este paso, no codificaremos, sino que configuraremos archivos que contengan los tokens de autenticación adecuados para la API de AdWords y la Content API for Shopping.

Configura la autenticación de la API de AdWords

En este codelab, se usa la misma carga de credenciales que la biblioteca cliente, por lo que, si ya usaste la biblioteca cliente de las APIs de Google Ads para Java con tu cuenta de administrador, ya deberías tener todo configurado. De lo contrario, siga los pasos 1 a 3 para comenzar a utilizar la biblioteca cliente de las APIs de Google Ads para Java.

Cómo configurar la utenticación de Content API

Si aún no tienes una clave de cuenta de servicio, haz lo siguiente:

1. Ve a Merchant Center para tu cuenta de varios clientes y selecciona Content API en el menú ampliado:
2. Selecciona Autenticación y, luego, haz clic en el botón azul +:
3. Después de aceptar las Condiciones del Servicio de Google Cloud Platform y las APIs de Google, tu navegador descargará automáticamente un archivo JSON con tu nueva clave de cuenta de servicio.

Ahora, sigue las instrucciones para configurar la autenticación de los ejemplos de Shopping con una cuenta de servicio. Es decir, una copia de la clave de tu cuenta de servicio debe estar en la siguiente ruta de acceso desde tu directorio principal: shopping-samples/content/service-account.json. No es necesario que establezcas la configuración de las muestras, a menos que te interese probarlos después de finalizar este codelab.

Pruébalo

Ahora que tienes los tokens de autenticación en los lugares correctos, intenta ejecutar los ejemplos. Si usas Maven en la línea de comandos, ejecuta los siguientes comandos:

mvn compile

Nota: Si cambias alguno de los archivos de src/main/resources, incluso si no realizas ningún cambio en el código (como en este paso), vuelve a compilar antes de ejecutar las muestras para copiar los recursos modificados en el destino.

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

Si recibes un mensaje de error que indica que no se proporcionan los objetos de sesión, significa que tus tokens de autenticación están implementados y funcionan correctamente. De lo contrario, el mensaje de error que recibas debería informarte qué credenciales no funcionaron y qué archivo debes corregir.

Importante: En el marco de trabajo que proporcionamos, se presupone que tu cuenta de servicio de Content API solo aparece como usuario en tu cuenta de varios clientes. Si recibes un mensaje de error que indica que tu cuenta de servicio tiene acceso a más de una cuenta, sigue los pasos anteriores para obtener una clave de cuenta de servicio específica para tu cuenta de varios clientes.

4. Cómo conectarse a las APIs

Ahora que tienes tokens de autenticación válidos para las dos APIs que usaremos, comencemos a completar el código real. Comenzaremos por crear objetos de sesión con nuestros tokens de autenticación. Más adelante, accederemos a los diversos servicios y métodos que proporciona cada API con estos objetos de sesión.

Crea un objeto de sesión de Content API

Para crear una sesión de Content API, crearemos un objeto ShoppingContent.Builder y lo usaremos para crear el objeto ShoppingContent adecuado. Por suerte, todo lo que necesitamos para construir el primero ya está disponible en el esqueleto de código, por lo que solo debemos reunirlo de la siguiente manera:

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

Nota: Los comentarios iniciales en esta muestra de código y en las siguientes ya existen en la estructura de código. Búscalos para ver dónde se deben agregar estas líneas.

También omitimos las instrucciones de importación necesarias para las clases de la API de AdWords y la API de Content que usamos en estos fragmentos. Si no usas un IDE que pueda agregar automáticamente las importaciones correctas, verifica el código del paquete solution para conocer las importaciones necesarias.

No es estrictamente necesario establecer un nombre de aplicación, pero se muestra cómo establecer las opciones deseadas a través del objeto ShoppingContent.Builder antes de llamar al método build().

Cómo crear un objeto de sesión de la API de AdWords

Del mismo modo, hay una clase AdWordsSession.Builder para compilar objetos AdWordsSession. La diferencia principal aquí es que, en lugar de establecer opciones de configuración directamente en el compilador, usaremos el método fromFile() para cargarlas desde el archivo ads.properties que configuramos en el paso anterior.

SolutionRunner.java

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

Pruébalo

Usaremos los mismos comandos que en la sección anterior para volver a compilar y ejecutar el proyecto de Maven, si lo ejecutas desde la línea de comandos:

mvn compile

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

Esta vez, no deberías obtener ningún error, aunque tampoco obtendrás ningún resultado interesante. Agregaremos eso cuando llamemos a las APIs para crear y vincular las cuentas nuevas.

5. Crea una nueva cuenta de AdWords administrada

Ahora que creamos nuestros objetos de sesión de API, analizaremos y crearemos las cuentas que queremos vincular. Comenzaremos con AdWords y crearemos una cuenta de prueba en nuestra cuenta de administrador.

Nota: Todos los fragmentos de código de esta sección se agregan al mismo lugar en el código del esqueleto en el orden presentado. Por ese motivo, solo mostraremos el comentario (// TODO...) que marca dónde colocarlos en el primero. Por lo tanto, en este paso y en los siguientes, si ves fragmentos de código sin un comentario introductorio, se mostrarán inmediatamente después del fragmento anterior.

Accede a ManagedCustomerService

En la API de AdWords, para acceder a los diversos servicios disponibles, primero recuperamos una instancia de la clase AdWordsServices mediante el método estático getInstance(). Con esta instancia, podemos crear clientes para esos servicios a través del método get(), que toma dos argumentos: la sesión para la que se creará el cliente y la interfaz del servicio deseado.

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

Aquí, accedemos a ManagedCustomerService, que nos permite administrar los "clientes" (cuentas) de AdWords desde una cuenta de administrador determinada.

Cómo especificar la nueva configuración de la cuenta

Primero, crearemos un objeto ManagedCustomer que contenga la configuración de nuestra cuenta nueva. Crearemos una cuenta de prueba para este codelab y configuraremos su moneda en USD y su zona horaria en la misma que la de la costa oeste de EE.UU.

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

También creamos un número aleatorio que incluimos en el nombre de la cuenta. Esto es solo para que podamos hacer coincidir la cuenta de AdWords que crearemos aquí con la cuenta de Merchant Center que crearemos más adelante, de modo que podamos inspeccionarlas visualmente una vez que se complete nuestra solución y asegurarnos de que realmente se hayan vinculado las dos.

Crear la nueva cuenta administrada

Para crear la cuenta nueva, usaremos ManagedCustomerOperation para especificar una operación ADD:

SolutionRunner.java

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

Luego, realizaremos la operación con el método mutate() del objeto ManagedCustomerService. Este método toma un array de operaciones para realizar, pero aquí solo queremos realizar una sola operación. El resultado del método mutate() es un valor que contiene una lista de ManagedCustomer. Aquí, será una lista que contiene un cliente, la cuenta nueva que creamos. Recuperaremos el ID de esa cuenta nueva para usarlo en el futuro y también lo imprimiremos para poder verlo como parte del resultado de nuestra solución.

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

Pruébalo

Como antes, intenta ejecutar la solución. Si usas Maven desde la línea de comandos, haz lo siguiente:

mvn compile

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

Si todo resulta bien, no deberías ver errores de todas formas, y esta vez veremos el ID de la nueva cuenta de AdWords que creamos. Revisa el sitio de AdWords de tu cuenta de administrador. Allí también deberías ver la cuenta nueva.

Nota: En este punto, cada ejecución de la solución ahora generará cuentas nuevas. Puedes cancelar las cuentas de AdWords creadas a través del sitio de AdWords después de ejecutar tu solución. Después de todo, nuestro esquema de nombres para estas cuentas hace que sea fácil ver cuáles fueron creadas por nuestro código.

6. Crea una nueva cuenta secundaria de Merchant Center

En este paso, crearemos la cuenta secundaria de Merchant Center que vincularemos a la cuenta de AdWords que creamos en el último paso. En lugar de solicitar la vinculación por separado después de crear la cuenta secundaria, podemos solicitar la vinculación durante la creación, dado que ya tenemos el ID de la cuenta de AdWords correspondiente.

Especifica la configuración de la cuenta secundaria nueva

A diferencia de la API de AdWords, los métodos set para la clase de modelo Account muestran el objeto, por lo que podemos encadenar nuestras llamadas a ellos en el nuevo objeto Account. También usaremos el número aleatorio que generamos durante la creación de la cuenta de AdWords en el nombre de la nueva cuenta de 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 se mencionó en la introducción de este paso, dado que ya tenemos el ID de AdWords para la nueva cuenta administrada, podemos agregarlo a la lista de AdwordsLinks para la nueva cuenta secundaria. Cuando se cree la nueva cuenta secundaria, este vínculo se solicitará automáticamente y estará disponible en la API de AdWords.

Crea la cuenta secundaria nueva

En la API de Content, llamamos al método accounts() del objeto de sesión para acceder al servicio Accounts y, luego, llamamos al método insert() directamente en lugar de configurar un objeto de operación. Este método tiene dos argumentos: el ID de la cuenta de varios clientes en la que se creará la nueva cuenta secundaria y el objeto Account que contiene la configuración deseada:

SolutionRunner.java

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

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

El método insert() muestra un objeto Account que contiene la configuración de la nueva cuenta secundaria. Reemplazamos nuestro objeto original Account porque la versión que se muestra incluye información importante: el ID de la cuenta secundaria nueva. Lo imprimimos en el resultado de nuestra solución para poder ejecutarla y, luego, verificar que la nueva cuenta secundaria exista en Merchant Center.

Pruébalo

Como antes, prueba ejecutar la solución. Si usas Maven desde la línea de comandos, haz lo siguiente:

mvn compile

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

Si todo va bien, no deberías ver ningún error y, esta vez, veremos los IDs de la nueva cuenta de AdWords y de la nueva cuenta de Merchant Center. Consulta la página de Merchant Center de tu cuenta de varios clientes para ver la cuenta secundaria nueva allí.

Nota: Al igual que con AdWords, cada ejecución de la solución ahora generará cuentas nuevas de Merchant Center. Puedes borrar las cuentas secundarias creadas a través de Merchant Center después de ejecutar la solución.

7. Acepta la vinculación desde la cuenta de AdWords

En el último paso, creamos una nueva cuenta secundaria de Merchant Center y, al mismo tiempo, solicitamos la vinculación a nuestra nueva cuenta de AdWords. En este paso, terminaremos el proceso con la API de AdWords para aceptar la vinculación solicitada.

Accede a CustomerService

Al igual que antes, usaremos la clase AdWordsServices a fin de obtener un cliente para CustomerService. Sin embargo, antes de crear el cliente, primero cambiamos nuestro objeto de sesión de AdWords para que los usos futuros se ejecuten en la nueva cuenta administrada en lugar de la cuenta de administrador. Después de todo, la cuenta de Merchant Center solicitó una vinculación a la cuenta administrada, no a la cuenta 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);

Especifica el vínculo solicitado

Al igual que cuando creamos una cuenta de AdWords nueva, crearemos un objeto ServiceLink que contiene la configuración de la vinculación y, luego, un objeto ServiceLinkOperation que describe la operación deseada. Aquí, queremos llevar el vínculo de servicio pendiente a una cuenta de MERCHANT_CENTER y SET a ACTIVE. Para el parámetro de configuración serviceLinkId, utilizaremos el ID de la cuenta de Merchant Center que acabamos de crear, ya que se utiliza para el ID de la vinculación del servicio en 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);

Aceptar el vínculo

Por último, llamaremos al método mutateServiceLinks() del objeto CustomerService para realizar la operación. Como antes, se necesita un array de operaciones de vínculo de servicios. Esta vez, el método muestra una lista de vínculos de servicio (posiblemente modificados) directamente, por lo que solo imprimiremos el resultado de nuestra solución realizando un bucle en esa lista. Por supuesto, dado que solo especificamos una operación, solo esperas que se imprima un único vínculo en el resultado.

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

Pruébalo

Como antes, intenta ejecutar la solución. Si usas Maven desde la línea de comandos, haz lo siguiente:

mvn compile

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

Si todo resulta bien, no deberías ver errores, y esta vez también veremos una nota que indica que se actualizó el vínculo del servicio para que esté activo. Revisa AdWords y Merchant Center y vuelve a verificar que las cuentas estén vinculadas.

8. Variaciones sobre un tema

Felicitaciones por completar el codelab. Ahora que tienes una solución que funciona completamente, veamos algunos ejemplos de cómo podrías modificarla o extenderla para usar más de las APIs que viste en este codelab.

Crédito adicional: Actualiza una cuenta existente de Merchant Center para solicitar una vinculación con AdWords

En este codelab, primero creamos de manera ingeniosa la cuenta de AdWords para poder usar su información y solicitar la vinculación cuando creamos la cuenta de Merchant Center. Sin embargo, si la cuenta de Merchant Center ya existe, deberás actualizar su configuración. Intenta modificar tu código para crear primero la cuenta de Merchant Center y, luego, vuelve después de crear la cuenta de AdWords y actualiza su configuración para solicitar la vinculación.

Nota: Te recomendamos usar el método Accounts.update o Accounts.patch. De hecho, prueba una versión con cada una para comprender la diferencia.

Importante: Es posible que una cuenta nueva de Merchant Center no esté disponible inmediatamente después de la llamada al Accounts.insert. Hasta que la cuenta nueva esté disponible, recibirás un error HTTP 401 cuando intentes acceder a ella o modificarla. Los ejemplos de Shopping tienen un ejemplo del uso de la retirada exponencial para reintentar métodos en AccountWorkflow.java, que usa el método retryFailures de BaseWorkflowSample.java.

Crédito adicional: Para verificar la creación del vínculo, recupere la información de las cuentas de AdWords y Merchant Center

Actualmente, la aplicación solo trata la ausencia de errores de las llamadas a la API como una señal de éxito. Intenta ampliar el ejemplo para verificar la información de vinculación de las nuevas cuentas de Merchant Center y AdWords, y comprobar que la vinculación realmente esté activa.

Nota: En el caso de Content API, te recomendamos que consultes el método Accounts.get. En el lado de AdWords, te recomendamos que uses el método getServiceLinks del objeto CustomerServiceInterface.

Tienes el mundo a tus pies

Si se te ocurren otros cambios que podrías hacer, pruébalos. Si necesitas código de referencia para tus ideas, consulta los ejemplos de Google Shopping y el directorio examples en la fuente de la biblioteca cliente de Java de Google Ads.