API di acquisizione dati

L’API di acquisizione dati è un servizio ad alto volume, a bassa latenza e a disponibilità elevata progettato per gestire in modo efficiente e con ritardi minimi l’acquisizione di grandi quantità di dati relativi a persone e persone.

I dati vengono acquisiti inviando le richieste eseguite in modo asincrono. È possibile recuperare lo stato della richiesta sottoscrivendo eventi da Marketo Observability Data Stream.

Le interfacce sono disponibili per quattro tipi di oggetto: Persone, Oggetti personalizzati, Aziende e Membri del programma. L'operazione di registrazione è solo "insert or update" (Inserisci o aggiorna), ad eccezione dei membri del programma che supportano anche l'eliminazione.

Autenticazione

L'API di acquisizione dati utilizza lo stesso metodo di autenticazione OAuth 2.0 dell'API REST di Marketo per generare un token di accesso, ma il token di accesso deve essere passato tramite l'intestazione HTTP X-Mkto-User-Token. Non è possibile passare il token di accesso tramite un parametro di query.

Esempio di token di accesso tramite intestazione:

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

Autorizzazioni

L’acquisizione dei dati utilizza lo stesso modello di autorizzazioni dell’API REST di Marketo e non richiede alcuna autorizzazione speciale aggiuntiva da utilizzare, anche se sono necessarie autorizzazioni specifiche per ogni endpoint.

Tipi di oggetto supportati

Intestazioni

L’acquisizione dei dati utilizza le seguenti intestazioni HTTP personalizzate.

Richiesta

Risposta

Richieste

Utilizzare il metodo HTTP POST per inviare dati al server.

La rappresentazione dei dati è inclusa nel corpo della richiesta come application/json.

Nome di dominio: mkto-ingestion-api.adobe.io

Il percorso inizia con /subscriptions/MunchkinId, dove MunchkinId è specifico per l'istanza Marketo. Puoi trovare il tuo Munchkin ID nell'interfaccia utente di Marketo Engage in Amministratore > Il mio account > Informazioni di supporto. Il resto del percorso viene utilizzato per specificare la risorsa di interesse.

URL di esempio per Persone:

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

URL di esempio per oggetti personalizzati:

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

URL di esempio per le società:

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

URL di esempio per i membri del programma:

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

Risposte

Tutte le risposte restituiscono un ID di richiesta univoco tramite l'intestazione X-Request-Id.

Esempio di ID richiesta tramite intestazione:

X-Request-Id: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Completato

Quando una chiamata ha esito positivo, viene restituito lo stato 202. Nessun corpo di risposta restituito.

Esempio di risposta di successo:

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

Errore

Quando una chiamata genera un errore, viene restituito uno stato non 202 insieme a un corpo della risposta con ulteriori dettagli sull’errore. Il corpo della risposta è application/json e contiene un singolo oggetto con i membri error_code e message.

Di seguito sono riportati i codici di errore riutilizzati da Adobe Developer Gateway.

Di seguito sono riportati i codici di errore univoci dell’API di acquisizione dati, composti da 3 segmenti. Le prime tre cifre sono lo stato (restituito da Adobe Developer Gateway), seguito da zero "0", seguito da tre cifre.

Nuovi tentativi

Quando viene rilevato un errore transitorio, il servizio ritenta l’operazione tre volte. Il primo nuovo tentativo si verifica dopo un periodo di attesa di 5 minuti, il secondo dopo altri 30 minuti e infine il terzo dopo altri 30 minuti. I tentativi si verificano per vari motivi, principalmente quando un servizio dipendente va in timeout o non è temporaneamente disponibile.

Endpoint

Gli endpoint di acquisizione sono disponibili per Persone, Oggetti personalizzati, Aziende e Membri del programma.

Persone

Endpoint utilizzato per eseguire l'upsert dei record persona.

Intestazioni

Corpo della richiesta

Le autorizzazioni richieste sono Read-Write Lead.

Esempio di persone

Richiesta

POST /subscriptions/{munchkinId}/persons

Intestazioni

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

Corpo

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

Risposta

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Oggetti personalizzati

Endpoint utilizzato per eseguire l'upsert dei record oggetto personalizzati.

Intestazioni

Corpo della richiesta

Le autorizzazioni necessarie sono Read-Write Custom Object.

Se nella richiesta è specificato un campo di collegamento a una persona e tale persona non esiste, si verificano diversi tentativi. Se la persona viene aggiunta durante la finestra dei nuovi tentativi (65 minuti), l’aggiornamento ha esito positivo. Ad esempio, se il campo del collegamento è e-mail su Persona e questa non esiste, si verifica un nuovo tentativo.

Esempio di oggetti personalizzati

Richiesta

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

Intestazioni

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

Corpo

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

Risposta

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Aziende

Endpoint utilizzato per sincronizzare i record aziendali. Supporta le operazioni di creazione, aggiornamento e upsert con deduplicazione tramite ID società esterno o ID interno Marketo.

Intestazioni

Corpo della richiesta

Ogni oggetto aziendale nell'array input supporta i campi seguenti:

Le autorizzazioni necessarie sono Read-Write Company.

Esempio di società

Richiesta

POST /subscriptions/{munchkinId}/companies

Intestazioni

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

Corpo

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

Risposta

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Esempio di aggiornamento società per ID

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

Regole di convalida società

Membri del programma (sincronizzazione)

Endpoint utilizzato per sincronizzare lo stato dei membri del programma, aggiungere lead ai programmi o aggiornarne lo stato.

Intestazioni

Corpo della richiesta

Ogni oggetto nell'array programs contiene:

Ogni oggetto nell'array members contiene:

Le autorizzazioni necessarie sono Read-Write Lead.

Esempio di sincronizzazione dei membri del programma

Richiesta

POST /subscriptions/{munchkinId}/programmembers

Intestazioni

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

Corpo

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

Risposta

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

Regole di convalida sincronizzazione membri programma

Membri del programma (eliminazione)

Endpoint utilizzato per rimuovere i lead dai programmi. Imposta lo stato di appartenenza del lead su "Not in Program" e rimuove il membro da tale programma.

Intestazioni

Corpo della richiesta

Ogni oggetto nell'array programs contiene:

Ogni oggetto nell'array members contiene:

Le autorizzazioni necessarie sono Read-Write Lead.

Esempio di eliminazione membri del programma

Richiesta

POST /subscriptions/{munchkinId}/programmembers/delete

Intestazioni

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

Corpo

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

Risposta

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

I membri del programma eliminano le regole di convalida

Limiti

Ecco un elenco aggiornato dei guardrail:

Questi limiti si applicano in modo uniforme a Persone, Oggetti personalizzati, Aziende e Membri del programma. Per i membri del programma, "oggetti per richiesta" è il numero totale di riferimenti lead in tutti i programmi in una singola richiesta.

API di acquisizione dati e API REST

Elenco delle differenze tra l’API di acquisizione dati e altre API REST di Marketo: