Method: customers.googleAds.mutate

Crea, aggiorna o rimuove le risorse. Questo metodo supporta transazioni atomiche con più tipi di risorse. Ad esempio, puoi creare in modo atomico una campagna e un budget della campagna oppure eseguire fino a migliaia di mutazioni in modo atomico.

Questo metodo è essenzialmente un wrapper per una serie di metodi di mutazione. Le uniche funzionalità offerte rispetto alla chiamata diretta di questi metodi sono:

  • Transazioni atomiche
  • Nomi delle risorse temporanee (descritti di seguito)
  • Latenza leggermente ridotta rispetto all'esecuzione di una serie di chiamate mutate

Nota: vengono incluse solo le risorse che supportano le transazioni atomiche, pertanto questo metodo non può sostituire tutte le chiamate ai singoli servizi.

Vantaggi delle transazioni atomiche

L'atomicità semplifica notevolmente la gestione degli errori. Se apporti una serie di modifiche e una non va a buon fine, il tuo account potrebbe risultare in uno stato incoerente. Con l'atomicità, raggiungi direttamente lo stato scelto oppure la richiesta non va a buon fine e puoi riprovare.

Nomi delle risorse temporanee

I nomi delle risorse temporanee sono un tipo speciale di nome di risorsa utilizzato per creare una risorsa e fare riferimento a quella risorsa nella stessa richiesta. Ad esempio, se viene creato un budget della campagna con resourceName uguale a customers/123/campaignBudgets/-1, il nome della risorsa può essere riutilizzato nel campo Campaign.budget nella stessa richiesta. In questo modo, le due risorse vengono create e collegate in modo atomico.

Per creare un nome della risorsa temporanea, inserisci un numero negativo nella parte del nome che normalmente viene allocata dal server.

Nota:

  • Le risorse devono essere create con un nome temporaneo prima che il nome possa essere riutilizzato. Ad esempio, l'esempio precedente CampaignBudget+Campaign non andrebbe a buon fine se l'ordine di mutazione fosse invertito.
  • I nomi temporanei non vengono memorizzati nelle richieste successive.
  • Non esiste un limite al numero di nomi temporanei in una richiesta.
  • Ogni nome temporaneo deve utilizzare un numero negativo univoco, anche se i tipi di risorse sono diversi.

Latenza

È importante raggruppare le mutazioni per tipo di risorsa, altrimenti la richiesta potrebbe scadere e non andare a buon fine. La latenza è approssimativamente uguale a una serie di chiamate a singoli metodi di mutazione, in cui ogni modifica del tipo di risorsa corrisponde a una nuova chiamata. Ad esempio, la mutazione di 10 campagne e poi di 10 gruppi di annunci equivale a 2 chiamate, mentre la mutazione di 1 campagna, 1 gruppo di annunci, 1 campagna, 1 gruppo di annunci equivale a 4 chiamate.

Elenco degli errori generati: AdCustomizerError AdError AdGroupAdError AdGroupCriterionError AdGroupError AssetError AuthenticationError AuthorizationError BiddingError CampaignBudgetError CampaignCriterionError CampaignError CampaignExperimentError CampaignSharedSetError CollectionSizeError ContextError ConversionActionError CriterionError CustomerFeedError DatabaseError DateError DateRangeError DistinctError ExtensionFeedItemError ExtensionSettingError FeedAttributeReferenceError FeedError FeedItemError FeedItemSetError FieldError FieldMaskError FunctionParsingError HeaderError ImageError InternalError KeywordPlanAdGroupKeywordError KeywordPlanCampaignError KeywordPlanError LabelError ListOperationError MediaUploadError MutateError NewResourceCreationError NullError OperationAccessDeniedError PolicyFindingError PolicyViolationError QuotaError RangeError RequestError ResourceCountLimitExceededError SettingError SharedSetError SizeLimitError StringFormatError StringLengthError UrlFieldError UserListError YoutubeVideoRegistrationError

Richiesta HTTP

POST https://googleads.googleapis.com/v19/customers/{customerId}/googleAds:mutate

L'URL utilizza la sintassi di transcodifica gRPC.

Parametri del percorso

Parametri
customerId

string

Obbligatorio. L'ID del cliente di cui vengono modificate le risorse.

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

Rappresentazione JSON 
{
  "mutateOperations": [
    {
      object (MutateOperation)
    }
  ],
  "partialFailure": boolean,
  "validateOnly": boolean,
  "responseContentType": enum (ResponseContentType)
}
Campi
mutateOperations[]

object (MutateOperation)

Obbligatorio. L'elenco delle operazioni da eseguire sulle singole risorse.
partialFailure

boolean

Se è true, verranno eseguite le operazioni riuscite e quelle non valide restituiranno errori. Se false, tutte le operazioni verranno eseguite in un'unica transazione se e solo se sono tutte valide. Il valore predefinito è false.
validateOnly

boolean

Se è true, la richiesta viene convalidata, ma non eseguita. Vengono restituiti solo gli errori, non i risultati.
responseContentType

enum (ResponseContentType)

L'impostazione del tipo di contenuto della risposta. Determina se la risorsa mutabile o solo il nome della risorsa deve essere restituita dopo la mutazione. La risorsa mutabile verrà restituita solo se ha il campo di risposta appropriato. Ad esempio, MutateCampaignResult.campaign.

Corpo della risposta

Messaggio di risposta per GoogleAdsService.Mutate.

In caso di esito positivo, il corpo della risposta contiene dati con la seguente struttura:

Rappresentazione JSON 
{
  "partialFailureError": {
    object (Status)
  },
  "mutateOperationResponses": [
    {
      object (MutateOperationResponse)
    }
  ]
}
Campi
partialFailureError

object (Status)

Errori relativi a errori di operazione nella modalità di errore parziale. Viene restituito solo quando partialFailure = true e tutti gli errori si verificano all'interno delle operazioni. Se si verificano errori al di fuori delle operazioni (ad esempio errori di autenticazione), viene restituito un errore a livello di RPC.
mutateOperationResponses[]

object (MutateOperationResponse)

Tutte le risposte per la mutazione.

Ambiti di autorizzazione

Richiede il seguente ambito OAuth:

  • https://www.googleapis.com/auth/adwords

Per ulteriori informazioni, consulta la sezione OAuth 2.0 Overview.