Modificar

Las secuencias de comandos de Google Ads ofrecen compatibilidad con las modificaciones 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 las secuencias de comandos de Google Ads, incluidas la creación y la administración de campañas.

Debido a que esta función permite acceder a una porción 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. Muchos aspectos se pueden omitir, como los tokens de desarrollador y la autorización, ya que las secuencias de comandos de Google Ads se encargan de ellos, pero tienes que formar una solicitud de modificación válida.

A continuación, se presentan algunos recursos básicos sobre la interfaz REST de la API de Google Ads que debe conocer antes de continuar con esta guía:

Ejemplo básico

Para demostrar la funcionalidad, considera este ejemplo básico que crea un presupuesto de 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 realizas; en este caso, un campaignBudgetOperation. Luego, especifica create, remove o ambos, update y updateMask. Los campos específicos en create y update dependen del tipo específico de recurso en el que operas.

Compila una operación

Hay algunas estrategias que puedes usar para compilar una operación válida. Según el ejemplo del presupuesto de la campaña, puedes buscar la documentación de referencia de REST sobre el presupuesto de la campaña para ver una lista de todos sus campos válidos y, a continuación, completar los campos correspondientes o escribir código JavaScript personalizado en la secuencia de comandos para construir un objeto adecuado.

Como alternativa, podrías crear una operación de forma dinámica con la función"Prueba esto" para el presupuesto de la campaña, que te permite crear un cuerpo de solicitud de forma dinámica si eliges qué campos 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 arriba para ver un ejemplo de la operación create.

Quitar

Especifica remove en tu operación y pasa el nombre del recurso del recurso que deseas 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 mediante 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 para los que quieras actualizar los valores y especifica un 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"
    }
});

Controla los resultados

Sin importar el tipo de operación, el valor que se muestra es una 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 si se produjeron errores.

A continuación, te mostramos un ejemplo de un flujo básico para verificar un resultado y, luego, imprimir 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);
    }
}

Operaciones múltiples

Las secuencias de comandos de Google Ads también permiten mutar 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 forma opcional, puedes hacer que todo el conjunto de operaciones sea atómico, por lo que, si falla alguna, no se realizará 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 funciona de la misma manera que la función 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 en la guía se usa snake_case para representar nombres de campos, mientras que la documentación de secuencias de comandos de Google Ads usa lowerCamelCase. Ambos casos se aceptan en las secuencias de comandos de Google Ads, por lo que puedes copiar el código directamente desde esa guía.

Para realizar varias operaciones en una sola solicitud, recopila todas las 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 las siguientes opciones:

  • apiVersion: Puedes especificar una versión personalizada de la API, como V16, si deseas usar una versión que no sea 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 configura como true, se realizan operaciones válidas y las operaciones con errores muestran errores. Si se configura como false, si falla alguna operación, no se realizan operaciones, lo que hace que este conjunto de operaciones sea atómico.

A continuación, te mostramos un ejemplo con varias operaciones que crean un presupuesto, una campaña y un grupo de anuncios de una campaña 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});