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 modifiable est associée à un service et à un type d'opération. 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. Créez un objet Campaign avec les attributs de votre choix.
  2. Attribuez-le au champ create d'un CampaignOperation.
  3. Envoyez l'opération dans une requête MutateCampaignsRequest à CampaignService.MutateCampaigns.

Ce même modèle s'applique à tous les services spécifiques aux ressources dans l'API Google Ads :

La charge utile JSON REST suivante illustre une requête adressée à 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 modification spécifiques à une ressource acceptent un champ operations répété. Une même 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 individuels 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 entre les ressources : comme un appel de modification 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 (comme customers/CUSTOMER_ID/campaigns/-1) et la référencer à partir d'une ressource enfant d'un autre type (comme AdGroup) dans la même requête. (Les ID temporaires autoré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 dans différents types de ressources, utilisez plutôt GoogleAdsService.Mutate.

Différences selon les 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 rétention client 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, l'acquisition de nouveaux clients (new_customer_acquisition_goal_settings/campaign_new_customer_acquisition_settings) et la fidélisation (loyalty_retention_goal_settings/campaign_loyalty_retention_settings) sont également modifiées 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 seul champ operation.
Précédent
Aperçu
Suivant
Mutations groupées