Modifica

Gli script Google Ads offrono il supporto per le modifiche 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 poterla utilizzare. Molti aspetti possono essere ignorati, come i token sviluppatore e l'autorizzazione, in quanto vengono gestiti per te dagli script Google Ads, ma devi formare una richiesta di mutazione valida.

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

Esempio di base

Per dimostrare la funzionalità, considera 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. All'interno di questo oggetto, specifica il tipo di operazione che stai eseguendo. In questo caso, un campaignBudgetOperation. Poi specifichi 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.

Crea un'operazione

Esistono alcune strategie che puoi utilizzare per creare un'operazione valida. Se prendiamo come esempio il budget della campagna, puoi consultare la documentazione di riferimento REST per il budget della campagna per visualizzare un elenco di tutti i 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 in modo dinamico utilizzando la funzionalità "Prova questa" per il budget della campagna, che ti consente di creare un corpo della richiesta in modo dinamico scegliendo i campi da aggiungere. Puoi quindi estrarre i contenuti dell'operazione dal risultato generato e aggiungerli 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 un esempio dell'operazione create.

Rimuovi

Specifica remove nell'operazione, passando il nome 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 per 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 per cui vuoi aggiornare i valori e specifica un updateMask che indichi esattamente i campi che intendi 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 attuale della risorsa dopo la mutazione e verificare se l'operazione è riuscita o quali errori si sono verificati, se presenti.

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 un'unica richiesta con il metodo AdsApp.mutateAll. Puoi creare entità dipendenti l'una dall'altra, ad esempio una gerarchia completa di campagne in una singola richiesta. Se vuoi, puoi rendere l'intero insieme di operazioni atomico, in modo che se una non va a buon fine, nessuna venga eseguita.

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

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

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

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

Di seguito è riportato un esempio con più operazioni che crea un budget della campagna, 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});