Estrazione lead in blocco

Riferimento endpoint estrazione lead bulk

Il set Bulk Lead Extract delle API REST fornisce un’interfaccia programmatica per recuperare set elevati di record di lead/persone da Marketo. Inoltre, può essere utilizzato per recuperare i lead in modo incrementale in base alla data di creazione del record, all’aggiornamento più recente, all’iscrizione all’elenco statico o all’iscrizione all’elenco avanzato. L'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.

Autorizzazioni

Le API Bulk Lead Extract richiedono che l’utente API proprietario abbia un ruolo con una o entrambe le autorizzazioni Read-Only Lead o Read-Write Lead.

Filtri

I lead supportano varie opzioni di filtro. Alcuni filtri, tra cui updatedAt, smartListName e smartListId, richiedono componenti di infrastruttura aggiuntivi non ancora implementati in tutte le sottoscrizioni. È possibile specificare un solo tipo di filtro per processo di esportazione.

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 del processo Crea lead di esportazione offre diverse opzioni di formattazione, consentendo all’utente di includere campi particolari all’interno del file esportato, la possibilità di rinominare le intestazioni di colonna di tali campi e il formato del file esportato.

Creazione di un processo

I parametri per il processo vengono definiti prima di avviare l'esportazione utilizzando l'endpoint Crea processo lead esportazione. È necessario definire fields necessari per l'esportazione, il tipo di parametri di filter, format del file e gli eventuali nomi di intestazione di colonna.

POST /bulk/v1/leads/export/create.json

{
   "fields": [
      "firstName",
      "lastName",
      "id",
      "email"
   ],
   "format": "CSV",
   "columnHeaderNames": {
      "firstName": "First Name",
      "lastName": "Last Name",
      "id": "Marketo Id",
      "email": "Email Address"
   },
   "filter": {
      "createdAt": {
         "startAt": "2017-01-01T00:00:00Z",
         "`endAt`": "2017-01-31T00:00:00Z"
      }
   }
}

Questa richiesta inizierà l'esportazione di un set di lead creati tra il 1° gennaio 2017 e il 31 gennaio 2017, inclusi i valori dei campi firstName, lastName, id e email corrispondenti.

{
   "requestId": "e42b#14272d07d78",
   "success": true,
   "result": [
      {
         "exportId": "ce45a7a1-f19d-4ce2-882c-a3c795940a7d",
         "status": "Created",
         "createdAt": "2017-01-21T11:47:30-08:00",
         "queuedAt": "2017-01-21T11:48:30-08:00",
         "format": "CSV"
      }
   ]
}

Restituisce una risposta di stato che indica che il processo è stato creato. Il processo è stato definito e creato, ma non è ancora stato avviato. A tale scopo, l'endpoint Processo lead esportazione accodamento deve essere chiamato utilizzando il valore exportId dalla risposta dello stato di creazione:

POST /bulk/v1/leads/export/{exportId}/enqueue.json

{
    "requestId": "147e4#16b24d9b913",
    "result": [
        {
            "exportId": "fad2cd1b-e822-4025-be1e-9caa9cf1d4b8",
            "format": "CSV",
            "status": "Queued",
            "createdAt": "2019-06-04T23:35:43Z",
            "queuedAt": "2019-06-04T23:36:17Z"
        }
    ],
    "success": true
}

Questo risponde con un status di "In coda" dopo il quale verrà impostato su "Elaborazione" quando è disponibile uno slot di esportazione.

Stato processo di polling

È possibile recuperare lo stato Note: solo per i processi creati dallo stesso utente API.

Poiché si tratta di un endpoint asincrono, dopo la creazione del processo è necessario eseguire un polling del relativo stato per determinarne l’avanzamento. Eseguire il polling utilizzando l'endpoint Ottieni stato processo lead esportazione. 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. Diamo un'occhiata ai sondaggi.

GET /bulk/v1/leads/export/{exportId}/status.json

{
   "requestId": "e42b#14272d07d78",
   "success": true,
   "result": [
      {
         "exportId": "ce45a7a1-f19d-4ce2-882c-a3c795940a7d",
         "status": "Processing",
         "createdAt": "2017-01-21T11:47:30-08:00",
         "queuedAt": "2017-01-21T11:48:30-08:00",
         "format": "CSV"
      }
   ]
}

L’endpoint di stato risponde indicando che il processo è ancora in elaborazione, pertanto il file non è ancora disponibile per il recupero. Una volta che lo stato del processo cambia in "Completato", si è preparato per il download.

Il campo di stato può rispondere con uno qualsiasi dei seguenti elementi:

Recupero dei dati

Per recuperare il file di un'esportazione lead completata, è sufficiente chiamare l'endpoint Ottieni file lead esportazione con exportId.

GET /bulk/v1/leads/export/{exportId}/file.json

La risposta contiene un file formattato nel modo in cui è stato configurato il processo. L’endpoint risponde con il contenuto del file.

Se un campo lead richiesto è vuoto (non contiene dati), null viene inserito nel campo corrispondente nel file di esportazione. Nell’esempio seguente, il campo e-mail per il lead restituito è vuoto.

firstName,lastName,email,cookies
Russell,Wilson,null,_mch-localhost-1536605780000-12105

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, viene restituito l’intero contenuto. Ulteriori informazioni sull'utilizzo dell'intestazione Range con 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 processo lead esportazione:

POST /bulk/v1/leads/export/{exportId}/cancel.json

{
   "requestId": "e42b#14272d07d78",
   "success": true,
   "result": [
      {
         "exportId": "ce45a7a1-f19d-4ce2-882c-a3c795940a7d",
         "status": "Cancelled",
         "createdAt": "2017-01-21T11:47:30-08:00",
         "format": "CSV"
      }
   ]
}

Questo risponde con uno stato che indica che il processo è stato annullato.