Skip to main content

Löschen von Kontakten mit der REST API

Lernziele

Nachdem Sie diese Lektion abgeschlossen haben, sind Sie in der Lage, die folgenden Aufgaben auszuführen:

  • Löschen von Kontakten in Batches mit der REST API
  • Abrufen des Status von Kontaktlöschungsanforderungen
  • Beheben von Fehlern in Kontaktlöschungsanforderungen

Effizientere Löschung von Kontakten

Das Löschen von ein oder zwei Kontakten direkt in Marketing Cloud Engagement ist recht einfach. Wenn Sie jedoch mehr als eine Handvoll Kontakte löschen, kann der Vorgang schnell langwierig werden. Obwohl das Limit pro Anforderungs-Batch eine Million Kontakte beträgt, erwarten wir nicht, dass Sie diese Anzahl von Kontakten manuell auswählen. Wenn Sie also eine große Anzahl von Kontakten löschen müssen (und Sie sich ganz sicher sind, dass das Löschen von Kontakten die beste Wahl ist), stehen Ihnen dafür in Marketing Cloud Engagement mehrere REST-API-Ressourcen zur Verfügung.

Aktivieren der Kontaktlöschung

Denken Sie vor Beginn daran, dass die Kontaktlöschung aktiviert sein muss. Konsultieren Sie die vorherige Lektion, wenn Sie diesbezüglich eine Auffrischung benötigen. Analog können Sie den Unterdrückungszeitraum für Ihren Account mit der configSettings-Ressource ändern, wie in diesem Beispiel gezeigt.

Beispiel: Konfigurieren des Unterdrückungszeitraums für die Kontaktlöschung

In diesem Beispiel wird der Wert auf 0 Tage (mit einem Wert von -1) festgelegt, was einer sofortigen Löschung entspricht.

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"
      }
   ]

Auswahl der Vorgehensweise bei der Kontaktlöschung mit der REST API

Nachdem Ihr Account nun zum Löschen von Kontakten aktiviert ist, können Sie die zu löschenden Kontakte anhand eines von drei verschiedenen Werten auswählen: Kontakt-IDs, Kontaktschlüssel oder Data Extensions. Schauen wir uns diese zusammen mit einem Beispielcode genauer an. 

Kontakt-IDs

Wenn Sie Kontakte mit einem Kontakt-ID-Wert löschen möchten, sollten Sie die Werte in einem Array übergeben, wie in diesem Beispiel gezeigt.

Beispiel: Löschen von Kontakten nach Kontakt-ID

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"
}

Kontaktschlüssel

Wenn Sie Kontakte anhand des ContactKey-Werts löschen möchten, sollten Sie die Werte in einem Array übergeben.

Beispiel: Löschen von Kontakten nach Kontaktschlüssel

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"
}

Data Extensions

Sie können auch alle Kontakte entfernen, die in einer bestimmten Data Extension enthalten sind. Denken Sie daran, dass dieser Vorgang die in der Data Extension angegebenen Kontaktdatensätze für alle versandfähigen Data Extensions löscht. Dies schließt Data Extensions ein, die basierend auf den Werten "ContactKey", "ContactID" und "Email Address" Sendevorgänge ausführen. Wenn Sie fertig sind, können Sie sich auch überlegen, ob Sie die gesamte Data Extension löschen. So viele Möglichkeiten! 

Dieser Prozess erstellt eine asynchrone Anforderung für Ihren Batch von Löschanforderungen. Sie können sich an Ihren Marketing Cloud Engagement-Accountmanager wenden, wenn Sie weitere Informationen zum Konfigurieren von Löschanforderungslimits in Ihrem Account benötigen.

Hinweis

Sie müssen angeben, dass Sie eine Data Extension löschen und den externen Schlüssel für diese Data Extension einbeziehen. Außerdem lassen sich synchronisierte Data Extensions nicht löschen. Sie können damit zwar die zu löschenden Kontakte ermitteln, die eigentliche Data Extension bleibt jedoch erhalten.

Beispiel: Löschen von Kontakten mit einer Data Extension

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
}

Überprüfen Ihrer Anforderungen

Wie bereits erwähnt, dauert es einige Zeit, bis Kontaktlöschungsanforderungen abgeschlossen sind. Tatsächlich kann dieser Vorgang einige Stunden in Anspruch nehmen, abhängig von der Anzahl der Kontakte, die Sie in Ihre Anforderung aufgenommen haben, der Anzahl der von Ihnen gesendeten Anforderungen und anderen Systemfaktoren. Mit dem OperationID-Wert können Sie sich jedoch über den Fortschritt Ihrer Anforderungen auf dem Laufenden halten. Jede Kontaktlöschungsanforderung gibt einen OperationID-Wert zurück, mit dem Sie alle verfügbaren Informationen abrufen können. Hier einige Beispielanforderungen.

Beispiel: Abrufen des Status einer bestimmten Kontaktlöschungsanforderung

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

Diese Beispielantwort zeigt die Informationen für einen gelöschten Kontakt.

{
   "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"
}

Beispiel: Abrufen von Kontaktlöschungsanforderungen nach Datum

Sie können auch eine Zusammenfassung der Anforderungen abrufen, die in einem bestimmten Zeitraum gesendet wurden. 

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
{

Die Antwort enthält die OperationID-Werte und kurze Zusammenfassungen aller betreffenden Anforderungen. Um genauere Informationen zu erhalten, verwenden Sie die OperationID mit der 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"
}

Beispiel: Abrufen einer Zusammenfassung von Kontaktlöschungsanforderungen

Dieses Beispiel zeigt eine Zusammenfassung der Statusberichte für alle Anforderungen im angegebenen Zeitraum.

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

In der Beispielantwort werden die Anforderungen in "Completed", "Processing" oder "Invalid" unterteilt.

{
   "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}
            ]
         }]
}

Sie können OperationID-Werte verwenden, um ungültige oder in Verarbeitung befindliche Anforderungen zu verfolgen.

Das war ganz schön viel Code, oder? Lassen Sie uns in Sachen Code eine Pause machen und zur letzten Lektion übergehen. Dort erfahren Sie, wie Sie Probleme beim Löschen von Kontakten am besten vermeiden.

Ressourcen

Lernen Sie weiter kostenlos!
Registrieren Sie sich für einen Account, um fortzufahren.
Registrieren Anmelden
Was ist für Sie drin?
  • Holen Sie sich personalisierte Empfehlungen für Ihre Karriereplanung
  • Erproben Sie Ihre Fähigkeiten mithilfe praktischer Aufgaben und Quizze
  • Verfolgen Sie Ihre Fortschritte nach und teilen Sie sie mit Arbeitgebern
  • Nutzen Sie Mentoren und Karrierechancen
Vorerst überspringen