Documentazione Guida per sviluppatori di Marketo

Estrazione oggetto personalizzato in blocco

Last update: Mon Jul 22 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Argomenti:
Oggetti personalizzati

Creato per:

Amministratore

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.

Tipo di filtro

Tipo di dati

Note

updatedAt

Intervallo date

Accetta un oggetto JSON con i membri startAt e endAt &nbsp.;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.

staticListName

Stringa

Accetta il nome di un elenco statico. I processi con questo tipo di filtro restituiscono tutti i record accessibili che sono membri dell'elenco statico al momento dell'inizio dell'elaborazione del processo. Recuperare i nomi di elenco statici utilizzando l'endpoint Get Lists.

staticListId

Intero

Accetta l’ID di un elenco statico. I processi con questo tipo di filtro restituiscono tutti i record accessibili che sono membri dell'elenco statico al momento dell'inizio dell'elaborazione del processo. Recupera gli ID di elenco statici utilizzando l’endpoint Get Lists.

smartListName*

Stringa

Accetta il nome di un elenco avanzato. I processi con questo tipo di filtro restituiscono tutti i record accessibili che sono membri degli elenchi smart nel momento in cui il processo inizia l'elaborazione. Recupera i nomi degli elenchi smart utilizzando l’endpoint Get Smart Lists.

smartListId*

Intero

Accetta l’ID di un elenco avanzato. I processi con questo tipo di filtro restituiscono tutti i record accessibili che sono membri degli elenchi smart nel momento in cui il processo inizia l'elaborazione. Recupera gli ID degli elenchi avanzati utilizzando l’endpoint Ottieni elenchi avanzati.

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

Parametro

Tipo di dati

Obbligatorio

Note

fields

Array[Stringa]

Sì

Array di stringhe contenenti il valore del nome dell'attributo dell'oggetto personalizzato restituito dall'endpoint Describe Custom Object. I campi elencati sono inclusi nel file esportato.

columnHeaderNames

Oggetto

No

Oggetto JSON contenente coppie chiave-valore di nomi di intestazione di campo e colonna. La chiave deve essere il nome di un campo incluso nel processo di esportazione. Il valore corrisponde al nome dell'intestazione di colonna esportata per il campo.

format

Stringa

No

Accetta uno di: CSV, TSV, SSV. Il file esportato viene renderizzato rispettivamente come un file di valori separati da virgole, valori separati da tabulazioni o valori separati da spazi, se impostato. Se non impostato, viene impostato il valore predefinito CSV.

Creazione 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

Oggetto personalizzato

Campi oggetto personalizzati

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 intuitivo dei dati estratti, l’endpoint del file supporta facoltativamente l’intervallo di intestazioni HTTP dei byte di tipo. 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
}

recommendation-more-help