Changement

La plupart des ressources sont modifiées (créées, mises à jour ou supprimées) à l'aide d'une méthode Mutate. La méthode Mutate est appelée en tant que POST HTTP sur une URL spécifique à une ressource qui correspond au modèle de nom de ressource, sans l'ID de ressource de fin. Les ID des ressources à modifier sont envoyés dans le corps de la requête JSON. Cela vous permet d'envoyer un seul appel d'API contenant plusieurs opérations sur différentes ressources.

Par exemple, le nom de ressource d'une campagne utilise le format suivant :

customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID

Pour obtenir l'URL utilisée pour modifier les campagnes, omettez l'ID de ressource de fin et ajoutez :mutate :

https://googleads.googleapis.com/v20/customers/CUSTOMER_ID/campaigns:mutate

Un message Mutate contient un objet JSON de premier niveau avec un tableau operations pouvant contenir de nombreux objets operation. Chaque opération peut être l'une des suivantes : create, update ou remove. Il s'agit des seules opérations de mutation possibles.

POST /v20/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
  "operations": [
    ...
  ]
}

La plupart des services acceptent des milliers d'opérations dans un seul appel d'API. Le guide Limites du système documente les limites de taille des requêtes.

Par défaut, les opérations d'une même requête API sont exécutées en tant qu'ensemble d'actions. Cela signifie qu'elles réussissent toutes ensemble ou que l'ensemble du lot échoue si une seule opération échoue. Certains services sont compatibles avec un attribut partialFailure permettant de modifier ce comportement. Pour en savoir plus sur la sémantique des opérations de mutation, consultez Ressources de mutation.

Créer

Les opérations de création produisent de nouvelles entités et doivent inclure une représentation JSON complète de la ressource que vous souhaitez créer.

POST /v20/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
  "operations": [
    {
    "create": {
        "name": "An example campaign",
        "status": "PAUSED",
        "campaignBudget": "customers/CUSTOMER_ID/campaignBudgets/CAMPAIGN_BUDGET_ID",
        "advertisingChannelType": "SEARCH",
        "networkSettings": {
          "targetGoogleSearch": true,
          "targetSearchNetwork": true,
          "targetContentNetwork": true,
          "targetPartnerSearchNetwork": false
        },
        "target_spend": {}
      }
    }
  ]
}

Mettre à jour

Les opérations de mise à jour effectuent des mises à jour éparses d'une ressource existante. Il vous suffit de spécifier les champs que vous souhaitez modifier.

Pour spécifier les champs que vous souhaitez mettre à jour, définissez l'attribut updateMask sur une liste de noms de champs séparés par une virgule. Cela est particulièrement utile si vous disposez déjà d'une représentation JSON complète d'un objet (par exemple, telle qu'elle est renvoyée par un appel d'API précédent), mais que vous ne souhaitez modifier que certains champs. Au lieu d'élaguer l'objet JSON, vous pouvez simplement lister les noms de champs à modifier dans updateMask et envoyer l'objet JSON entier.

L'exemple ci-dessous modifie le name et le status d'une campagne existante ayant le resourceName donné.

POST /v20/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
  "operations": [
    {
      "updateMask": "name,status",
      "update": {
        "resourceName": "customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID",
        "name": "My renamed campaign",
        "status": "PAUSED",
      }
    }
  ]
}

Supprimer

Les opérations de suppression suppriment efficacement un objet et définissent son état Google Ads sur REMOVED. Seul le resourceName à supprimer est requis.

POST /v20/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
  "operations": [
    {
      "remove": "customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID"
    }
  ]
}