Massenaktivität-Extrakt

Referenz für Massenaktivität-Extraktionsendpunkt

Der Satz von REST-APIs für die Massenaktivität-Extraktion bietet eine programmgesteuerte Schnittstelle zum Abrufen großer Mengen von Aktivitätsdaten aus Marketo.  Für Fälle, in denen keine niedrige Latenz erforderlich ist und erhebliche Mengen von Aktivitätsdaten aus Marketo übertragen werden müssen, z. B. CRM-Integration, ETL, Data Warehousing und Datenarchivierung.

Berechtigungen

Die APIs zum Extrahieren von Massenaktivitäten erfordern, dass der API-Benutzer über die Berechtigungen „Schreibgeschützte Aktivität“ oder „Lese-/Schreibaktivität“ verfügt.

Filter

primaryAttributeValueIds-Optionen primaryattributevalueids-options

Bei Verwendung von primaryAttributeValueIds muss der activityTypeIds vorhanden sein und darf nur Aktivitäts-IDs enthalten, die mit der entsprechenden Asset-Gruppe übereinstimmen. Wenn Sie beispielsweise nach Web-Formular-Assets filtern, ist in activityTypeIds nur die Aktivitätstyp-ID „Formular ausfüllen“ zulässig.

Beispiel-Anfragetext:

{
  "filter": {
    "createdAt": {
      "startAt": "2021-07-01T23:59:59-00:00",
      "endAt": "2021-07-02T23:59:59-00:00"
    },
    "activityTypeIds": [
      2
    ],
    "primaryAttributeValueIds": [
      16,102,95,8
    ]
  }
}

primaryAttributeValueIds und primaryAttributeValues können nicht zusammen verwendet werden.

primaryAttributeValues-Optionen primaryattributevalues-options

Beachten Sie, dass Sie "<program> verwenden müssen.<asset>" verwenden, um den Namen für die folgenden Asset-Gruppen anzugeben: Marketing-Programm, statische Liste, Web-Formular. Beispielsweise würde ein Formular mit dem Namen „MPS Outbound“, das sich unter einem Programm mit dem Namen „GL_OP_ALL_2021“ befindet, als „GL_OP_ALL_2021.MPS Outbound“ angegeben.

Beispiel-Anfragetext:

{
  "filter": {
    "createdAt": {
      "startAt": "2021-07-01T23:59:59-00:00",
      "endAt": "2021-07-02T23:59:59-00:00"
    },
    "activityTypeIds": [
      2
    ],
    "primaryAttributeValues": [
      "GL_OP_ALL_2021.MPS Outbound"
    ]
  }
}

Bei Verwendung von primaryAttributeValues muss der activityTypeIds vorhanden sein und darf nur Aktivitäts-IDs enthalten, die mit der entsprechenden Asset-Gruppe übereinstimmen. Wenn Sie beispielsweise nach Web-Formular-Assets filtern, ist in activityTypeIds nur die Aktivitätstyp-ID „Formular ausfüllen“ zulässig. primaryAttributeValues und primaryAttributeValueIds können nicht zusammen verwendet werden.

Optionen

Erstellen von Aufträgen

Um Datensätze zu exportieren, müssen Sie zunächst den Auftrag und die Menge der Datensätze definieren, die Sie abrufen möchten.  Erstellen Sie den Auftrag mit Endpunkt „Exportaktivitätsauftrag erstellen.  Beim Exportieren von Aktivitäten können zwei primäre Filter angewendet werden: createdAt, was immer erforderlich ist, und activityTypeIds, was optional ist.  Der createdAt Filter wird verwendet, um einen Datumsbereich zu definieren, in dem Aktivitäten erstellt wurden. Dabei werden die Parameter startAt und endAt verwendet, die beide Datums-/Uhrzeitfelder sind und das früheste zulässige Erstellungsdatum bzw. das späteste zulässige Erstellungsdatum darstellen.  Optional können Sie auch mit dem activityTypeIds Filter nur nach bestimmten Aktivitätstypen filtern.  Dies ist nützlich, um Ergebnisse zu entfernen, die für Ihren Anwendungsfall nicht relevant sind.

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

{
   "format": "CSV",
   "filter": {
      "createdAt": {
         "startAt": "2017-07-01T23:59:59-00:00",
         "endAt": "2017-07-31T23:59:59-00:00"
      },
      "activityTypeIds": [
         1,
         12,
         13
      ]
   }
}

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

Der Auftrag hat jetzt den Status „Erstellt“, befindet sich jedoch noch nicht in der Verarbeitungswarteschlange.  Um ihn in die Warteschlange einzustellen, damit er mit der Verarbeitung beginnen kann, rufen Sie den Endpunkt Exportaktivitätsauftrag in die Warteschlange mit der exportId aus der Antwort auf den Erstellungsstatus auf.

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

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

Jetzt meldet der Status, dass der Auftrag in die Warteschlange gestellt wurde.  Wenn ein Worker für diesen Auftrag verfügbar wird, wird der Status auf „Verarbeitung läuft“ geändert und der Vorgang beginnt, Datensätze aus Marketo zu aggregieren.

Status des Abrufauftrags

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

Marketos Massenaktivität-Extraktion ist ein asynchroner Endpunkt, sodass der Auftragsstatus abgefragt werden muss, um zu bestimmen, wann der Auftrag abgeschlossen ist.  Abfrage mit dem Endpunkt Exportaktivitätsstatus abrufen wie folgt:

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

{
   "requestId": "e42b#14272d07d78",
   "success": true,
   "result": [
      {
         "exportId": "ce45a7a1-f19d-4ce2-882c-a3c795940a7d",
         "status": "Completed",
         "createdAt": "2017-01-21T11:47:30-08:00",
         "queuedAt": "2017-01-21T11:48:30-08:00",
         "startedAt": "2017-01-21T11:51:30-08:00",
         "finishedAt": "2017-01-21T12:59:30-08:00",
         "format": "CSV",
         "numberOfRecords": 15423,
         "fileSize": 12342,
         "fileChecksum": "sha256:c16514c7e80fcac5ea055dacae9617fc3c29aff5365e3743071313ce0ed2a815"
      }
   ]
}

Das Statusfeld kann mit einem der folgenden Werte antworten:

Daten abrufen

Sobald der Auftrag abgeschlossen ist, rufen Sie Ihre Daten mit dem Endpunkt Exportaktivitätsdatei abrufen ab.

GET /bulk/v1/activities/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 then null in der Exportdatei im entsprechenden Feld platziert.  Im folgenden Beispiel ist das campaignId Feld für die zurückgegebene Aktivität leer.

marketoGUID,leadId,activityDate,activityTypeId,campaignId,primaryAttributeValueId,primaryAttributeValue,attributes
783957693,5414087,2022-02-13T14:06:20Z,104,8497,1670,MembershipTest1,"{""Reason"":""Changed by Smart Campaign MembershipTestCampaignStepChoice.MembershipTestCampaignStepChoiceSetUp action Change Data Value"",""Program Member ID"":3240303,""Acquired By"":true,""Old Status"":""Not in Program"",""New Status ID"":21,""Success"":false,""New Status"":""On List"",""Old Status ID"":20}"
783958220,5414094,2022-02-13T14:08:50Z,104,17240,3569,SuccessWebCPS,"{""Program Member ID"":3240305,""Acquired By"":false,""Old Status"":""Not in Program"",""New Status ID"":6,""Success"":true,""New Status"":""Attended"",""Old Status ID"":1}"
783958306,5414094,2022-02-13T14:09:16Z,104,17240,3569,SuccessWebCPS,"{""Program Member ID"":3240305,""Acquired By"":false,""Old Status"":""Attended"",""New Status ID"":6,""Success"":false,""New Status"":""Attended"",""Old Status ID"":6}"
783961924,5316669,2022-02-13T14:27:21Z,104,11614,2333,Nurture Automation,"{""Program Member ID"":3240306,""Acquired By"":false,""Old Status"":""Not in Program"",""New Status ID"":27,""Success"":false,""New Status"":""Member"",""Old Status ID"":26}"

Um das teilweise und fortsetzungsfreundliche Abrufen extrahierter Daten zu unterstützen, unterstützt der Dateiendpunkt optional die HTTP-Header-Range vom Typ bytes.  Wenn die Kopfzeile nicht festgelegt ist, wird der gesamte Inhalt zurückgegeben.  Weitere Informationen zur 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 Exportaktivitätsauftrag abbrechen abgebrochen werden:

POST /bulk/v1/activities/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"
      }
   ]
}

Diese Antwort weist einen Status auf, der angibt, dass der Vorgang abgebrochen wurde.