A API de Processamento em Lote foi desenvolvida para atender à necessidades de realizar consultas em grande escala de forma simplificada e eficiente. Ela permite a execução de consultas em massa para um conjunto de registros, como no caso de enriquecimento de dados ou validação de listas. Através do envio de um arquivo de entrada com os registros, a API processa as consultas de forma paralelizada, otimizando o tempo de resposta e oferecendo uma solução ágil para o processamento em lote.
Sobre o Serviço
A maior parte das requisições realizadas contra a Plataforma de Dados seguem o modelo de API tradicional, uma requisição sendo realizada de cada vez. Em algumas situações, no entanto, é necessário um mecanismo que permita realizar a mesma consulta, de forma simplificada, para uma quantidade grande de registros. Pode ser o enriquecimento de uma base de dados que você já possui, a validação de uma lista de e-mails, ou ou qualquer outra situação que demande um processamento em lote.
Para atender à essas situações, desenvolvemos a API de Processamento em Lote. Ela permite a execução de consultas para registros contidos em um arquivo de entrada submetido pelo cliente, executando as consultas para os diferentes registros de forma paralelizada para minimizar o tempo de resposta.
Nessa API, ao invés de fazer a chamada e ficar aguardando um retorno, o cliente submete um lote (batch) de registros, com algumas configurações, e é avisado posteriormente quando o processamento deste lote for finalizado. Além da submissão de um lote para execução, é possível também se pausar ou cancelar uma execução, ou mesmo reexecutar um lote processado anteriormente.
Iniciando o processamento em lote
Para trazer maior versatilidade aos clientes, existem formas distintas de se utilizar a API de Processamento em Lote, cada uma visa atender a diferentes fluxos de processos. No entanto, todas elas partem da mesma etapa: a definição dos datasets e parâmetros a serem processados.
Nesse método é necessário enviar as configurações iniciais para a consulta de um lote de registros: o arquivo com os registros que devem ser processados, a API que deve ser consultada, o formato do arquivo de saída e algumas informações de metadados do arquivo de entrada, como indicado pelo exemplo abaixo:
POST: https://plataforma.bigdatacorp.com.br/lote/salvarDefinicao
{
"InputFileUrl": "web{https://www.example.com/mysamplefile.txt}",
"InputKeysHeader" : "Documento",
"APIName": "people",
"Datasets": "basic_data",
"QueryTemplate": "doc{{0}}"
}
A partir dessas informações, conseguimos identificar que é necessário consultar os Dados Básicos na API de Pessoas, usando a primeira coluna que é chamada de "Documento". Como resultado, o método retorna um código e mensagem de erro, caso algum problema tenha ocorrido. Do contrário, é retornado o identificador único do job(JobId), que pode ser utilizado para recuperar outras informações sobre o mesmo ou cancelar sua execução (veja os outros métodos da API de Processamento em Lote).
Após a definição das configurações necessárias para o job, os documentos são preparados internamente para a consulta. Quando esse processo é concluído, o status do job é alterado para loaded, e o cliente é notificado por e-mail de que a carga dos registros para processamento foi finalizada.
Atenção
Esse passo não é necessário, caso você já tenha definido o parâmetro
AutomaticallyStartQueryingcomotrueem Salvar Definição.
A partir desse momento, o job está pronto para iniciar as consultas. Para dar continuidade, o cliente deve fornecer o JobId correspondente a esse processamento, conforme descrito abaixo:
POST: https://plataforma.bigdatacorp.com.br/lote/iniciarExecucao
{
"JobId": "[IDENTIFICADOR ÚNICO DO JOB]"
}
Endpoints da API
A seguir serão descritos as funcionalidades disponíveis para uso na API de Processamento em Lote. Para obter mais detalhes sobre cada uma, acesse suas respectivas páginas de documentação.
Este método permite ao usuário recuperar a lista de processamentos em batch solicitados pelo mesmo, com dados detalhados sobre cada um dos processos.
Este método permite ao usuário recuperar informações detalhadas sobre o progresso de execução de qualquer job que tenha sido submetido para execução. A partir do identificador do job (JobId) que deseja consultar.
Esse método permite ao usuário suspender a execução de um job que está sendo processado, a partir do identificador do job (JobId) do mesmo.
Este método permite ao usuário retomar a execução de um job que foi suspendido, a partir do identificador do job (JobId) do mesmo.
Esse método permite ao usuário cancelar a execução de um job que está sendo processado, a partir do identificador do job (JobId) do mesmo.
Este método permite ao usuário reexecutar todas as etapas de um job, a partir do identificador do job (JobId) do mesmo.
Atenção
Todos os resultados obtidos até então serão perdidos e todas as consultas serão reexecutadas, e sendo cobradas novamente.
Cobrança
O valor de cada consulta no dataset possui o mesmo custo de uma requisição padrão. As informações sobre precificação de datasets podem ser encontradas na página de Tabela de Preços Resumida.
O valor final de um processamento é multiplicado pelo número de registros que foram consultados.
Fluxograma da API de Processamento em Lote
A seguir, explicamos cada etapa do fluxo:
🧾 1. Salvar Definição
O primeiro passo do processo é o envio da definição do job, que configura como o lote de dados será processado.
Resultado esperado: retorno de um JobId (identificador único do job), que será usado nas próximas etapas.
Status inicial: pending
🔄 2. Carregamento dos Registros
Após salvar a definição, o sistema carrega o arquivo com os registros para preparar as consultas.
Status alterado para: loading
Ao final do carregamento:
Status: loaded
O sistema notifica o usuário por e-mail.
A partir deste ponto, o job está pronto para iniciar as consultas caso o parâmetro AutomaticallyStartQuerying não tenha sido definido como true.
▶️ 3. Iniciar Execução
Se o job estiver em estado loaded, o usuário deve iniciar a execução manualmente (caso não tenha sido automático)
Status alterado para: querying
⏸️ 4. Controle da Execução (opcional)
Durante a execução, o usuário pode controlar o andamento do job:
Pausar execução: Status vai para paused
Resumir execução: Retoma para querying
Cancelar execução: Finaliza o job com status cancelled
Reiniciar execução: Recomeça desde o início com base na definição original
📥 5. Finalização das Consultas
Depois que todas as consultas forem executadas:
Status: queried
Em seguida, o sistema inicia o processo de parseamento dos dados.
📦 6. Geração do Arquivo de Saída
O sistema transforma os dados obtidos em um arquivo de saída no formato especificado.
Status: parsing
✅ 7. Conclusão
Quando o parseamento é finalizado e o arquivo de resultado é gerado e enviado:
Status final: done
Resumo dos Status
| Status | Descrição |
|---|---|
| pending | Job salvo, aguardando processamento |
| loading | Arquivo sendo carregado |
| loaded | Pronto para iniciar consultas |
| querying | Consultas em andamento |
| paused | Execução pausada |
| queried | Consultas finalizadas |
| parsing | Resultados sendo processados |
| done | Job concluído com sucesso |
| cancelled | Job cancelado pelo usuário |
