Datenaufnahme-API

Die Datenerfassungs-API ist ein Service mit hoher Datenmenge und geringer Latenz, der mit hoher Verfügbarkeit entwickelt wurde, um die Aufnahme großer Mengen von Personen- und personenbezogenen Daten effizient und mit minimalen Verzögerungen zu handhaben.

Daten werden durch Senden von Anfragen aufgenommen, die asynchron ausgeführt werden. Der Anfragestatus kann abgerufen werden, indem Ereignisse aus dem Marketo Observability Data Stream abonniert werden.

Schnittstellen werden für zwei Objekttypen angeboten: Personen, Benutzerdefinierte Objekte. Der Datensatzvorgang ist nur „Einfügen oder Aktualisieren“.

Authentifizierung

Die Datenaufnahme-API verwendet dieselbe OAuth 2.0-Authentifizierungsmethode wie die Marketo REST-API zum Generieren eines Zugriffstokens, das Zugriffstoken muss jedoch über die HTTP-Kopfzeile X-Mkto-User-Token übergeben werden. Das Zugriffstoken kann nicht über einen Abfrageparameter übergeben werden.

Beispiel eines Zugriffs-Tokens über den Header:

X-Mkto-User-Token: 11606815-aa7a-405a-80a1-f9683efa528b:ab

Berechtigungen

Die Datenaufnahme verwendet dasselbe Berechtigungsmodell wie die Marketo REST-API und erfordert keine zusätzlichen speziellen Berechtigungen zur Verwendung, obwohl für jeden Endpunkt spezifische Berechtigungen erforderlich sind.

Kopfzeilen

Die Datenaufnahme nutzt die folgenden benutzerdefinierten HTTP-Kopfzeilen.

Anfrage

Antwort

Anfragen

Verwenden Sie die HTTP-POST-Methode, um Daten an den Server zu senden.

Die Datendarstellung ist im Anfragetext als application/json enthalten.

Der Domain-Name lautet: mkto-ingestion-api.adobe.io

Der Pfad beginnt mit /subscriptions/MunchkinId, wobei MunchkinId spezifisch für Ihre Marketo-Instanz ist. Ihre Munchkin-ID finden Sie in der Marketo Engage-Benutzeroberfläche unter Admin > Mein > Support-Informationen. Der Rest des Pfads wird verwendet, um die gewünschte Ressource anzugeben.

Beispiel-URL für Personen:

https://mkto-ingestion-api.adobe.io/subscriptions/556-RJS-213/persons

Beispiel-URL für benutzerdefinierte Objekte:

https://mkto-ingestion-api.adobe.io/subscriptions/556-RJS-213/customobjects/purchases

Antworten

Alle Antworten geben über den X-Request-Id-Header eine eindeutige Anfrage-ID zurück.

Beispiel einer Anfrage-ID über den Header:

X-Request-Id: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Erfolgreich

Wenn ein Aufruf erfolgreich war, wird der Status 202 zurückgegeben. Es wird kein Antworttext zurückgegeben.

Beispiel für eine erfolgreiche Antwort:

HTTP/1.1 202 Accepted
X-Request-Id: e3d92152-0fb1-444a-8f8f-29d5a2338598
Content-Length: 0
Date: Wed, 18 Oct 2023 18:56:49 GMT

Fehler

Wenn ein Aufruf einen Fehler erzeugt, wird ein Nicht-202-Status zusammen mit einem Antworttext mit zusätzlichen Fehlerdetails zurückgegeben. Der Antworttext ist application/json und enthält ein einzelnes Objekt mit Membern und Fehlercode sowie Nachricht.

Im Folgenden finden Sie wiederverwendete Fehler-Codes vom Adobe Developer-Gateway.

Im Folgenden finden Sie Fehlercodes, die für die Datenaufnahme-API eindeutig sind und aus drei Segmenten bestehen. Die ersten drei Ziffern geben den Status an (von Adobe Developer Gateway zurückgegeben), gefolgt von einer Null „0“, gefolgt von drei Ziffern.

Weitere Zustellversuche

Wenn ein vorübergehender Fehler erkannt wird, versucht der Service den Vorgang dreimal erneut. Der erste erneute Versuch findet nach einer Wartezeit von 5 Minuten statt, der zweite nach 30 weiteren Minuten und schließlich der dritte nach 30 weiteren Minuten. Weitere Zustellversuche erfolgen aus verschiedenen Gründen, in erster Linie, wenn ein abhängiger Service eine Zeitüberschreitung aufweist oder vorübergehend nicht verfügbar ist.

Endpunkte

Aufnahme-Endpunkte sind für Personen und benutzerdefinierte Objekte verfügbar.

Personen

Endpunkt, der zur Aktualisierung von Personendatensätzen verwendet wird.

Kopfzeilen

Anfragetext

Erforderliche Berechtigungen sind Read-Write Lead.

Beispiel für Personen

Anfrage

POST /subscriptions/{munchkinId}/persons

Kopfzeilen

Content-Type: application/json
X-Mkto-User-Token: {accessToken}

Textkörper

{
   "priority": "high",
   "partitionName": "EMEA",
   "dedupeFields": {
      "field1": "email",
      "field2": "firstName"
   },
   "persons":[
      {
         "email": "brooklyn.parker@karnv.com",
         "firstName": "Brooklyn",
         "lastName": "Parker"
      },
      {
         "email": "johnny.neal@yvu30.com",
         "firstName": "Johnny",
         "lastName": "Neal"
      }
   ]
}

Antwort

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Benutzerdefinierte Objekte

Endpunkt zum Upsertieren benutzerdefinierter Objektdatensätze

Kopfzeilen

Anfragetext

Erforderliche Berechtigungen sind Read-Write Custom Object.

Wenn in der Anfrage ein Verknüpfungsfeld zu einer Person angegeben ist und diese Person nicht vorhanden ist, werden mehrere weitere Zustellversuche unternommen. Wenn diese Person im Wiederholungsfenster (65 Minuten) hinzugefügt wird, ist die Aktualisierung erfolgreich. Wenn beispielsweise das Verknüpfungsfeld E-Mail an Person lautet und Person nicht vorhanden ist, werden weitere Zustellversuche unternommen.

Beispiel für benutzerdefinierte Objekte

Anfrage

POST /subscriptions/{munchkinId}/customobjects/{customObjectAPIName}

Kopfzeilen

Content-Type: application/json
X-Mkto-User-Token: {accessToken}

Textkörper

{
   "dedupeBy": "dedupeFields",
   "priority": "high",
   "customObjects": [
      {
         "email": "brooklyn.parker@karnv.com",
         "vin": "20UYA31581L000000",
         "make": "BMW",
         "model": "3-Series 330i",
         "year": 2003
      },
      {
         "email": "johnny.neal@yvu30.com",
         "vin": "19UYA31581L000000",
         "make": "BMW",
         "model": "3-Series 325i",
         "year": 1989
      }
   ]
}

Antwort

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Beschränkungen

Im Folgenden finden Sie eine Liste zur Verwendung von Leitplanken:

Datenaufnahme-API und REST-API im Vergleich

Im Folgenden finden Sie eine Liste der Unterschiede zwischen der Datenaufnahme-API und anderen Marketo-REST-APIs: