Mutar

Los scripts de Google Ads ofrecen compatibilidad con las mutaciones genéricas que están disponibles en la API de Google Ads. La mayoría de las operaciones que se pueden realizar desde GoogleAdsService.mutate también se pueden realizar en los scripts de Google Ads, incluida la creación y administración de campañas.

Dado que esta función permite acceder a una parte tan grande de la API de Google Ads, es importante tener un conocimiento básico de las convenciones de la API de Google Ads para usar esta función. Se pueden omitir muchos aspectos, como los tokens de desarrollador y la autorización, ya que las secuencias de comandos de Google Ads se encargan de ellos, pero debes formar una solicitud de mutación válida.

Estos son algunos recursos básicos sobre la interfaz de REST de la API de Google Ads con los que deberías familiarizarte antes de continuar con esta guía:

Ejemplo básico

Para demostrar la funcionalidad, considera este ejemplo básico que crea un presupuesto de la campaña:

const budgetResult = AdsApp.mutate({
    campaignBudgetOperation: {
      create: {
        amountMicros: 10000000,
        explicitlyShared: false
      }
    }
  });

Una llamada a AdsApp.mutate toma un objeto JSON que representa un solo MutateOperation. Dentro de este objeto, especificas qué tipo de operación estás realizando; en este caso, una campaignBudgetOperation. Luego, especifica create, remove o ambos update y updateMask. Los campos específicos dentro de create y update dependen del tipo específico de recurso en el que operas.

Compila una operación

Existen algunas estrategias que puedes usar para crear una operación válida. Siguiendo con el ejemplo del presupuesto de la campaña, puedes consultar la documentación de referencia de REST para el presupuesto de la campaña para ver una lista de todos sus campos válidos y, luego, completar los campos correspondientes o escribir código de JavaScript personalizado en tu secuencia de comandos para crear un objeto adecuado.

Como alternativa, puedes intentar compilar una operación de forma dinámica con la función "Probar esto" para el presupuesto de la campaña, que te permite compilar un cuerpo de la solicitud de forma dinámica eligiendo los campos que deseas agregar. Luego, puedes extraer el contenido de la operación del resultado generado y agregarlo a tu llamada a mutate después de especificar el tipo de operación.

Tipos de operación

Crear

Especifica create en tu operación y pasa una representación de objeto del recurso que deseas crear.

Consulta el fragmento que se proporcionó antes para ver un ejemplo de la operación create.

Quitar

Especifica remove en tu operación y pasa el nombre del recurso que quieres quitar, por ejemplo:

AdsApp.mutate({
    adGroupOperation: {
        remove: "customers/[CUSTOMER_ID]/adGroups/[AD_GROUP_ID]"
    }
});

Si no conoces el nombre del recurso de una entidad, puedes recuperarlo con una solicitud Adsapp.search.

Actualizar

Especifica update en tu operación y pasa un objeto con el nombre del recurso especificado para que el sistema pueda determinar qué objeto deseas actualizar. Además, completa los campos cuyos valores quieras actualizar y especifica una updateMask que indique exactamente qué campos planeas cambiar en esta solicitud. No incluyas el nombre del recurso en la máscara de actualización.

Ejemplo de una operación update:

const campaignResult = AdsApp.mutate({
    campaignOperation: {
        update: {
            resourceName: "customers/[CUSTOMER_ID]/campaigns/[CAMPAIGN_ID]",
            status: "PAUSED",
            name: "[Paused] My campaign"
        },
        updateMask: "name,status"
    }
});

Cómo controlar los resultados

Independientemente del tipo de operación, el valor que se muestra es un MutateResult. Puedes usar el nombre del recurso que se muestra para consultar el estado actual del recurso después de la mutación y verificar si la operación se realizó correctamente o qué errores se produjeron, si los hubiera.

A continuación, se muestra un ejemplo de un flujo básico para verificar un resultado y mostrar información en los registros:

const result = AdsApp.mutate( ... );
if (result.isSuccessful()) {
    console.log(`Resource ${result.getResourceName()} successfully mutated.`);
} else {
    console.log("Errors encountered:");
    for (const error of result.getErrorMessages()) {
        console.log(error);
    }
}

Varias operaciones

Las secuencias de comandos de Google Ads también admiten la mutación de varias operaciones en una sola solicitud con el método AdsApp.mutateAll. Puedes crear entidades que dependan unas de otras, como una jerarquía de campaña completa, en una sola solicitud. De manera opcional, puedes hacer que todo el conjunto de operaciones sea atómico, de modo que, si alguna falla, no se realice ninguna.

El valor que se muestra es un array de objetos MutateResult, uno para cada operación que proporcionaste y en el mismo orden que las operaciones iniciales.

Esta función tiene el mismo comportamiento que la de la API de Google Ads, por lo que debes consultar la guía de prácticas recomendadas de la API de Google Ads para obtener una explicación completa de los IDs temporales y otras consideraciones. Ten en cuenta que la guía usa snake_case para representar los nombres de los campos, mientras que la documentación de las secuencias de comandos de Google Ads usa lowerCamelCase. Ambos casos se aceptan en los scripts de Google Ads, por lo que puedes copiar el código directamente de esa guía.

Para realizar varias operaciones en una sola solicitud, recopila todas tus operaciones en un array y, luego, llama a AdsApp.mutateAll. La llamada a mutateAll toma el array de operaciones como primer argumento y un segundo argumento opcional de opciones, que incluye lo siguiente:

  • apiVersion: Puedes especificar una versión de la API personalizada, como V26, si quieres usar una versión diferente de la predeterminada de las secuencias de comandos. Puedes usar cualquier versión disponible públicamente en ese momento.
  • partialFailure: El valor predeterminado de este campo es true. Si se establece en true, se realizan las operaciones válidas y las operaciones con errores devuelven errores. Si se establece en false, no se realiza ninguna operación si falla alguna, lo que hace que este conjunto de operaciones sea atómico.

A continuación, se muestra un ejemplo con varias operaciones que crean un presupuesto de la campaña, una campaña y un grupo de anuncios en una solicitud atómica.

const operations = [];
const customerId = 'INSERT_CUSTOMER_ID_HERE';
const budgetId = `customers/${customerId}/campaignBudgets/-1`;
const campaignId = `customers/${customerId}/campaigns/-2`;
operations.push({
    campaignBudgetOperation: {
      create: {
        resourceName: budgetId,
        amountMicros: 10000000,
        explicitlyShared: false
      }
    }
  });
operations.push({
    campaignOperation: {
      create: {
        resourceName: campaignId,
        name: 'New Campaign ' + new Date(),
        advertisingChannelType: 'SEARCH',
        manualCpc: {},
        campaignBudget: budgetId,
        advertisingChannelType: 'DISPLAY',
        networkSettings: {
          targetContentNetwork: true
        }
      }
    }
  });
operations.push({
    adGroupOperation: {
      create: {
        campaign: campaignId,
        name: 'New AdGroup ' + new Date(),
        optimizedTargetingEnabled: true
      }
    }
  });
const results = AdsApp.mutateAll(
    operations, {partialFailure: false});