Estrazione lead in blocco

Riferimento endpoint estrazione lead bulk

Le API REST Bulk Lead Extract recuperano set elevati di record di lead/persone da Marketo. Puoi anche 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.

Utilizza Bulk Lead Extract per lo scambio continuo di dati tra Marketo e i sistemi esterni, inclusi ETL, data warehousing e flussi di lavoro di archiviazione.

Autorizzazioni

L’utente API proprietario del processo deve disporre di un ruolo con l’autorizzazione Lead di sola lettura, l’autorizzazione Lead di lettura/scrittura o entrambe le autorizzazioni.

Filtri

I processi di esportazione dei lead supportano diversi tipi di filtro. Ogni processo di esportazione può utilizzare un solo tipo di filtro.

I filtri updatedAt, smartListName e smartListId richiedono un’infrastruttura non disponibile in tutte le sottoscrizioni.

I tipi di filtro contrassegnati con un asterisco non sono disponibili per alcune sottoscrizioni. Se un tipo di filtro non è disponibile per la sottoscrizione, l’endpoint Crea processo lead di esportazione restituisce l’errore “1035, tipo di filtro non supportato per la sottoscrizione di destinazione”. Contatta il supporto Marketo per abilitare questa funzionalità per il tuo abbonamento.

Opzioni

L’endpoint “Crea processo lead di esportazione” fornisce opzioni per selezionare i campi esportati, rinominare le intestazioni di colonna e impostare il formato del file.

Creazione di un processo

Utilizza l’endpoint Crea processo lead esportazione per definire un processo di esportazione. Specificare fields da esportare, un tipo filter e i relativi parametri, il file format ed eventuali nomi di intestazione di colonna personalizzati.

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 crea un processo di esportazione per i lead creati tra il 1° gennaio 2017 e il 31 gennaio 2017. L’esportazione include i valori dei campi firstName, lastName, id e email.

{
   "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"
      }
   ]
}

La risposta conferma che il processo è stato creato ma non avviato. Per avviare il processo, chiama l’endpoint Accoda processo lead esportazione con exportId dalla risposta 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
}

La risposta di accodamento ha un status di “In coda”. Quando uno slot di esportazione diventa disponibile, lo stato cambia in “Elaborazione”.

Stato processo di polling

Puoi recuperare lo stato solo per i processi creati dallo stesso utente API.

I processi di esportazione dei lead vengono eseguiti in modo asincrono. Esamina l’endpoint Ottieni stato processo lead esportazione per tenere traccia dell’avanzamento del processo.

Lo stato viene aggiornato una sola volta ogni 60 secondi. Non eseguire il polling con maggiore frequenza; nella maggior parte dei casi, tale intervallo è ancora eccessivo.

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"
      }
   ]
}

Questa risposta indica che il processo è ancora in elaborazione, quindi il file non è disponibile. Quando lo stato del processo diventa “Completato”, il file è pronto per il download.

Il campo status può restituire uno dei seguenti valori:

Recupero dei dati

Per recuperare un’esportazione del lead completata, chiamare l’endpoint Get Export Lead File con exportId.

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

Il corpo della risposta contiene il file nel formato configurato per il processo.

Se un campo lead richiesto non contiene dati, il campo corrispondente nel file di esportazione contiene null. Nell’esempio seguente, il lead restituito ha un campo e-mail vuoto.

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

Per il recupero parziale o ripristinabile, l’endpoint del file supporta l’intestazione HTTP Range facoltativa con il tipo bytes. Se non imposti l’intestazione, l’endpoint restituisce tutto il contenuto. Ulteriori informazioni sull’utilizzo dell’intestazione Range con Marketo Bulk Extract.

Annullamento di un processo

Per annullare un processo non configurato correttamente o non necessario, chiamare 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"
      }
   ]
}

La risposta conferma l’annullamento del processo.