Massenauszug von Blei

Referenz zum Massenextraktions-Endpunkt für Leads

Der Satz von REST-APIs für die Lead-Massenextraktion bietet eine programmgesteuerte Schnittstelle zum Abrufen großer Mengen von Lead/Personen-Datensätzen aus Marketo. Sie kann auch verwendet werden, um Leads inkrementell basierend auf dem Erstellungsdatum des Datensatzes, der letzten Aktualisierung, der statischen Listenmitgliedschaft oder der Smart-Listen-Mitgliedschaft abzurufen. Die empfohlene Benutzeroberfläche für Anwendungsfälle, für die ein kontinuierlicher Datenaustausch zwischen Marketo und einem oder mehreren externen Systemen für ETL-, Data Warehousing- und Archivierungszwecke erforderlich ist.

Berechtigungen

Die APIs zum Massen-Lead-Extrahieren erfordern, dass der besitzende API-Benutzer über eine Rolle mit einer oder beiden der Berechtigungen Schreibgeschützter Lead oder Lese-/Schreib-Lead verfügt.

Filter

Leads unterstützen verschiedene Filteroptionen. Bestimmte Filter, einschließlich updatedAt, smartListName und smartListId, erfordern zusätzliche Infrastrukturkomponenten, die noch nicht für alle Abonnements bereitgestellt wurden. Pro Exportvorgang kann nur ein Filtertyp angegeben werden.

Filtertyp ist für einige Abonnements nicht verfügbar. Wenn für Ihr Abonnement nicht verfügbar ist, erhalten Sie eine Fehlermeldung beim Aufruf des Endpunkts „Exportleitungs-Auftrag erstellen“ („1035, Nicht unterstützter Filtertyp für Zielabonnement„). Kunden können sich an den Marketo-Support wenden, um diese Funktion in ihrem Abonnement aktivieren zu lassen.

Optionen

Der Endpunkt Exportvorgang erstellen bietet mehrere Formatierungsoptionen, die es Benutzenden ermöglichen, bestimmte Felder in die exportierte Datei einzuschließen, Spaltenüberschriften dieser Felder umzubenennen und das Format der exportierten Datei anzugeben.

Erstellen von Aufträgen

Die Parameter für den Auftrag werden vor dem Start des Exports mithilfe des Endpunkts Exportvorgang erstellen definiert. Wir müssen die für den Export erforderlichen fields, den Parametertyp des filter, den format der Datei und gegebenenfalls die Namen der Spaltenüberschriften definieren.

POST /bulk/v1/leads/export/create.json

{
   "fields": [
      "firstName",
      "lastName",
      "id",
      "email"
   ],
   "format": "CSV",
   "columnHeaderNames": {
      "firstName": "First Name",
      "lastName": "Last Name",
      "id": "Marketo Id",
      "email": "Email Address"
   },
   "filter": {
      "createdAt": {
         "startAt": "2017-01-01T00:00:00Z",
         "`endAt`": "2017-01-31T00:00:00Z"
      }
   }
}

Diese Anfrage beginnt mit dem Export eines Lead-Satzes, der zwischen dem 1. Januar 2017 und dem 31. Januar 2017 erstellt wurde, einschließlich der Werte aus den entsprechenden firstName-, lastName-, id- und email.

{
   "requestId": "e42b#14272d07d78",
   "success": true,
   "result": [
      {
         "exportId": "ce45a7a1-f19d-4ce2-882c-a3c795940a7d",
         "status": "Created",
         "createdAt": "2017-01-21T11:47:30-08:00",
         "queuedAt": "2017-01-21T11:48:30-08:00",
         "format": "CSV"
      }
   ]
}

Dadurch wird eine Statusantwort zurückgegeben, die angibt, dass der Auftrag erstellt wurde. Der Auftrag wurde definiert und erstellt, aber noch nicht gestartet. Dazu muss der Endpunkt Exportauftrag in die Warteschlange einreihen mit der exportId aus der Erstellungsstatusantwort aufgerufen werden:

POST /bulk/v1/leads/export/{exportId}/enqueue.json

{
    "requestId": "147e4#16b24d9b913",
    "result": [
        {
            "exportId": "fad2cd1b-e822-4025-be1e-9caa9cf1d4b8",
            "format": "CSV",
            "status": "Queued",
            "createdAt": "2019-06-04T23:35:43Z",
            "queuedAt": "2019-06-04T23:36:17Z"
        }
    ],
    "success": true
}

Daraufhin wird mit der status „In Warteschlange“ geantwortet, die auf „Wird verarbeitet“ gesetzt wird, wenn ein Exportsteckplatz verfügbar ist.

Status des Abrufauftrags

Note: Status kann nur für Aufträge abgerufen werden, die vom selben API-Benutzer erstellt wurden.

Da es sich um einen asynchronen Endpunkt handelt, müssen wir nach der Erstellung des Auftrags dessen Status abfragen, um den Fortschritt zu ermitteln. Abfrage mit dem Endpunkt Status des Exportvorgangs abrufen. Der Status wird nur einmal alle 60 Sekunden aktualisiert, sodass eine niedrigere Abfrageintervall nicht empfohlen wird und in fast allen Fällen immer noch zu hoch ist. Werfen wir einen kurzen Blick auf die Umfragen.

GET /bulk/v1/leads/export/{exportId}/status.json

{
   "requestId": "e42b#14272d07d78",
   "success": true,
   "result": [
      {
         "exportId": "ce45a7a1-f19d-4ce2-882c-a3c795940a7d",
         "status": "Processing",
         "createdAt": "2017-01-21T11:47:30-08:00",
         "queuedAt": "2017-01-21T11:48:30-08:00",
         "format": "CSV"
      }
   ]
}

Der Status-Endpunkt antwortet und gibt an, dass der Auftrag noch verarbeitet wird, sodass die Datei noch nicht zum Abrufen verfügbar ist. Sobald sich der Auftragsstatus in „Abgeschlossen“ ändert, wird er zum Download vorbereitet.

Das Statusfeld kann mit einem der folgenden Elemente antworten:

Daten abrufen

Um die Datei eines abgeschlossenen Lead-Exports abzurufen, rufen Sie einfach den Endpunkt Lead-Exportdatei abrufen mit Ihrem exportId auf.

GET /bulk/v1/leads/export/{exportId}/file.json

Die Antwort enthält eine -Datei, die so formatiert ist, wie der Auftrag konfiguriert wurde. Der Endpunkt antwortet mit dem Inhalt der -Datei.

Wenn ein angefordertes Lead-Feld leer ist (keine Daten enthält), wird null in der Exportdatei im entsprechenden Feld platziert. Im folgenden Beispiel ist das E-Mail-Feld für den zurückgegebenen Lead leer.

firstName,lastName,email,cookies
Russell,Wilson,null,_mch-localhost-1536605780000-12105

Um das partielle und fortsetzungsfreundliche Abrufen extrahierter Daten zu unterstützen, unterstützt der Datei-Endpunkt optional den HTTP-Header-Bereich vom Typ Byte. Wenn die Kopfzeile nicht festgelegt ist, wird der gesamte Inhalt zurückgegeben. Erfahren Sie mehr über die Verwendung des Bereichs-Headers mit Marketo Massenextraktion.

Abbrechen von Aufträgen

Wenn ein Auftrag falsch konfiguriert wurde oder unnötig wird, kann er einfach mit dem Endpunkt Exportvorgang abbrechen abgebrochen werden:

POST /bulk/v1/leads/export/{exportId}/cancel.json

{
   "requestId": "e42b#14272d07d78",
   "success": true,
   "result": [
      {
         "exportId": "ce45a7a1-f19d-4ce2-882c-a3c795940a7d",
         "status": "Cancelled",
         "createdAt": "2017-01-21T11:47:30-08:00",
         "format": "CSV"
      }
   ]
}

Daraufhin wird ein Status angezeigt, der angibt, dass der Vorgang abgebrochen wurde.