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 API de Content 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 cuenta 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 un vínculo 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 o versiones posteriores
• Maven
• El código de muestra
• Un editor de texto (se recomienda un IDE que comprenda 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. Esto 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 interés:

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

Instala los paquetes necesarios y compila

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

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 descomprimido (shopping-account-linking-master):

mvn compile

3. Configura la autenticación

En este paso, no codificaremos, sino que configuraremos archivos que contengan tokens de autenticación adecuados para la API de AdWords y la Content API de 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, sigue los pasos del 1 al 3 para comenzar a usar la biblioteca cliente de las APIs de Google Ads para Java.

Configura la autenticació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ú de desbordamiento:
2. Selecciona Autenticación y, luego, haz clic en el botón azul con el signo +:
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 que contiene la clave de tu nueva cuenta de servicio.

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

Pruébalo

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

mvn compile

Nota: Si cambias alguno de los archivos en src/main/resources, incluso si no realizas ningún cambio de 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 sobre la falta de objetos de sesión, significa que tus tokens de autenticación están en su lugar y funcionan correctamente. De lo contrario, el mensaje de error que recibas te indicará qué credenciales no funcionaron y qué archivo debes corregir.

Importante: El marco de trabajo que proporcionamos supone que tu cuenta de servicio de Content API solo aparece como usuario en tu cuenta de varios clientes. Si recibes un 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íficamente para tu cuenta de varios clientes.

4. Conéctate 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. En pasos posteriores, accederemos a los distintos servicios y métodos que proporciona cada API con estos objetos de sesión.

Crea un objeto de sesión de la API de Content

Para crear una sesión de la API de Content, crearemos un objeto ShoppingContent.Builder y, luego, lo usaremos para compilar 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 unirlo 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 de este y los siguientes ejemplos de código ya existen en el esqueleto del código. Busca los puntos donde 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, consulta el código del paquete solution para ver las importaciones necesarias.

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

Crea un objeto de sesión de la API de AdWords

Del mismo modo, existe una clase AdWordsSession.Builder para compilar objetos AdWordsSession. La principal diferencia 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. Cómo crear una nueva cuenta administrada de AdWords

Ahora que creamos nuestros objetos de sesión de la API, 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 en el mismo lugar del código esqueleto en el orden en que se presentan. Por ese motivo, solo mostraremos el comentario (// TODO...) que marca dónde colocarlo en el primero). Por lo tanto, en este y en los pasos futuros, si ves fragmentos de código sin un comentario introductorio, estos van inmediatamente después del fragmento anterior.

Accede a ManagedCustomerService

En la API de AdWords, accedemos a los distintos servicios disponibles recuperando primero una instancia de la clase AdWordsServices con 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.

Especifica 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, estableceremos su moneda en USD y su zona horaria en la misma que 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 nuestra solución esté completa y asegurarnos de que, de hecho, se vincularon las dos.

Crea 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 ManagedCustomers. En este caso, 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 que podamos 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 sale bien, no deberías ver ningún error y, esta vez, verás el ID de la nueva cuenta de AdWords que creamos. Consulta el sitio de AdWords de tu cuenta de administrador y verás la nueva cuenta allí también.

Nota: En este punto, cada ejecución de la solución generará cuentas nuevas. Puedes cancelar las cuentas de AdWords creadas a través del sitio de AdWords después de que termines de ejecutar tu solución. Después de todo, nuestro esquema de nombres para estas cuentas facilita ver cuáles creó 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 paso anterior. En lugar de solicitar la vinculación por separado después de crear la subcuenta, podemos solicitarla durante la creación, ya que ya tenemos el ID de la cuenta de AdWords correspondiente.

Especifica la configuración de la nueva cuenta secundaria

A diferencia de la API de AdWords, los métodos setter de la clase de modelo Account devuelven 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 de la nueva cuenta administrada, ahora podemos agregar ese ID 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 nueva cuenta secundaria

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 toma dos argumentos: el ID de la cuenta de varios clientes en la que se creará la nueva subcuenta 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() devuelve un objeto Account que contiene la configuración de la nueva subcuenta. Reemplazamos nuestro objeto Account original porque la versión que se devolvió incluye un dato importante: el ID de la nueva subcuenta. Imprimimos eso en el resultado de nuestra solución, por lo que podemos ejecutarla y, luego, verificar que la nueva cuenta secundaria exista en Merchant Center.

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 sale bien, no deberías ver ningún error y, esta vez, veremos los IDs de la nueva cuenta de AdWords y la nueva cuenta de Merchant Center. Consulta Merchant Center para tu cuenta de varios clientes y ver la nueva cuenta secundaria allí.

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

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

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

Accede a CustomerService

Al igual que antes, usaremos la clase AdWordsServices para 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 operen en la nueva cuenta administrada en lugar de la cuenta de administrador. Después de todo, la cuenta de Merchant Center solicitó un vínculo 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 contenga la configuración de la vinculación y, luego, un objeto ServiceLinkOperation que describa la operación deseada. Aquí, queremos llevar la vinculación de servicio pendiente a una cuenta de MERCHANT_CENTER y SETla a ACTIVE. Para el parámetro de configuración serviceLinkId, usaremos el ID de la cuenta de Merchant Center que acabamos de crear, ya que se usa 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 la vinculación

Por último, llamaremos al método mutateServiceLinks() del objeto CustomerService para realizar la operación. Al igual que antes, toma un array de operaciones de vinculación de servicios. Esta vez, el método devuelve directamente una lista de vínculos de servicios (posiblemente modificados), por lo que solo imprimiremos el resultado de nuestra solución iterando sobre esa lista. Por supuesto, como solo especificamos una operación, solo se espera que se imprima un 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 sale bien, no deberías ver ningún error y, esta vez, también verás una nota que indica que el vínculo del servicio se actualizó para estar activo. Verifica AdWords y Merchant Center, y vuelve a comprobar que las cuentas estén vinculadas.

8. Variaciones sobre un tema

¡Felicitaciones por completar el codelab! Ahora que tienes una solución que funciona por completo, 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 de Merchant Center existente para solicitar un vínculo de AdWords

En el codelab, creamos primero la cuenta de AdWords de forma inteligente 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, regresa después de crear la cuenta de AdWords y actualiza su configuración para solicitar la vinculación.

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

Importante: Es posible que una cuenta nueva de Merchant Center no esté disponible inmediatamente después de la llamada a Accounts.insert. Hasta que la cuenta nueva esté disponible, recibirás un error HTTP 401 cuando intentes acceder a ella o modificarla. En las muestras de Shopping, se incluye 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: Verifica la creación de la vinculación recuperando la información de las cuentas de AdWords y Merchant Center

Actualmente, la aplicación solo considera la ausencia de errores en las llamadas a la API como un signo de éxito. Intenta extender el ejemplo para verificar la información de vinculación de las nuevas cuentas de Merchant Center y AdWords, y comprueba que la vinculación esté activa.

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

El mundo está en tus manos

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 el código fuente de la biblioteca cliente de Google Ads para Java.