API för datainmatning

API:t för datainmatning är en tjänst med hög volym, låg latens och hög tillgänglighet som är utformad för att hantera stora mängder personrelaterade data effektivt och med minimal fördröjning.

Data hämtas genom att begäranden som körs asynkront skickas. Status för begäran kan hämtas genom att prenumerera på händelser från Marketo-dataströmmen för observabilitet.

Gränssnitt finns för fem objekttyper: Personer, anpassade objekt, företag, programmedlemmar och listor (statiska listor). Poståtgärden är"infoga eller uppdatera", förutom för programmedlemmar som också har stöd för borttagning, och listor som har stöd för åtgärder för att lägga till och ta bort.

Läs API-dokumentationen för datainmatning.

Autentisering

API:t för datainmatning använder samma OAuth 2.0-autentiseringsmetod som Marketo REST API för att generera en åtkomsttoken, men åtkomsttoken måste skickas via HTTP-huvudet X-Mkto-User-Token. Du kan inte skicka åtkomsttoken via en frågeparameter.

Exempel på åtkomsttoken via rubrik:

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

Behörigheter

Datainmatning använder samma behörighetsmodell som Marketo REST API och kräver inga ytterligare specialbehörigheter att använda, men specifika behörigheter krävs för varje slutpunkt.

Objekttyper som stöds

Sidhuvuden

Datainmatning använder följande anpassade HTTP-rubriker.

Begäran

Svar

Begäranden

Använd HTTP POST-metoden för att skicka data till servern.

Datarepresentationen är inkluderad i begärandetexten som application/json.

Domännamnet är: mkto-ingestion-api.adobe.io

Sökvägen börjar med /subscriptions/MunchkinId där MunchkinId är specifik för din Marketo-instans. Du hittar ditt Munchkin-ID i Marketo Engage-gränssnittet under Admin > Mitt konto > Supportinformation. Resten av sökvägen används för att ange den givna resursen.

Exempel-URL för personer:

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

Exempel-URL för anpassade objekt:

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

Exempel-URL för företag:

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

Exempel-URL för programmedlemmar:

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

Exempel-URL för listor:

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

Svar

Alla svar returnerar ett unikt begärande-ID via huvudet X-Request-Id.

Exempel på begärande-ID via rubrik:

X-Request-Id: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Lyckades

När ett anrop lyckas returneras status 202. Ingen svarstext returneras.

Exempel på lyckat svar:

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

Fel

När ett anrop genererar ett fel returneras en status som inte är 202 tillsammans med ett svarstext med ytterligare felinformation. Svarstexten är application/json och innehåller ett enda objekt med medlemmarna error_code och message.

Nedan visas återanvända felkoder från Adobe Developer Gateway.

Nedan visas felkoder som är unika för API:t för datainmatning och som består av tre segment. De första tre siffrorna är statusen (returneras av Adobe Developer Gateway), följt av noll"0", följt av tre siffror.

Försök igen

När ett tillfälligt fel upptäcks försöker tjänsten utföra åtgärden igen. Försök görs på nytt av olika anledningar, i första hand när en beroende tjänst inte är tillgänglig eller inte är tillgänglig för tillfället.

Återförsöksintervall:

Slutpunkter

Slutpunkter för inmatning är tillgängliga för personer, anpassade objekt, företag, programmedlemmar och listor.

Personer

Slutpunkt som används för att infoga personposter.

Sidhuvuden

Begärandetext

Behörigheter som krävs är Read-Write Lead.

Exempel på personer

Begäran

POST /subscriptions/{munchkinId}/persons

Sidhuvuden

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

Brödtext

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

Svar

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Anpassade objekt

Slutpunkt som används för att infoga anpassade objektposter.

Sidhuvuden

Begärandetext

Nödvändiga behörigheter är Read-Write Custom Object.

Om ett länkfält till en person anges i begäran och den personen inte finns, görs flera försök. Om den personen läggs till under återförsöksfönstret (65 minuter) slutförs uppdateringen. Om länkfältet till exempel är email för person och personen inte finns, görs nya försök.

Exempel på anpassade objekt

Begäran

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

Sidhuvuden

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

Brödtext

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

Svar

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Företag

Slutpunkt som används för att synkronisera företagsposter. Stöder skapande, uppdatering och upsert-åtgärder med borttagning av dubbletter via externt företags-ID eller Marketo internt ID.

Sidhuvuden

Begärandetext

Varje företagsobjekt i arrayen input har stöd för följande fält:

Nödvändiga behörigheter är Read-Write Company.

Exempel på företag

Begäran

POST /subscriptions/{munchkinId}/companies

Sidhuvuden

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

Brödtext

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

Svar

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Exempel på företag som uppdaterar efter ID

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

Valideringsregler för företag

Programmedlemmar (synkronisera)

Slutpunkt som används för att synkronisera programmedlemmens status, lägga till leads till program eller uppdatera deras programstatus.

Sidhuvuden

Begärandetext

Varje objekt i arrayen programs innehåller:

Varje objekt i arrayen members innehåller:

Nödvändiga behörigheter är Read-Write Lead.

Exempel på synkronisering av programmedlemmar

Begäran

POST /subscriptions/{munchkinId}/programmembers

Sidhuvuden

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

Brödtext

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

Svar

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

Synkroniseringsverifieringsregler för programmedlemmar

Programmedlemmar (ta bort)

Slutpunkt som används för att ta bort leads från program. Detta ställer in leadets medlemskapsstatus till "Not in Program" och tar bort medlemmen från det programmet.

Sidhuvuden

Begärandetext

Varje objekt i arrayen programs innehåller:

Varje objekt i arrayen members innehåller:

Nödvändiga behörigheter är Read-Write Lead.

Exempel på borttagning av programmedlemmar

Begäran

POST /subscriptions/{munchkinId}/programmembers/delete

Sidhuvuden

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

Brödtext

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

Svar

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

Programmedlemmar tar bort valideringsregler

Listor (Lägg till i lista)

Slutpunkt som används för att lägga till leads till en statisk lista. Leads identifieras av deras Marketo lead-ID.

Sidhuvuden

Begärandetext

Varje objekt i indataarrayen innehåller:

Nödvändiga behörigheter är Read-Write Lead.

Listor som lagts till i listexempel

Begäran

POST /subscriptions/{munchkinId}/lists

Sidhuvuden

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

Brödtext

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

Svar

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Listor som läggs till i listvalideringsregler

Listor (Ta bort från lista)

Slutpunkt som används för att ta bort leads från en statisk lista. Leads identifieras av deras Marketo lead-ID.

Sidhuvuden

Begärandetext

Varje objekt i indataarrayen innehåller:

Nödvändiga behörigheter är Read-Write Lead.

Listor som tas bort från listexempel

Begäran

POST /subscriptions/{munchkinId}/lists/remove

Sidhuvuden

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

Brödtext

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

Svar

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

Listor som tas bort från listvalideringsregler

Gränser

Här är en uppdaterad lista över skyddsräcken:

Dessa begränsningar gäller enhetligt för personer, anpassade objekt, företag, programmedlemmar och listor. För programmedlemmar är"objekt per begäran" det totala antalet lead-referenser i alla program i en enda begäran. För listor är “objekt per begäran” antalet lead-referenser i indatarrayen.

API för datainmatning jämfört med REST API

Här är en lista över skillnader mellan API:t för datainmatning och andra Marketo REST-API