Extração de chumbo em massa

Referência de Ponto de Extremidade de Extração de Lead em Massa

As APIs REST de extração de lead em massa recuperam grandes conjuntos de registros de lead/pessoa da Marketo. Você também pode recuperar clientes em potencial de forma incremental com base na data de criação do registro, na atualização mais recente, na associação à lista estática ou na associação à lista inteligente.

Use a extração de leads em massa para a troca contínua de dados entre a Marketo e sistemas externos, incluindo ETL, data warehouse e workflows de arquivamento.

Permissões

O usuário da API que é proprietário do trabalho deve ter uma função com a permissão Lead somente leitura, com a permissão Lead de leitura e gravação ou com ambas as permissões.

Filtros

Os trabalhos de exportação de clientes potenciais são compatíveis com vários tipos de filtro. Cada trabalho de exportação pode usar apenas um tipo de filtro.

Os filtros updatedAt, smartListName e smartListId exigem uma infraestrutura que não está disponível em todas as assinaturas.

Os tipos de filtro marcados com um asterisco não estão disponíveis para algumas assinaturas. Se um tipo de filtro não estiver disponível para sua assinatura, o ponto de extremidade Criar trabalho de lead de exportação retornará o erro “1035, Tipo de filtro não suportado para assinatura de destino”. Entre em contato com o Suporte da Marketo para ativar essa funcionalidade para sua assinatura.

Opções

O ponto de extremidade Criar trabalho de lead de exportação fornece opções para selecionar campos exportados, renomear cabeçalhos de coluna e definir o formato de arquivo.

Criação de um trabalho

Use o ponto de extremidade Criar Trabalho de Exportação de Cliente Potencial para definir um trabalho de exportação. Especifique o fields a ser exportado, um tipo de filter e seus parâmetros, o arquivo format e qualquer nome de cabeçalho de coluna personalizado.

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

Essa solicitação cria um trabalho de exportação para clientes potenciais criados entre 1º de janeiro de 2017 e 31 de janeiro de 2017. A exportação inclui valores dos campos 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"
      }
   ]
}

A resposta confirma que o job foi criado, mas não foi iniciado. Para iniciar o trabalho, chame o ponto de extremidade Enfileirar Trabalho de Cliente Potencial para Exportação com o exportId da resposta de criação.

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
}

A resposta do enfileiramento tem um status de “Em fila”. Quando um slot de exportação se torna disponível, o status muda para “Processando”.

Status do trabalho de pesquisa

Você pode recuperar o status somente para trabalhos criados pelo mesmo usuário da API.

Os trabalhos de exportação de clientes potenciais são executados de forma assíncrona. Sonde o ponto de extremidade Obter Status do Trabalho de Cliente Potencial para Exportação para acompanhar o progresso do trabalho.

O status é atualizado apenas uma vez a cada 60 segundos. Não faça enquetes com mais frequência; em quase todos os casos, esse intervalo ainda é excessivo.

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

Essa resposta mostra que a tarefa ainda está sendo processada, portanto, o arquivo não está disponível. Quando o status do trabalho muda para “Concluído”, o arquivo está pronto para download.

O campo status pode retornar qualquer um dos seguintes valores:

Recuperação de dados

Para recuperar uma exportação de clientes potenciais concluída, chame o ponto de extremidade Obter Arquivo de Cliente Potencial para Exportação com o exportId.

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

O corpo da resposta contém o arquivo no formato configurado para o trabalho.

Se um campo de cliente potencial solicitado não contiver dados, o campo correspondente no arquivo de exportação conterá null. No exemplo a seguir, o lead retornado tem um campo de email vazio.

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

Para recuperação parcial ou retomável, o ponto de extremidade do arquivo dá suporte ao cabeçalho HTTP Range opcional com o tipo bytes. Se você não definir o cabeçalho, o endpoint retornará todo o conteúdo. Saiba mais sobre como usar o cabeçalho Range com a Extração em massa do Marketo.

Cancelar um trabalho

Para cancelar um trabalho desnecessário ou configurado incorretamente, chame o ponto de extremidade Cancelar Trabalho de Cliente Potencial para Exportação.

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

A resposta confirma que o processo foi cancelado.