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 cinque tipi di oggetto: Persone, Oggetti personalizzati, Aziende, Membri del programma ed Elenchi (Elenchi statici). L’operazione di registrazione è solo “insert or update”, fatta eccezione per i membri del programma che supportano anche le operazioni di eliminazione, e per gli elenchi che supportano le operazioni di aggiunta e rimozione.

Leggi la documentazione sull’API di acquisizione dati.

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

URL di esempio per gli elenchi:

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

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 temporaneo, il servizio tenta di eseguire nuovamente l’operazione. I tentativi si verificano per vari motivi, principalmente quando un servizio dipendente va in timeout o non è temporaneamente disponibile.

Intervalli tentativi:

Endpoint

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

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 è email per Persona e Persona non esiste, si verificano nuovi tentativi.

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

Elenchi (Aggiungi all’elenco)

L’endpoint utilizzato per aggiungere lead a un elenco statico. I lead sono identificati dal relativo ID lead Marketo.

Intestazioni

Corpo della richiesta

Ogni oggetto nell’array di input contiene:

Le autorizzazioni necessarie sono Read-Write Lead.

Esempi di elenchi da aggiungere all’elenco

Richiesta

POST /subscriptions/{munchkinId}/lists

Intestazioni

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

Corpo

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

Risposta

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

Elenchi da aggiungere alle regole di convalida dell’elenco

Elenchi (Rimuovi dall’elenco)

Endpoint utilizzato per rimuovere i lead da un elenco statico. I lead sono identificati dal relativo ID lead Marketo.

Intestazioni

Corpo della richiesta

Ogni oggetto nell’array di input contiene:

Le autorizzazioni necessarie sono Read-Write Lead.

Elenchi rimossi dall’elenco

Richiesta

POST /subscriptions/{munchkinId}/lists/remove

Intestazioni

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

Corpo

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

Risposta

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

Elenchi rimossi dalle regole di convalida dell’elenco

Limiti

Ecco un elenco aggiornato dei guardrail:

Questi limiti si applicano in modo uniforme a Persone, Oggetti personalizzati, Società, Membri del programma ed Elenchi. Per i membri del programma, “oggetti per richiesta” è il numero totale di riferimenti lead in tutti i programmi in una singola richiesta. Per Elenchi, “oggetti per richiesta” è il numero di riferimenti di lead nell’array di input.

API di acquisizione dati e API REST

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