Modifica

Gli script Google Ads offrono supporto per 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 utilizzarla. Molti aspetti possono essere ignorati, come i token sviluppatore e l'autorizzazione, poiché vengono gestiti dagli script Google Ads, ma devi formare una richiesta di mutazione valida.

Ecco 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à, 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, specifichi 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.

Creare un'operazione

Esistono alcune strategie che puoi utilizzare per creare un'operazione valida. Continuando con l'esempio del 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 "Prova" per il budget della campagna, che ti consente di creare un corpo della richiesta in modo dinamico scegliendo i campi che vuoi 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.

Per un esempio dell'operazione create, consulta lo snippet fornito in precedenza.

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 l'oggetto che vuoi aggiornare. Inoltre, compila tutti i campi per i quali vuoi aggiornare i valori e specifica un updateMask che indica esattamente i campi che intendi modificare in questa richiesta. Non includere il nome della risorsa nella maschera di aggiornamento.

Esempio di un'operazione update:

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

Gestire i risultati

Indipendentemente dal tipo di operazione, il valore restituito è un MutateResult. Puoi utilizzare il nome della risorsa restituito per eseguire una query sullo stato attuale della risorsa dopo la mutazione e verificare se l'operazione è andata a buon fine 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 mutazione di più operazioni in una singola richiesta con il AdsApp.mutateAll metodo. Puoi creare entità dipendenti l'una dall'altra, ad esempio una gerarchia di campagne completa in una singola richiesta. Facoltativamente, puoi rendere atomico l'intero insieme di operazioni, in modo che se una non va a buon fine, non venga eseguita alcuna operazione.

Il valore restituito è un array di MutateResult oggetti, uno per ogni operazione fornita 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 di 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, quindi puoi copiare il codice direttamente da questa guida.

Per eseguire più operazioni in una singola 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 V24, se vuoi utilizzare una versione diversa da quella predefinita degli script. Puoi utilizzare qualsiasi versione disponibile pubblicamente al momento.
  • partialFailure: questo campo è impostato su true per impostazione predefinita. Se è impostato su true, le operazioni valide vengono eseguite e le operazioni non riuscite restituiscono errori. Se è impostato su false, se un'operazione non va a buon fine, non viene eseguita alcuna operazione, rendendo di fatto atomico questo insieme di operazioni.

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