Modifica

Gli script Google Ads supportano le mutazioni generiche disponibili nell'API Google Ads. La maggior parte delle operazioni che possono essere eseguite da GoogleAdsService.mutate può essere eseguita anche negli script Google Ads, inclusa la creazione e la gestione delle campagne.

Poiché questa funzionalità consente l'accesso a una parte così ampia dell'API Google Ads, è importante avere una conoscenza di base delle convenzioni dell'API Google Ads per utilizzare questa funzionalità. Molti aspetti possono essere ignorati, ad esempio i token sviluppatore e l'autorizzazione, poiché vengono gestiti dagli script Google Ads, ma devi formare una richiesta di modifica valida.

Di seguito sono riportate alcune risorse di base sull'interfaccia REST dell'API Google Ads che dovresti conoscere prima di continuare con questa guida:

Esempio di base

Per dimostrare la funzionalità, prendi in considerazione questo esempio di base che crea un budget della campagna:

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

Una chiamata a AdsApp.mutate accetta un oggetto JSON che rappresenta un singolo MutateOperation. In questo oggetto, specifica il tipo di operazione che stai eseguendo, in questo caso un campaignBudgetOperation. Devi quindi specificare create, remove o entrambi update e updateMask. I campi specifici all'interno di create e update dipendono dal tipo specifico di risorsa su cui stai operando.

Creare un'operazione

Esistono alcune strategie che puoi utilizzare per creare un'operazione valida. Per rimanere nell'esempio del budget della campagna, puoi consultare la documentazione di riferimento REST per il budget della campagna per visualizzare un elenco di tutti i relativi campi validi, quindi compilare i campi appropriati o scrivere codice JavaScript personalizzato nello script per creare un oggetto appropriato.

In alternativa, puoi provare a creare un'operazione dinamicamente utilizzando la funzionalità "Prova" per il budget della campagna, che ti consente di creare dinamicamente un corpo della richiesta scegliendo i campi da aggiungere. Puoi quindi estrarre i contenuti dell'operazione dal risultato generato e aggiungerlo alla chiamata mutate dopo aver specificato il tipo di operazione.

Tipi di operazioni

Crea

Specifica create nell'operazione, passando una rappresentazione dell'oggetto della risorsa che vuoi creare.

Vedi sopra per un esempio dell'operazione create.

Rimuovi

Specifica remove nell'operazione, passando il nome della risorsa della risorsa che vuoi rimuovere, ad esempio:

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

Se non conosci il nome della risorsa di un'entità, puoi recuperarlo utilizzando una richiesta Adsapp.search.

Aggiorna

Specifica update nell'operazione, passando un oggetto con il nome della risorsa specificato in modo che il sistema possa determinare quale oggetto vuoi aggiornare. Inoltre, compila tutti i campi di cui vuoi aggiornare i valori e specifica un updateMask che indichi esattamente quali campi vuoi modificare in questa richiesta. Non includere il nome della risorsa nella maschera di aggiornamento.

Esempio di operazione update:

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

Gestione dei risultati

Indipendentemente dal tipo di operazione, il valore restituito è un MutateResult. Puoi utilizzare il nome della risorsa restituito per eseguire query sullo stato corrente della risorsa dopo la modifica e verificare se l'operazione è riuscita o se si sono verificati errori.

Ecco un esempio che mostra un flusso di base per controllare un risultato e stampare alcune informazioni nei log:

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

Più operazioni

Gli script Google Ads supportano anche la modifica di più operazioni in una singola richiesta con il metodo AdsApp.mutateAll. Puoi creare entità dipendenti l'una dall'altra, ad esempio una gerarchia completa della campagna in una singola richiesta. Se vuoi, puoi rendere atomico l'intero insieme di operazioni, in modo che se una non va a buon fine, non venga eseguita nessuna.

Il valore restituito è un array di oggetti MutateResult, uno per ogni operazione specificata e nello stesso ordine delle operazioni iniziali.

Questa funzionalità funziona come la funzionalità dell'API Google Ads, quindi consulta la guida alle best practice dell'API Google Ads per una spiegazione completa degli ID temporanei e altre considerazioni. Tieni presente che la guida utilizza snake_case per rappresentare i nomi dei campi, mentre la documentazione degli script Google Ads utilizza lowerCamelCase. Entrambi questi casi sono accettati negli script Google Ads, pertanto puoi copiare il codice direttamente dalla guida.

Per eseguire più operazioni in una singola richiesta, raccogli tutte le operazioni in un array e poi chiama AdsApp.mutateAll. La chiamata mutateAll prende l'array di operazioni come primo argomento e un secondo argomento facoltativo di opzioni, tra cui:

  • apiVersion: puoi specificare una versione dell'API personalizzata, ad esempio V18, se vuoi utilizzare una versione diversa da quella predefinita degli script. Puoi utilizzare qualsiasi versione disponibile pubblicamente al momento.
  • partialFailure: il valore predefinito di questo campo è true. Se impostato su true, vengono eseguite le operazioni valide e quelle non riuscite restituiscono errori. Se impostato su false, se un'operazione non va a buon fine, non viene eseguita alcuna operazione, rendendo in modo efficace questo insieme di operazioni atomico.

Di seguito è riportato un esempio con più operazioni che creano un budget, una campagna e un gruppo di annunci in una richiesta atomica.

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