Le service de ressources effectue des mutations

L'utilisation du service dédié d'une ressource est le moyen le plus direct de créer, de mettre à jour ou de supprimer des entités d'un seul type de ressource dans l'API Google Ads.

Points de terminaison de mutation

Chaque ressource mutable possède un service et un type d'opération correspondants. Pour modifier une ressource à l'aide de son service dédié, renseignez l'un des champs suivants de l'opération et envoyez-le au point de terminaison de modification du service :

  • Créer (create) : nouvel objet de ressource à créer.
  • Mise à jour (update) : objet de ressource modifié, accompagné d'un update_mask spécifiant les champs modifiés.
  • Supprimer (remove) : chaîne resource_name de la ressource cible à supprimer.

Par exemple, pour créer un Campaign, procédez comme suit :

  1. Construisez un objet Campaign avec les attributs de votre choix.
  2. Attribuez-le au champ create d'un CampaignOperation.
  3. Envoyez l'opération dans un MutateCampaignsRequest à CampaignService.MutateCampaigns.

Ce même schéma s'applique à tous les services spécifiques aux ressources de l'API Google Ads :

La charge utile JSON REST suivante illustre une requête CampaignService.MutateCampaigns :

{
  "customerId": "CUSTOMER_ID",
  "operations": [
    {
      "create": {
        "name": "Interplanetary Cruise #1",
        "advertisingChannelType": "SEARCH",
        "status": "PAUSED",
        "manualCpc": {},
        "campaignBudget": "customers/CUSTOMER_ID/campaignBudgets/BUDGET_ID",
        "containsEuPoliticalAdvertising": "DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING"
      }
    }
  ],
  "partialFailure": false,
  "validateOnly": false
}

Opérations multiples et limites

La plupart des requêtes de mutation spécifiques aux ressources acceptent un champ operations répété. Une seule requête peut donc contenir plusieurs opérations pour ce type de ressource (jusqu'à 10 000 opérations par requête, ou 20 000 pour AdGroupCriterionService.MutateAdGroupCriteria). CustomerService.MutateCustomer accepte un champ operation singulier. Par défaut, toutes les opérations de la requête s'exécutent de manière atomique, sauf si le service est compatible avec partial_failure et que vous le définissez sur true.

Toutefois, les services de ressources individuelles présentent deux limites importantes :

  • Type de ressource unique : une requête adressée à un service de ressources ne peut modifier que les ressources gérées par ce service spécifique.
  • Pas d'ID temporaires inter-ressources : étant donné qu'un appel mutate spécifique à une ressource n'accepte qu'un seul type de ressource, vous ne pouvez pas attribuer d'ID négatif temporaire à une ressource parente (telle que customers/CUSTOMER_ID/campaigns/-1) et y faire référence à partir d'une ressource enfant d'un type différent (telle que AdGroup) dans la même requête. (Les ID temporaires auto-référencés au sein du même type de ressource sont acceptés pour les arborescences hiérarchiques telles que les groupes de fiches AdGroupCriterion et les nœuds AssetGroupListingGroupFilter.)

Si vous devez modifier plusieurs types de ressources dans une même requête ou référencer des noms de ressources temporaires pour différents types de ressources, utilisez plutôt GoogleAdsService.Mutate.

Différences spécifiques aux versions

Lorsque vous modifiez des ressources, tenez compte de la différence suivante entre les versions compatibles de l'API Google Ads :

  • Services d'objectifs de cycle de vie : les objectifs de fidélisation des clients sont modifiés dans toutes les versions compatibles via GoalService.MutateGoals (retention_goal_settings) et CampaignGoalConfigService.MutateCampaignGoalConfigs (campaign_retention_settings) à l'aide d'un champ operations répété standard. Dans la version 25 et les versions ultérieures, les objectifs "Acquisition de nouveaux clients" (new_customer_acquisition_goal_settings/campaign_new_customer_acquisition_settings) et "Fidélisation des clients" (loyalty_retention_goal_settings / campaign_loyalty_retention_settings) sont également modifiés via GoalService.MutateGoals et CampaignGoalConfigService.MutateCampaignGoalConfigs. Cela remplace CustomerLifecycleGoalService.ConfigureCustomerLifecycleGoals et CampaignLifecycleGoalService.ConfigureCampaignLifecycleGoals, qui sont utilisés pour l'acquisition de nouveaux clients dans les versions 23 et 24 et acceptent un champ operation singulier.
Précédent
Aperçu
Suivant
Mutations groupées