Modifica

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

Poiché questa funzionalità consente di accedere a una porzione così grande dell'API Google Ads, è importante conoscere le nozioni di base delle convenzioni dell'API Google Ads per utilizzarla. Molti aspetti, come i token sviluppatore e le autorizzazioni, vengono gestiti automaticamente dagli script Google Ads, ma devi creare una richiesta di modifica valida.

Di seguito sono riportate alcune risorse di base dell'interfaccia REST dell'API Google Ads che dovresti conoscere prima di continuare con la 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 richiede un oggetto JSON che rappresenta un singolo MutateOperation. All'interno dell'oggetto, specifichi il tipo di operazione che stai eseguendo, in questo caso un campaignBudgetOperation. Puoi 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.

Crea un'operazione

Esistono alcune strategie che puoi adottare per creare un'operazione valida. Attenendoti all'esempio di budget della campagna, potresti cercare 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, potresti provare a creare un'operazione in modo dinamico utilizzando la funzionalità "Prova questo" per il budget della campagna, che consente di creare dinamicamente un corpo della richiesta selezionando e 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, trasmettendo una rappresentazione dell'oggetto della risorsa che vuoi creare.

Qui sopra è riportato un esempio dell'operazione create.

Rimuovi

Specifica remove nell'operazione, passando il nome 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 recuperarla 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 quali campi 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"
    }
});

Gestione dei risultati

Indipendentemente dal tipo di operazione, il valore restituito è MutateResult. Puoi utilizzare il nome della risorsa restituito per eseguire una query sullo stato attuale 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 rendere le entità dipendenti l'una dall'altra, ad esempio una gerarchia completa di campagne in una singola richiesta. Facoltativamente, puoi rendere atomico l'intero insieme di operazioni, quindi se una di queste non funziona, non ne viene eseguita nessuna.

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

Questa funzionalità funziona nello stesso modo dell'API Google Ads, perciò 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 i casi sono accettati negli script Google Ads, quindi puoi copiare il codice direttamente dalla guida.

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

  • apiVersion: puoi specificare una versione personalizzata dell'API, ad esempio V16, se vuoi utilizzare una versione diversa da quella predefinita degli script. Puoi utilizzare qualsiasi versione disponibile pubblicamente del momento.
  • partialFailure: l'impostazione predefinita di questo campo è true. Se il criterio viene impostato su true, vengono eseguite le operazioni valide e quelle non riuscite restituiscono errori. Se il criterio è impostato su false, in caso di errore di una o più operazioni, non vengono eseguite operazioni, il che rende di fatto questo insieme di operazioni atomico.

Di seguito è riportato un esempio con più operazioni che creano un budget, una campagna e un gruppo di annunci della campagna 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});