Method: customers.googleAds.mutate

Crée, met à jour ou supprime des ressources. Cette méthode accepte 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 mutate. Les seules fonctionnalités qu'il offre par rapport à l'appel direct de ces méthodes sont les suivants:

  • Transactions atomiques
  • Noms de ressources temporaires (décrits ci-dessous)
  • Latence légèrement réduite par rapport à une série d'appels mutate.

Remarque: Seules les ressources acceptant les transactions atomiques sont incluses. Cette méthode ne peut donc pas remplacer tous les appels de services individuels.

Avantages des transactions atomiques

L'atomicité facilite grandement le traitement des erreurs. Si vous apportez plusieurs modifications et que l'une d'entre elles échoue, votre compte risque de ne pas fonctionner correctement. 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 vous créez un budget de campagne avec une resourceName égale à customers/123/campaignBudgets/-1, ce nom de ressource peut être réutilisé dans le champ Campaign.budget de la même demande. De cette façon, les deux ressources sont créées et liées de manière atomique.

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

Remarque :

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

Latence

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

{0122020320330333333ErrorError.3.4.222222444str messages(4) des erreurs suivantesAdCustomizerErrorAdErrorAdGroupAdErrorAdGroupCriterionErrorAdGroupErrorAssetErrorAuthenticationErrorAuthorizationErrorBiddingErrorCampaignBudgetErrorCampaignCriterionErrorCampaignErrorCampaignExperimentErrorCampaignSharedSetErrorCollectionSizeErrorContextErrorConversionActionErrorCriterionErrorCustomerFeedErrorDatabaseErrorDateErrorDateRangeErrorDistinctErrorExtensionFeedItemErrorExtensionSettingErrorFeedAttributeReferenceErrorFeedErrorFeedItemErrorFeedItemSetErrorFieldErrorFieldMaskErrorFunctionParsingErrorHeaderErrorImageErrorInternalErrorKeywordPlanAdGroupKeywordErrorKeywordPlanCampaignErrorKeywordPlanErrorLabelErrorListOperationErrorMediaUploadErrorMutateErrorNewResourceCreationErrorNullErrorOperationAccessDeniedErrorPolicyFindingErrorPolicyViolationErrorQuotaErrorRangeErrorRequestErrorResourceCountLimitExceededErrorSettingErrorSharedSetErrorSizeLimitErrorStringFormatErrorStringLengthErrorUrlFieldErrorUserListErrorYoutubeVideoRegistrationError

Requête HTTP

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

L'URL utilise la syntaxe de transcodage gRPC.

Paramètres de chemin d'accès

Paramètres
customerId

string

Obligatoire. Identifiant du client dont les ressources sont en cours de modification.

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 "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 seront effectuées en 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, pas les résultats.
responseContentType

enum (ResponseContentType)

Paramètre de type de contenu de la réponse. Détermine si la ressource modifiable ou uniquement son nom doit être renvoyé après la mutation. La ressource modifiable n'est renvoyée que si elle possède 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ération en mode d'échec partiel. Renvoyée uniquement lorsque partialFailure = true et que toutes les erreurs se produisent dans les opérations. Si des erreurs se produisent en dehors des opérations (erreurs d'authentification, par exemple), nous renvoyons une erreur au niveau du RPC.
mutateOperationResponses[]

object (MutateOperationResponse)

Toutes les réponses pour le mutate.

Champs d'application des autorisations

Requiert le niveau d'accès OAuth suivant :

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

Pour en savoir plus, consultez la présentation d'OAuth 2.0.