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

Étant donné que le champ operations d'une requête de modification est répété, une seule requête peut contenir plusieurs opérations (jusqu'à 10 000 opérations par requête) pour ce type de ressource. Par défaut, toutes les opérations de la requête s'exécutent de manière atomique, sauf si vous définissez partial_failure 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 de ressources temporaires ni de références croisées : les opérations d'un appel de mutation spécifique à une ressource sont traitées indépendamment. Vous ne pouvez pas attribuer d'ID négatifs temporaires (tels que customers/CUSTOMER_ID/campaigns/-1) ni faire référence à des entités nouvellement créées à partir d'autres opérations dans la même requête.

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

Différences spécifiques aux versions

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

  • Services d'objectif de cycle de vie : dans la version 25 et les versions ultérieures, tous les objectifs de cycle de vie (y compris l'acquisition de nouveaux clients (new_customer_acquisition_goal_settings), la fidélisation des clients (retention_goal_settings) et la fidélisation (loyalty_retention_goal_settings)) sont mutés via GoalService.MutateGoals et CampaignGoalConfigService.MutateCampaignGoalConfigs à l'aide d'un champ operations répété standard. Il remplace CustomerLifecycleGoalService.ConfigureCustomerLifecycleGoals et CampaignLifecycleGoalService.ConfigureCampaignLifecycleGoals (qui sont utilisés pour l'acquisition de nouveaux clients dans la version 24 et les versions antérieures, et qui acceptent un champ operation singulier).
  • Champs de date et d'heure des campagnes : lorsque vous créez ou mettez à jour un Campaign, la version 23 et les versions ultérieures utilisent start_date_time et end_date_time (yyyy-MM-dd HH:mm:ss), en remplacement des champs start_date et end_date utilisés dans la version 22.
  • Mutabilité de l'attestation de contenu synthétique : bien que Asset.synthetic_content_info et Ad.synthetic_content_info apparaissent dans le schéma pour la version 22 et les versions ultérieures, les champs synthetic_content_info.advertiser_attestation.status et synthetic_content_info.advertiser_attestation.source ne sont mutables que dans la version 23 et les versions ultérieures (system_attestation est toujours OUTPUT_ONLY). Toute tentative de mutation des sous-champs advertiser_attestation dans la version 22 renvoie une erreur de champ immuable ("The field attempted to be mutated is immutable" ou "Field cannot be set").
Précédent
Aperçu
Suivant
Mutations groupées