Las secuencias de comandos de Google Ads admiten 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 las secuencias de comandos de Google Ads, incluida la creación y administración de campañas.
Debido a que esta función permite el acceso a una gran parte de la API de Google Ads, es importante tener un conocimiento básico de las convenciones de la API de Google Ads para poder utilizar esta función. Puedes 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 crear una solicitud de mutación válida.
Estos son algunos recursos básicos sobre la interfaz REST de la API de Google Ads con los que debes 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 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 el tipo de operación que realizas; 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 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, luego, completar los campos correspondientes o escribir código JavaScript personalizado en tu secuencia de comandos para construir 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 solicitud de forma dinámica seleccionando 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 más arriba 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 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 deseas actualizar 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"
}
});
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ó de forma correcta o
qué errores se produjeron, si los hay.
Este es un ejemplo que muestra un flujo básico para verificar un resultado y, luego, imprimir cierta 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 dependen entre sí, como una jerarquía de campañas completa, en una sola solicitud. De manera opcional, puedes hacer que todo el conjunto de operaciones sea atómica, por lo que si alguna falla, no se realiza 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 igual 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 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 utiliza 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 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, incluidos los siguientes:
apiVersion: Puedes especificar una versión de API personalizada, comoV18, si deseas usar una versión distinta de la predeterminada de las secuencias de comandos. Puedes usar cualquier versión disponible de forma pública en ese momento.partialFailure: El valor predeterminado de este campo estrue. Si se establece entrue, se realizan operaciones válidas y las operaciones fallidas muestran errores. Si se configura comofalse, si alguna operación falla, no se realizan operaciones, lo que hace que este conjunto de operaciones sea atómica.
A continuación, se muestra un ejemplo con varias operaciones que crean un presupuesto, 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});