Method: customers.googleAds.mutate

Crée, met à jour ou supprime des ressources. Cette méthode est compatible avec les transactions atomiques avec plusieurs types de ressources. Par exemple, vous pouvez créer de manière atomique une campagne et un budget de campagne, ou effectuer jusqu'à des milliers de modifications de manière atomique.

Cette méthode est essentiellement un wrapper autour d'une série de méthodes de mutation. Les seules fonctionnalités qu'il offre par rapport à l'appel direct de ces méthodes sont les suivantes:

  • Transactions atomiques
  • Noms de ressources temporaires (décrits ci-dessous)
  • Latence quelque peu réduite par rapport à l'envoi d'une série d'appels de modification

Remarque: Seules les ressources compatibles avec les transactions atomiques sont incluses. Par conséquent, cette méthode ne peut pas remplacer tous les appels à des services individuels.

Avantages des transactions atomiques

L'atomicité facilite grandement la gestion des erreurs. Si vous effectuez une série de modifications et que l'une d'elles échoue, votre compte peut se retrouver dans un état incohérent. Avec l'atomicité, vous atteignez directement l'état choisi, ou la requête échoue et vous pouvez réessayer.

Noms de ressources temporaires

Les noms de ressources temporaires sont un type spécial de nom de ressource utilisé pour créer une ressource et la référencer dans la même requête. Par exemple, si un budget de campagne est créé avec resourceName égal à customers/123/campaignBudgets/-1, ce nom de ressource peut être réutilisé dans le champ Campaign.budget de la même requête. Les deux ressources sont ainsi créées et associées de manière atomique.

Pour créer un nom de ressource temporaire, saisissez un nombre négatif dans la partie du nom que le serveur attribue normalement.

Remarque :

  • Les ressources doivent être créées avec un nom temporaire avant de pouvoir être réutilisées. Par exemple, l'exemple CampaignBudget+Campaign précédent échouerait si l'ordre de modification était inversé.
  • Les noms temporaires ne sont pas mémorisés entre les requêtes.
  • Le nombre de noms temporaires dans une requête n'est pas limité.
  • Chaque nom temporaire doit utiliser un nombre négatif unique, même si les types de ressources sont différents.

Latence

Il est important de regrouper les mutations par type de ressource, sinon la requête risque de dépasser le délai avant expiration et d'échouer. La latence est à peu près égale à une série d'appels de méthodes de mutation individuelles, où chaque changement de type de ressource correspond à un nouvel appel. Par exemple, modifier 10 campagnes, puis 10 groupes d'annonces équivaut à deux appels, tandis que modifier une campagne, un groupe d'annonces, une campagne, un groupe d'annonces équivaut à quatre appels.

Liste des erreurs générées: 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

Requête HTTP

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

L'URL utilise la syntaxe de transcodage gRPC.

Paramètres de chemin d'accès

Paramètres
customerId

string

Obligatoire. ID du client dont les ressources sont modifiées.

Corps de la requête

Le corps de la requête contient des données présentant la structure suivante :

Représentation JSON 
{
  "mutateOperations": [
    {
      object (MutateOperation)
    }
  ],
  "partialFailure": boolean,
  "validateOnly": boolean,
  "responseContentType": enum (ResponseContentType)
}
Champs
mutateOperations[]

object (MutateOperation)

Obligatoire. Liste des opérations à effectuer sur des ressources individuelles.
partialFailure

boolean

Si la valeur est définie sur "true", les opérations réussies sont effectuées et les opérations non valides renvoient des erreurs. Si la valeur est "false", toutes les opérations sont effectuées dans une seule transaction si et seulement si elles sont toutes valides. La valeur par défaut est "false".
validateOnly

boolean

Si la valeur est "true", la requête est validée, mais pas exécutée. Seules les erreurs sont renvoyées, et non les résultats.
responseContentType

enum (ResponseContentType)

Paramètre du type de contenu de la réponse. Détermine si la ressource modifiable ou uniquement le nom de la ressource doit être renvoyé après la mutation. La ressource modifiable n'est renvoyée que si elle comporte le champ de réponse approprié. Par exemple, MutateCampaignResult.campaign.

Corps de la réponse

Message de réponse pour GoogleAdsService.Mutate.

Si la requête aboutit, le corps de la réponse contient des données qui ont la structure suivante :

Représentation JSON 
{
  "partialFailureError": {
    object (Status)
  },
  "mutateOperationResponses": [
    {
      object (MutateOperationResponse)
    }
  ]
}
Champs
partialFailureError

object (Status)

Erreurs liées aux échecs d'opérations en mode échec partiel. N'est renvoyé que lorsque "partialFailure" est défini sur "true" et que toutes les erreurs se produisent dans les opérations. Si des erreurs se produisent en dehors des opérations (par exemple, des erreurs d'authentification), nous renvoyons une erreur au niveau de l'RPC.
mutateOperationResponses[]

object (MutateOperationResponse)

Toutes les réponses pour la mutation.

Champs d'application des autorisations

Requiert le niveau d'accès OAuth suivant :

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

Pour en savoir plus, consultez OAuth 2.0 Overview.