Estrazione oggetto personalizzato in blocco
Riferimento all'endpoint di estrazione oggetto personalizzato in blocco
Il set Bulk Custom Object Extract delle API REST fornisce un’interfaccia programmatica per recuperare set elevati di record di oggetti personalizzati da Marketo. Si tratta dell'interfaccia consigliata per i casi d'uso che richiedono l'interscambio continuo di dati tra Marketo e uno o più sistemi esterni, a scopo di ETL, data warehousing e archiviazione.
Questa API supporta l’esportazione di record di oggetti personalizzati Marketo di primo livello collegati direttamente a un lead. Passa il nome dell’oggetto personalizzato e un elenco di lead a cui l’oggetto è collegato. Per ogni lead dell'elenco, i record oggetto personalizzati collegati che corrispondono al nome oggetto personalizzato specificato vengono scritti come righe nel file di esportazione. I dati oggetto personalizzato sono visualizzabili nella scheda Oggetto personalizzato della pagina dei dettagli del lead nell'interfaccia utente di Marketo.
Autorizzazioni
Le API Bulk Custom Object Extract richiedono che l’utente API abbia un ruolo con una o entrambe le autorizzazioni "Read-Only Custom Object" (Oggetto personalizzato di sola lettura) o "Read-Write Custom Object" (Oggetto personalizzato di lettura/scrittura).
Filtri
L’estrazione dell’oggetto personalizzato supporta diverse opzioni di filtro utilizzate per specificare un elenco di lead collegati all’oggetto personalizzato. Se un lead nell'elenco è collegato a record oggetto personalizzati che corrispondono a un determinato nome oggetto personalizzato, i record vengono scritti nel file di esportazione. È possibile specificare un solo tipo di filtro per processo di esportazione.
updatedAtstartAt e endAt  .;startAt accetta un datetime che rappresenta la filigrana minima e endAt accetta un datetime che rappresenta la filigrana massima. L’intervallo non può essere superiore a 31 giorni. I processi con questo tipo di filtro restituiscono tutti i record accessibili che sono stati aggiornati entro l’intervallo di date. I valori di data devono essere in formato ISO-8601, senza millisecondi.staticListNamestaticListIdsmartListName*smartListId*Il tipo di filtro non è disponibile per alcune sottoscrizioni. Se non disponibile per la sottoscrizione, viene visualizzato un errore durante la chiamata dell’endpoint del processo Crea lead di esportazione ("1035, tipo di filtro non supportato per la sottoscrizione di destinazione"). I clienti possono contattare il supporto tecnico Marketo per richiedere che questa funzionalità sia abilitata nel loro abbonamento.
Opzioni
L'endpoint Crea processo di esportazione oggetto personalizzato fornisce diverse opzioni di formattazione. Queste opzioni consentono all'utente di:
- Specificare i campi da includere nel file esportato
- Rinomina le intestazioni di colonna di questi campi
- Specifica il formato del file esportato
fieldscolumnHeaderNamesformatCreazione di un processo
I parametri per il processo vengono definiti prima di avviare l'esportazione utilizzando l'endpoint Crea processo di esportazione oggetto personalizzato.
Il parametro di percorso apiName richiesto è il nome dell'oggetto personalizzato restituito dall'endpoint Descrivi oggetto personalizzato. Specifica quale oggetto personalizzato Marketo esportare. Gli oggetti personalizzati CRM non sono consentiti. Il parametro filter richiesto contiene l'elenco dei lead collegati all'oggetto personalizzato. Può fare riferimento a un elenco statico o a un elenco avanzato. Il parametro fields obbligatorio contiene i nomi API degli attributi oggetto personalizzati da includere nel file di esportazione. Facoltativamente, è possibile definire format del file e columnHeaderNames.
Ad esempio, supponiamo di aver creato un oggetto personalizzato denominato "Car" con i seguenti campi: Color, Make, Model, VIN. Il campo del collegamento è l’ID del lead e il campo della deduplicazione è VIN.
Definizione oggetto personalizzato
Campi oggetto personalizzati
È possibile chiamare Descrivi oggetto personalizzato per controllare a livello di programmazione gli attributi dell'oggetto personalizzato visualizzati nell'attributo fields nella risposta.
GET /rest/v1/customobjects/car_c/describe.json
{
"requestId": "148ef#1793e00f64f",
"result": [
{
"name": "car_c",
"displayName": "Car",
"description": "It's a car.",
"createdAt": "2021-05-05T16:14:41Z",
"updatedAt": "2021-05-05T16:14:42Z",
"idField": "marketoGUID",
"dedupeFields": [
"vIN"
],
"searchableFields": [
[
"vIN"
],
[
"marketoGUID"
],
[
"leadID"
]
],
"relationships": [
{
"field": "leadID",
"type": "child",
"relatedTo": {
"name": "Lead",
"field": "Id"
}
}
],
"fields": [
{
"name": "createdAt",
"displayName": "Created At",
"dataType": "datetime",
"updateable": false,
"crmManaged": false
},
{
"name": "marketoGUID",
"displayName": "Marketo GUID",
"dataType": "string",
"length": 36,
"updateable": false,
"crmManaged": false
},
{
"name": "updatedAt",
"displayName": "Updated At",
"dataType": "datetime",
"updateable": false,
"crmManaged": false
},
{
"name": "color",
"displayName": "Color",
"dataType": "string",
"length": 255,
"updateable": true,
"crmManaged": false
},
{
"name": "leadID",
"displayName": "Lead ID",
"dataType": "integer",
"updateable": true,
"crmManaged": false
},
{
"name": "make",
"displayName": "Make",
"dataType": "string",
"length": 255,
"updateable": true,
"crmManaged": false
},
{
"name": "model",
"displayName": "Model",
"dataType": "string",
"length": 255,
"updateable": true,
"crmManaged": false
},
{
"name": "vIN",
"displayName": "VIN",
"dataType": "string",
"length": 255,
"updateable": true,
"crmManaged": false
}
]
}
],
"success": true
}
Crea diversi record di oggetti personalizzati e collegali a un lead diverso utilizzando l'endpoint Sincronizza oggetti personalizzati. Un lead può essere collegato a molti record di oggetti personalizzati. Questa è nota come relazione "uno a molti".
POST /rest/v1/customobjects/car_c.json
{
"action":"createOrUpdate",
"input":[
{
"leadId": 11,
"color": "Pearl White",
"make": "Tesla",
"model": "Model S",
"vIN": "5YJSA1E41FF156789"
},
{
"leadId": 12,
"color": "Midnight Silver Metallic",
"make": "Tesla",
"model": "Model X",
"vIN": "LRWXB2B41FF198765"
},
{
"leadId": 13,
"color": "Fusion Red",
"make": "Tesla",
"model": "Roadster",
"vIN": "SFGRC3C41FF154321"
}
]
}
{
"requestId": "50d9#1793e066088",
"result": [
{
"seq": 0,
"marketoGUID": "d911eaa1-fd0b-4a99-9b71-c6a7233c782c",
"status": "created"
},
{
"seq": 1,
"marketoGUID": "20d04ffb-51f0-4336-924c-c783b9bb4215",
"status": "created"
},
{
"seq": 2,
"marketoGUID": "e7da4331-8e7a-473b-85c8-047638eb6c7f",
"status": "created"
}
],
"success": true
}
Ciascuno dei tre lead a cui si fa riferimento in precedenza appartiene a un elenco statico denominato "Acquirenti auto" il cui id è 1081, come illustrato di seguito, chiamando l'endpoint Ottieni lead per ID elenco.
GET /rest/v1/lists/1081/leads.json
{
"requestId": "d023#1793e1e982b",
"result": [
{
"id": 11,
"firstName": "Hanna",
"lastName": "Crawford",
"email": "208161Hanna.Crawford@pookmail.com",
"updatedAt": "2020-01-16T02:38:22Z",
"createdAt": "2017-07-27T01:38:42Z"
},
{
"id": 12,
"firstName": "Bertha",
"lastName": "Fulton",
"email": "208160Bertha.Fulton@trashymail.com",
"updatedAt": "2020-01-16T02:38:22Z",
"createdAt": "2017-07-27T01:38:42Z"
},
{
"id": 13,
"firstName": "Faith",
"lastName": "England",
"email": "208159Faith.England@dodgit.com",
"updatedAt": "2020-01-16T02:38:22Z",
"createdAt": "2017-07-27T01:38:42Z"
}
],
"success": true
}
Ora creiamo un processo di esportazione per recuperare questi record. Utilizzando l'endpoint Crea processo di esportazione oggetto personalizzato, vengono specificati gli attributi dell'oggetto personalizzato nel parametro fields e un ID di elenco statico nel parametro filter.
POST /bulk/v1/customobjects/car_c/export/create.json
{
"fields": [
"leadId",
"color",
"make",
"model",
"vIN"
],
"filter": {
"staticListId": 1081
}
}
{
"requestId": "8d2f#1793e289e87",
"result": [
{
"exportId": "f2c03f1d-226f-47c1-a557-357af8c2b32a",
"format": "CSV",
"status": "Created",
"createdAt": "2021-05-05T20:12:01Z"
}
],
"success": true
}
Nella risposta viene restituito uno stato che indica che il processo è stato creato. Il processo è stato definito e creato, ma non è ancora stato avviato. Per eseguire questa operazione, è necessario chiamare l'endpoint Processo oggetto personalizzato esportazione accodamento utilizzando apiName e exportId dalla risposta dello stato di creazione.
POST /bulk/v1/customobjects/car_c/export/f2c03f1d-226f-47c1-a557-357af8c2b32a/enqueue.json
{
"requestId": "cfaf#1793e2a0762",
"result": [
{
"exportId": "f2c03f1d-226f-47c1-a557-357af8c2b32a",
"format": "CSV",
"status": "Queued",
"createdAt": "2021-05-05T20:12:01Z",
"queuedAt": "2021-05-05T20:13:32Z"
}
],
"success": true
}
Questo risponde con un status iniziale di "In coda" dopo il quale è impostato su "Elaborazione" quando è disponibile uno slot di esportazione.
Stato processo di polling
Lo stato può essere recuperato solo per i processi creati dallo stesso utente API.
Poiché si tratta di un endpoint asincrono, dopo la creazione del processo è necessario eseguire il polling del relativo stato per determinarne l’avanzamento. Eseguire il polling utilizzando l'endpoint Ottieni stato processo di esportazione oggetto personalizzato. Lo stato viene aggiornato solo una volta ogni 60 secondi, pertanto non è consigliabile una frequenza di polling inferiore a questa, e in quasi tutti i casi è ancora eccessiva. Il campo di stato può rispondere con uno dei seguenti valori: Creato, In coda, Elaborazione, Annullato, Completato o Non riuscito.
GET /bulk/v1/customobjects/{apiName}/export/{exportId}/status.json
{
"requestId": "14daa#1793e2cf9de",
"result": [
{
"exportId": "f2c03f1d-226f-47c1-a557-357af8c2b32a",
"format": "CSV",
"status": "Processing",
"createdAt": "2021-05-05T20:12:01Z",
"queuedAt": "2021-05-05T20:13:32Z",
"startedAt": "2021-05-05T20:14:15Z"
}
],
"success": true
}
L’endpoint di stato risponde indicando che il processo è ancora in elaborazione, pertanto il file non è ancora disponibile per il recupero. Quando il processo status diventa "Completato", è disponibile per il download.
{
"requestId": "14daa#1793e2cf9de",
"result": [
{
"exportId": "f2c03f1d-226f-47c1-a557-357af8c2b32a",
"format": "CSV",
"status": "Completed",
"createdAt": "2021-05-05T20:12:01Z",
"queuedAt": "2021-05-05T20:13:32Z",
"startedAt": "2021-05-05T20:14:15Z",
"finishedAt": "2021-05-05T20:14:28Z",
"numberOfRecords": 3,
"fileSize": 182,
"fileChecksum": "sha256:fac0cabc2352229c12e18b2fde03d1f24178bc71e9e926f520ae8d61bbe98c01"
}
],
"success": true
}
Recupero dei dati
Per recuperare il file di un'esportazione di oggetti personalizzati completata, è sufficiente chiamare l'endpoint Get Export Custom Object File con apiName e exportId.
La risposta contiene un file formattato nel modo in cui è stato configurato il processo. L’endpoint risponde con il contenuto del file. Se un attributo oggetto personalizzato richiesto è vuoto (non contiene dati), null viene inserito nel campo corrispondente nel file di esportazione.
GET /bulk/v1/customobjects/car_c/export/f2c03f1d-226f-47c1-a557-357af8c2b32a/file.json
leadId,color,make,model,vIN
11,Pearl White,Tesla,Model S,5YJSA1E41FF156789
12,Midnight Silver Metallic,Tesla,Model X,LRWXB2B41FF198765
13,Fusion Red,Tesla,Roadster,SFGRC3C41FF154321
Per supportare il recupero parziale e semplice dei dati estratti, l'endpoint del file supporta facoltativamente l'intestazione HTTP Range di tipo bytes. Se l’intestazione non è impostata, verrà restituito l’intero contenuto. Ulteriori informazioni sull'utilizzo dell'intestazione Range in Marketo Bulk Extract.
Annullamento di un processo
Se un processo non è stato configurato correttamente o non è più necessario, può essere facilmente annullato utilizzando l'endpoint Annulla esportazione processo oggetto personalizzato. Questo risponde con un status che indica che il processo è stato annullato.
POST /bulk/v1/customobjects/car_c/export/f2c03f1d-226f-47c1-a557-357af8c2b32a/cancel.json
{
"requestId": "e5f9#179391286a7",
"result": [
{
"exportId": "4a8cdd80-0d16-4dd6-9923-6ec97e30e91b",
"format": "CSV",
"status": "Cancelled",
"createdAt": "2021-05-04T20:24:33Z"
}
],
"success": true
}