Suivez votre progression
Accueil Trailhead
Accueil Trailhead

Suppression de contacts avec l’API REST

Objectifs de formation

Une fois cette unité terminée, vous pourrez :

  • Supprimer des contacts par lots à l’aide de l’API REST
  • Obtenir le statut des requêtes de suppression des contacts
  • Résoudre les problèmes liés aux requêtes de suppression des contacts

Amélioration de l’efficacité de la suppression des contacts

Il est assez simple de supprimer un ou deux contacts directement depuis Marketing Cloud, mais si vous devez en supprimer un plus grand nombre, le processus peut rapidement devenir fastidieux. Ainsi, bien que la limite par lot de requêtes soit d’un million de contacts, nous ne nous attendons pas à ce que vous sélectionniez ce nombre de contacts manuellement. Donc, si vous devez supprimer un grand nombre de contacts (et que vous vous êtes bien assuré auparavant qu’il est judicieux d’en supprimer), Marketing Cloud vous propose plusieurs ressources API REST afin d’y parvenir.

Activation de la suppression des contacts

N’oubliez pas que la suppression des contacts doit être activée avant de commencer. Reportez-vous à l’unité précédente si vous avez besoin d’un rappel sur la façon de procéder. De même, vous pouvez modifier la période de suppression pour votre compte grâce à la ressource configSettings, comme présenté dans cet exemple.

Exemple : configuration de la période de suppression de la suppression des contacts

Cet exemple définit la valeur sur 0 jour (en utilisant une valeur de -1), ce qui équivaut à une suppression immédiate.

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /contacts/v1/contacts/actions/delete/configSettings
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
   "items" : [{
      "settingKey" : "SuppressionRestoreUntilDays",
      "value" : "-1"
      }
   ]

Sélection du mode de suppression des contacts avec une API REST

Maintenant que la suppression des contacts est activée pour votre compte, vous avez le choix entre trois valeurs différentes pour sélectionner les contacts à supprimer : les ID de contact, les clés de contact ou les extensions de données. Examinons chacune d’entre elles de plus près, avec un exemple de code. 

ID de contact

Si vous choisissez de supprimer des contacts à l’aide d’une valeur d’ID de contact, vous devez transmettre les valeurs dans un tableau, comme indiqué dans cet exemple.

Exemple : suppression de contacts par ID de contact

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /contacts/v1/contacts/actions/delete?type=ids
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
   "values": [12345678, 12345679],
    "DeleteOperationType": "ContactAndAttributes"
}

Clés de contact

Si vous choisissez de supprimer des contacts à l’aide de la valeur ContactKey, vous devez également transmettre ces valeurs dans un tableau.

Exemple : suppression de contacts par clé de contact

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /contacts/v1/contacts/actions/delete?type=keys
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
   "values": [
      "TEST_317-531-5555", "TEST_317-531-5556"
      ],
   "DeleteOperationType": "ContactAndAttributes"
}

Extensions de données

Vous pouvez également choisir de supprimer tous les contacts contenus dans une extension de données spécifique. N’oubliez pas que cette opération supprime de toutes les extensions de données expédiables les enregistrements de contact figurant dans cette extension de données. Cela inclut les extensions de données réalisant des envois en fonction des valeurs Clé de contact, ID de contact et Adresse e-mail. Vous pouvez également décider de supprimer entièrement l’extension de données lorsque vous avez terminé. De nombreuses possibilités s’offrent à vous ! 

Ce processus crée une requête asynchrone pour votre lot de requêtes de suppression. Vous pouvez contacter votre gestionnaire de compte Marketing Cloud pour en savoir plus sur la configuration des limitations des requêtes de suppression dans votre compte.

Remarque

Remarque

Vous devez indiquer que vous supprimez une extension de données et fournir la clé externe lui correspondant. De plus, vous ne pouvez pas supprimer des extensions de données synchronisées. Vous pouvez les utiliser afin de permettre l’identification des contacts à supprimer, mais l’extension de données en elle-même continuera d’exister.

Exemple : suppression de contacts à l’aide d’une extension de données

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /contacts/v1/contacts/actions/delete?type=listReference
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
   "deleteOperationType": "ContactAndAttributes",
   "targetList": {
      "listType": {
         "listTypeID": 3
      },
   "listKey": "ContactListDeleteSource_as_DataExtension"
   },
   "deleteListWhenCompleted": false,
   "deleteListContentsWhenCompleted": false
}

Vérification de vos requêtes

Comme nous l’avons indiqué, l’exécution des requêtes de suppression des contacts prend un certain temps. Cela peut en effet durer plusieurs heures, selon le nombre de contacts que vous avez inclus dans votre requête, le nombre de requêtes que vous avez faites et d’autres facteurs propres au système. Cependant, vous pouvez vous tenir informé de la progression de vos requêtes en utilisant la valeur OperationID. Chaque demande de suppression de contact renvoie une valeur OperationID que vous pouvez utiliser pour récupérer l’ensemble des informations disponibles. Vous trouvez ci-dessous quelques exemples de requêtes.

Exemple : obtention du statut d’une requête de suppression des contacts spécifique

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
GET /contacts/v1/contacts/actions/delete/status?operationID=IDVALUEHERE
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

Cet exemple de réponse affiche les informations d’un contact supprimé.

{
   "operation": {
      "listTypeID": 3,
      "listIdentifier": "037c2811-ce62-4381-b3d2-1936e51fbf4d",
      "listKey": "037c2811-ce62-4381-b3d2-1936e51fbf4d",
      "expectedListCount": 1,
      "deleteType": "ContactAndAttributes",
      "deleteListOnCompleted": false,
      "operationID": 2,
      "eID": 12345,
      "mID": 12345,
      "employeeID": 30980,
      "operationRequestID": "21d0d10d-a15a-413c-bc3e-8b43b185e551",
      "status": "Completed",
      "scheduledTime": "2016-06-14T16:01:58.107",
      "retryCount": 0,
      "createdDate": "2016-06-14T16:02:00",
      "createdBy": 30980,
      "modifiedDate": "2016-06-14T16:02:00",
      "modifiedBy": 30980
    },
    "requestServiceMessageID": "93631be1-107f-4239-a8b7-cdae245d7403",
    "resultMessages": [],
    "serviceMessageID": "00e6add8-d79a-4bd6-9568-2f2a272538f0"
}

Exemple : récupération des requêtes de suppression des contacts par date

Vous pouvez également récupérer un récapitulatif des requêtes effectuées au cours d’une plage de dates spécifiée. 

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
GET contacts/v1/contacts/analytics/deleterequests?startdateutc=2019-02-18T00%3A00%3A00&enddateutc=2019-03-19T00%3A00%3A00&%24page=1&%24pagesize=20&%24orderby=operationId%20desc&statusid=5
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{

La réponse comporte les valeurs OperationID et de brefs récapitulatifs pour toutes les requêtes éligibles. Pour obtenir des informations plus précises, utilisez la valeur OperationID à l’aide de la ressource /contacts/v1/contacts/actions/delete/status?operationID=.

"startDateUtc":"2019-02-18T00:00:00",
"endDateUtc":"2019-03-19T00:00:00",
"statusAsOfDateUtc":"2019-03-19T19:33:17.496471Z",
"pageNumber":1,
"pageSize":20,
"operations":[
   {
      "operationId":22944,
      "totalContactCount":1,
      "completedContactCount":1,
      "receivedDateUtc":"2019-03-04T22:42:00",
      "status":"Completed",
      "lastStatusDateUtc":"2019-03-19T04:47:40.293",
      "deleteMethod":"Contact Key/ID"
   },
   {
      "operationId":22943,
      "totalContactCount":1,
      "completedContactCount":1,
      "receivedDateUtc":"2019-03-04T22:41:00",
      "status":"Completed",
      "lastStatusDateUtc":"2019-03-19T04:47:40.293",
      "deleteMethod":"Contact Key/ID"
   },
   {
      "operationId":22625,
      "totalContactCount":1,
      "completedContactCount":1,
      "receivedDateUtc":"2019-02-26T23:26:00",
      "status":"Completed",
      "lastStatusDateUtc":"2019-03-13T10:10:17.9",
      "deleteMethod":"Contact Key/ID"
   }
   ],
   "requestServiceMessageID":"e1198208-6432-40fd-b5ae-172c9d9bc44a",
   "responseDateTime":"2019-03-19T13:33:18.2141124-06:00",
   "resultMessages":[],
   "serviceMessageID":"ef7d833c-509f-4dbc-8f99-060aac3c0382"
}

Exemple : récupération d’un récapitulatif des requêtes de suppression des contacts

Cet exemple présente un récapitulatif des rapports de statut pour toutes les requêtes au cours de la période spécifiée.

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
GET contacts/v1/contacts/analytics/deleterequests/summary?startdateutc=2018-01-15T00:00:00Z&enddateutc=2018-01-15T05:00:00Z
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

La réponse donnée en exemple répartit les requêtes selon leur statut (terminées, en cours de traitement ou non valides).

{
   "startdateutc":"2018-01-15T00:00:00Z",
   "enddateutc":"2018-01-15T04:30:00Z",
   "statusofdateutc": "2018-01-17T04:30:00Z",
   "interval":"0",
   "itemcount":5,
   "totaltimeseries":[
      {
         "requestcount":500,
         "minvalue":100,
         "maxvalue":100,
         "items":[
            {time:"01-15-2018 00:00:00","value":100},
            {time:"01-15-2018 01:00:00","value":100},
            {time:"01-15-2018 02:00:00","value":100},
            {time:"01-15-2018 03:0000:","value":100},
            {time:"01-15-2018 04:00:00","value":100}
         ]
      }],
      "statustimeseries":[
         {
            "statusid": 5,
            "status": "Completed",
            "requestcount":350,
            "minvalue":0,
            "maxvalue":100,
            "items":[
               {time:"01-15-2018 00:00:00","value":100},
               {time:"01-15-2018 01:00:00","value":100},
               {time:"01-15-2018 02:00:00","value":100},
               {time:"01-15-2018 03:00:00","value":50},
               {time:"01-15-2018 04:00:00","value":0}
            ]
         },
         {
            "statusid": 1,
            "status": “Processing”,
            "requestcount":100,
            "minvalue":0,
            "maxvalue":75,
            "items":[
               {time:"01-15-2018 00:00:00","value":0},
               {time:"01-15-2018 01:00:00","value":0},
               {time:"01-15-2018 02:00:00","value":0},
               {time:"01-15-2018 03:00:00","value":25},
               {time:"01-15-2018 04:00:00","value":75}
            ]
         },
         {
            "statusid": 7,
            "Status": "Invalid",
            "requestcount":50,
            "minvalue":0,
            "maxvalue":50,
            "items":[
               {time:"01-15-2018 00:00:00","value":0},
               {time:"01-15-2018 01:00:00","value":0},
               {time:"01-15-2018 02:00:00","value":0},
               {time:"01-15-2018 03:00:00","value":25},
               {time:"01-15-2018 04:00:00","value":25}
            ]
         }]
}

Vous pouvez utiliser les valeurs OperationID pour suivre les requêtes non valides ou en cours de traitement.

Cela fait beaucoup de code, n’est-ce pas ? Nous en avons assez vu pour le moment. Concentrons-nous maintenant sur la dernière unité, afin d’apprendre la meilleure manière d’éviter les pièges lors des suppressions de contacts.

Ressources