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 due tipi di oggetto: Persone, Oggetti personalizzati. L'operazione di registrazione è solo "insert or update" (Inserisci o aggiorna).

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.

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

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 e Oggetti personalizzati.

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"
      },
      {
         "email": "johnny.neal@yvu30.com",
         "firstName": "Johnny",
         "lastName": "Neal"
      }
   ]
}

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

Limiti

Elenco di utilizzo dei guardrail:

API di acquisizione dati e API REST

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