Extração de chumbo em massa

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

O conjunto de Extração de lead em massa de APIs REST fornece uma interface programática para recuperar grandes conjuntos de registros de lead/pessoa do Marketo. Além disso, ele pode ser usado para recuperar clientes potenciais de forma incremental com base na data de criação do registro, na atualização mais recente, na associação de lista estática ou na associação de lista inteligente. A interface recomendada para casos de uso que exigem intercâmbio contínuo de dados entre o Marketo e um ou mais sistemas externos, para fins de ETL, data warehouse e arquivamento.

Permissões

As APIs de Extração de lead em massa exigem que o usuário da API responsável tenha uma função com uma ou ambas as permissões de Lead somente leitura ou Lead de leitura e gravação.

Filtros

Os clientes em potencial são compatíveis com várias opções de filtro. Determinados filtros, incluindo updatedAt, smartListName e smartListId, exigem componentes de infraestrutura adicionais que ainda não foram implementados em todas as assinaturas. Somente um tipo de filtro pode ser especificado por trabalho de exportação.

O tipo de filtro não está disponível para algumas assinaturas. Se não estiver disponível para sua assinatura, você receberá um erro ao chamar o endpoint Criar trabalho de lead de exportação ("1035, Tipo de filtro não suportado para assinatura de destino"). Os clientes podem entrar em contato com o Suporte da Marketo para ativar essa funcionalidade em suas assinaturas.

Opções

O ponto de extremidade Criar trabalho de lead de exportação fornece várias opções de formatação, dando ao usuário a capacidade de incluir campos específicos no arquivo exportado, a capacidade de renomear cabeçalhos de coluna desses campos e o formato do arquivo exportado.

Criação de um trabalho

Os parâmetros do trabalho são definidos antes do início da exportação usando o ponto de extremidade Criar Trabalho de Cliente Potencial para Exportação. Devemos definir os fields necessários para a exportação, o tipo de parâmetros do filter, o format do arquivo e os nomes de cabeçalho de coluna, se houver.

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

Esta solicitação começará a exportar um conjunto de clientes potenciais criados entre 1º de janeiro de 2017 e 31 de janeiro de 2017, incluindo os valores dos campos firstName, lastName, id e email correspondentes.

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

Isso retorna uma resposta de status indicando que o processo foi criado. A tarefa foi definida e criada, mas ainda não foi iniciada. Para fazer isso, o ponto de extremidade Enfileirar Trabalho de Cliente Potencial de Exportação deve ser chamado usando o exportId da resposta do status 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
}

Isso responde com uma status de "Em fila", após a qual será definido como "Processando" quando houver um slot de exportação disponível.

Status do trabalho de pesquisa

O status Note: só pode ser recuperado para trabalhos que foram criados pelo mesmo usuário da API.

Como esse é um endpoint assíncrono, depois de criar o trabalho, devemos pesquisar seu status para determinar seu progresso. Sondar usando o ponto de extremidade Obter Status do Trabalho de Cliente Potencial para Exportação. O status só é atualizado uma vez a cada 60 segundos, portanto, uma frequência de polling inferior a essa não é recomendada e, em quase todos os casos, ainda é excessiva. Vamos dar uma olhada na pesquisa.

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

O endpoint de status responde indicando que o trabalho ainda está sendo processado, portanto, o arquivo ainda não está disponível para recuperação. Quando o status do trabalho for alterado para "Concluído", ele foi preparado para download.

O campo de status pode responder com qualquer um dos seguintes:

Recuperação de dados

Para recuperar o arquivo de uma exportação de clientes potenciais concluída, basta chamar o Obter Arquivo de Cliente Potencial para Exportação com seu exportId.

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

A resposta contém um arquivo formatado da maneira que o trabalho foi configurado. O endpoint responde com o conteúdo do arquivo.

Se um campo de cliente em potencial solicitado estiver vazio (não contiver dados), null será colocado no campo correspondente no arquivo de exportação. No exemplo abaixo, o campo de email do lead retornado está vazio.

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

Para oferecer suporte à recuperação parcial e de fácil retomada dos dados extraídos, o endpoint do arquivo oferece suporte opcional ao Intervalo do cabeçalho HTTP do tipo bytes. Se o cabeçalho não estiver definido, todo o conteúdo será retornado. Leia mais sobre como usar o cabeçalho Intervalo com a Extração em massa do Marketo.

Cancelar um trabalho

Se um trabalho for configurado incorretamente ou se se tornar desnecessário, ele poderá ser facilmente cancelado usando 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"
      }
   ]
}

Isso responde com um status indicando que o trabalho foi cancelado.