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 fünf Objekttypen angeboten: Personen, benutzerdefinierte Objekte, Unternehmen, Programmmitglieder und Listen (statische Listen). Der Datensatzvorgang ist nur „Einfügen oder Aktualisieren“, mit Ausnahme von Programmmitgliedern, die auch „Löschen“ unterstützen, und Listen, die „Hinzufügen“ und „Entfernen“ unterstützen.

Lesen Sie ​ Dokumentation zur Datenaufnahme-API.

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.

Unterstützte Objekttypen

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

Beispiel-URL für Unternehmen:

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

Beispiel-URL für Programmmitglieder:

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

Beispiel-URL für Listen:

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

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 error_code und message.

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 erneut. 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.

Wiederholungsintervalle:

Endpunkte

Aufnahme-Endpunkte sind für Personen, benutzerdefinierte Objekte, Unternehmen, Programmmitglieder und Listen 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",
         "company": "Karnv"
      },
      {
         "email": "johnny.neal@yvu30.com",
         "firstName": "Johnny",
         "lastName": "Neal",
         "company": "Acme Inc"
      }
   ]
}

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 auf Person email ist 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

Firmen

Endpunkt zum Synchronisieren von Firmendatensätzen. Unterstützt das Erstellen, Aktualisieren und Aktualisieren von Vorgängen mit Deduplizierung nach externer Unternehmens-ID oder interner Marketo-ID.

Kopfzeilen

Anfragetext

Jedes Unternehmensobjekt im input-Array unterstützt die folgenden Felder:

Erforderliche Berechtigungen sind Read-Write Company.

Beispiel für Unternehmen

Anfrage

POST /subscriptions/{munchkinId}/companies

Kopfzeilen

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

Textkörper

{
   "action": "createOrUpdate",
   "dedupeBy": "dedupeFields",
   "input": [
      {
         "externalCompanyId": "ext-company-001",
         "company": "Acme Corporation",
         "industry": "Technology",
         "numberOfEmployees": 5000,
         "annualRevenue": 100000000
      },
      {
         "externalCompanyId": "ext-company-002",
         "company": "Globex Industries",
         "industry": "Manufacturing",
         "numberOfEmployees": 1200
      }
   ]
}

Antwort

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Beispiel für eine Aktualisierung nach ID durch Unternehmen

{
   "action": "updateOnly",
   "dedupeBy": "idField",
   "input": [
      {
         "id": 12345,
         "company": "Acme Corporation (Renamed)",
         "numberOfEmployees": 5500
      }
   ]
}

Validierungsregeln für Unternehmen

Programmmitglieder (synchronisieren)

Endpunkt, der zum Synchronisieren des Programmmitgliedsstatus, Hinzufügen von Leads zu Programmen oder Aktualisieren ihres Programmstatus verwendet wird.

Kopfzeilen

Anfragetext

Jedes Objekt im programs-Array enthält:

Jedes Objekt im members-Array enthält:

Erforderliche Berechtigungen sind Read-Write Lead.

Beispiel für die Synchronisierung von Programmmitgliedern

Anfrage

POST /subscriptions/{munchkinId}/programmembers

Kopfzeilen

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

Textkörper

{
   "programs": [
      {
         "programId": 1001,
         "status": "Member",
         "members": [
            {
               "leadId": 10001
            },
            {
               "leadId": 10002
            }
         ]
      },
      {
         "programId": 1002,
         "status": "Influenced",
         "members": [
            {
               "leadId": 10003
            }
         ]
      }
   ]
}

Antwort

HTTP/1.1 202
X-Request-ID: e3d92152-0fb1-444a-8f8f-29d5a2338598

Programmmitglieder synchronisieren Validierungsregeln

Programmmitglieder (Löschen)

Endpunkt zum Entfernen von Leads aus Programmen. Dadurch wird der Mitgliedschaftsstatus des Leads auf "Not in Program" gesetzt und das Mitglied aus diesem Programm entfernt.

Kopfzeilen

Anfragetext

Jedes Objekt im programs-Array enthält:

Jedes Objekt im members-Array enthält:

Erforderliche Berechtigungen sind Read-Write Lead.

Beispiel zum Löschen von Programmmitgliedern

Anfrage

POST /subscriptions/{munchkinId}/programmembers/delete

Kopfzeilen

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

Textkörper

{
   "programs": [
      {
         "programId": 1001,
         "members": [
            {
               "leadId": 10001
            },
            {
               "leadId": 10002
            }
         ]
      },
      {
         "programId": 1002,
         "members": [
            {
               "leadId": 10003
            }
         ]
      }
   ]
}

Antwort

HTTP/1.1 202
X-Request-ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Programmmitglieder löschen Validierungsregeln

Listen (zu Liste hinzufügen)

Endpunkt zum Hinzufügen von Leads zu einer statischen Liste. Leads werden anhand ihrer Marketo-Lead-ID identifiziert.

Kopfzeilen

Anfragetext

Jedes Objekt im Eingabe-Array enthält:

Erforderliche Berechtigungen sind Read-Write Lead.

Beispiel für Listen, die zu einer Liste hinzugefügt werden

Anfrage

POST /subscriptions/{munchkinId}/lists

Kopfzeilen

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

Textkörper

{
   "listId": 1001,
   "leads": [
      {
         "leadId": 10001
      },
      {
         "leadId": 10002
      },
      {
         "leadId": 10003
      }
   ]
}

Antwort

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Listen zu Validierungsregeln für Listen hinzufügen

Listen (aus Liste entfernen)

Endpunkt zum Entfernen von Leads aus einer statischen Liste. Leads werden anhand ihrer Marketo-Lead-ID identifiziert.

Kopfzeilen

Anfragetext

Jedes Objekt im Eingabe-Array enthält:

Erforderliche Berechtigungen sind Read-Write Lead.

Beispiel für das Entfernen von Listen aus einer Liste

Anfrage

POST /subscriptions/{munchkinId}/lists/remove

Kopfzeilen

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

Textkörper

{
   "listId": 1001,
   "leads": [
      {
         "leadId": 10001
      },
      {
         "leadId": 10002
      }
   ]
}

Antwort

HTTP/1.1 202
X-Request-ID: e3d92152-0fb1-444a-8f8f-29d5a2338598

Listen werden aus den Regeln für die Listenvalidierung entfernt

Beschränkungen

Im Folgenden finden Sie eine aktualisierte Liste von Leitplanken:

Diese Beschränkungen gelten einheitlich für Personen, benutzerdefinierte Objekte, Unternehmen, Programmmitglieder und Listen. Für Programmteilnehmer ist „Objekte pro Anfrage“ die Gesamtzahl der Lead-Referenzen in allen Programmen in einer einzigen Anfrage. Bei Listen ist „Objekte pro Anfrage“ die Anzahl der Lead-Referenzen im Eingabe-Array.

Datenaufnahme-API und REST-API im Vergleich

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