API di acquisizione dati
Creato per:
- Amministratore
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).
L’API di acquisizione dati è attualmente in versione beta privata. Gli invitati devono avere un diritto per il pacchetto Livello prestazioni Marketo Engage.
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.
| Endpoint | Autorizzazione |
|---|---|
| Persone | Lead di lettura/scrittura |
| Oggetti personalizzati | Oggetto personalizzato di lettura/scrittura |
Intestazioni
L’acquisizione dei dati utilizza le seguenti intestazioni HTTP personalizzate.
Richiesta
| Chiave | Valore | Obbligatorio | Descrizione |
|---|---|---|---|
| X-Correlation-Id | Stringa arbitraria (lunghezza massima 255 caratteri). | No | Può essere utilizzato per tracciare le richieste attraverso il sistema. Consulta Flusso di dati di osservabilità Marketo |
| X-Request-Source | Stringa arbitraria (lunghezza massima 50 caratteri). | No | Può essere utilizzato per tracciare l’origine delle richieste tramite il sistema. Consulta Flusso di dati di osservabilità Marketo |
Risposta
| Chiave | Valore | Obbligatorio |
|---|---|---|
| X-Request-Id | ID richiesta univoco. | Sì |
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 ID Munchkin nell'interfaccia utente del 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
Operazione riuscita
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
In un'operazione AND vengono utilizzati due attributi. Se ad esempio si specificano sia
email che firstName, verranno entrambi utilizzati per cercare una persona tramite l'operazione AND.Attributi supportati:
id, email, sfdcAccountId, sfdcContactId, sfdcLeadId sfdcLeadOwnerId, Attributi personalizzati (solo tipo "stringa" e "numero intero"), emailLe autorizzazioni richieste sono Read-Write Lead.
Esempio di persone
Richiesta
POST /subscriptions/{munchkinId}/persons
Intestazioni
Content-Type: application/jsonX-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 202X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw
Oggetti personalizzati
Endpoint utilizzato per eseguire l'upsert dei record oggetto personalizzati
/subscriptions/{munchkinId}/customobjects/{customObjectAPIName}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/jsonX-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 202X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw
Limiti
Elenco di utilizzo dei guardrail:
- Dimensione massima della richiesta: 1 MB
- Massimo oggetti per richiesta per tipo di oggetto: 1.000
- Numero massimo di richieste al secondo per ID client: 5.000
- Massimo oggetti al giorno: 10.000.000
API di acquisizione dati e API REST
Elenco delle differenze tra l’API di acquisizione dati e altre API REST di Marketo:
- Questa non è un'interfaccia CRUD completa, ma supporta solo upsert
- Per eseguire l'autenticazione, devi passare il token di accesso utilizzando l'intestazione
X-Mkto-User-Token - Il nome di dominio URL è
mkto-ingestion-api.adobe.io - Il percorso URL inizia con
/subscriptions/MunchkinId - Nessun parametro di query
- Se la chiamata ha esito positivo, viene restituito lo stato 202 e il corpo della risposta è vuoto
- Se la chiamata non riesce, viene restituito uno stato non 202 e il corpo della risposta contiene
{ "error_code" : "Error Code", "message" : "Message" } - L'ID della richiesta viene restituito tramite l'intestazione
X-Request-Id