Salvar Definição

Este método permite a inserção de um arquivo com um lote (batch) de registros para serem consultados na fila de processamento da Plataforma de Dados.

Funcionamento

Esse método recebe como entrada os parâmetros necessários 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 assim por diante. Esses elementos (descritos em mais detalhes na secção abaixo) são utilizados para inserir o job na fila de processamento e, posteriormente, para a execução das consultas.

O arquivo de entrada, que contém os registros à serem processados, deve ser disponibilizado em formato TXT (texto), com um registro por linha. Se o registro tiver mais de uma coluna, as colunas devem ser separadas por um delimitador. Para arquivos sendo trocados via HTTP ou HTTPS, o arquivo de entrada deve estar disponível através de um link público, que permita o download do arquivo pelo processo de execução, do contrário a execução em batch irá falhar.

Para arquivos disponibilizados através de Buckets S3, as credenciais de acesso fornecidas na chamada da API devem ter permissão para pegar e colocar objetos no bucket e identificar a região do bucket. Ou seja, para esse acesso, precisamos de permissão para os métodos: GetBucketLocation, GetObject e PutObject.

É possível se utilizar de todos os mecanismos de consulta presentes na API convencional da Plataforma de Dados, seja para consulta de pessoas, empresas ou validações, combinados com os elementos dos arquivos de entrada através da definição de um template de consulta. Isso inclui a execução de consultas através de chaves alternativas, o envio de datas de referência para a execução de back tests e muito mais.

Além dos mecanismos disponíveis na API, o processamento em Batch possui também o suporte a retentativa de consultas. O objetivo desse mecanismo é apoiar processamentos de arquivos muito grandes ou que dependem de fontes de informação instáveis, possibilitando que consultas com erro sejam reexecutadas sem a necessidade de uma submissão do arquivo de entrada, simplificando o trabalho dos clientes. É importante lembrar que você nunca é cobrado por consultas com erro, então a retentativa não implica em custos adicionais para os clientes. As consultas são retentadas em duas situações:

• Houve alguma falha de conexão ou de timeout de resposta na chamada da API de consultas; ou;
• Todos os datasets consultados retornaram um código de erro menor ou igual à -1200 (ver a tabela de códigos de erro para detalhes).

Os parâmetros opcionais utilizados para a retentativa de consultas estão descritos na tabela abaixo.

O arquivo de saída é disponibilizado através de um link na área de transferência de arquivos da BigData Corp, que fica no endereço https://files.bigdatacorp.com.br/go, e estão disponíveis para download por até 30 dias após a execução do job. Alternativamente, se for utilizado o método de troca de arquivos via Buckets S3, o arquivo de saída é depositado no repositório definido pelo cliente na entrada.

ATENÇÃO: Após a chamada à esse método, o arquivo será validado e carregado para processamento, mas o processo de consulta só terá início quando for chamado o método StartJobExecution, descrito abaixo.

Parâmetros de Entrada

A tabela a seguir descreve os parâmetros de entrada deste método, indicando se são obrigatórios ou não, e os valores possíveis para os campos com valores pré-definidos.

Formatação das URLs dos arquivos de entrada e saída do processo

A sintaxe abaixo se aplica aos campos InputFileURL e OutputFileUrl, e é utilizada para especificar qual será o mecanismo de transferência dos arquivos, além dos parâmetros necessários para que a transferência seja realizada com sucesso. Listamos abaixo os mecanismos de transferência suportados, e a sintaxe para cada um dos mesmos:

• Transferência via HTTP ou HTTPS: Nesse tipo de transferência, o arquivo de entrada será baixado a partir do link disponibilizado, e o arquivo de saída será gerado em uma área de transferência da BigDataCorp para download pelo cliente. O exemplo a seguir ilustra como preencher os parâmetros necessários:

  {
    "InputFileUrl": "web{https://www.example.com/mysamplefile.txt}",
    "InputKeysHeader" : "Documento",
    "APIName": "people",
    "Datasets": "basic_data",
    "QueryTemplate": "doc{{0}}"
  }
  

• Transferência via S3 (serviço de armazenamento de dados da AWS): Nesse tipo de transferência, o cliente pode especificar um endereço de retorno independente do endereço de entrada. Caso o parâmetro de URL do arquivo de saída não seja preenchido, o arquivo de resultados será colocado no mesmo bucket do arquivo de entrada. O exemplo a seguir ilustra como preencher os parâmetros necessários:

  {
    "InputFileUrl": "file{s3://aws_access_key:aws_secret_key@bucket_name}, remotefilepath{path_to_file_in_s3}",
    "OutputFileUrl": "file{s3://aws_access_key:aws_secret_key@bucket_name}, remotefilepath{path_for_file_to_be_saved_at}",
    "InputKeysHeader" : "Documento",
    "InputFileDelimiter": "	",
    "InputFileHasHeader": false,
    "OutputFileDelimiter": "	",
    "APIName": "people",
    "Datasets": "basic_data",
    "QueryTemplate": "doc{{0}}"
  }
  

• Transferência via FTP: Nesse modelo de transferência, o endereço de entrada e saída podem ser completamente diferentes. Os parâmetros entre parênteses "()" são opcionais, e, se não forem preenchidos, assumirã valores default. O exemplo a seguir ilustra como preencher os parâmetros necessários:

  {
    "InputFileUrl": "file{ftp://user(:password)@dns(:port)}, remotefilepath{path_to_file_in_ftp}",
    "OutputFileUrl": "file{ftp://user(:password)@dns(:port)}, remotefilepath{path_for_file_to_be_saved_at}",
    "InputKeysHeader" : "Documento",
    "InputFileDelimiter": "	",
    "InputFileHasHeader": false,
    "OutputFileDelimiter": "	",
    "APIName": "people",
    "Datasets": "basic_data",
    "QueryTemplate": "doc{{0}}"
  }
  

• Transferência via SFTP: Nesse modelo de transferência, o endereço de entrada e saída podem ser completamente diferentes. Os parâmetros entre parênteses "()" são opcionais, e, se não forem preenchidos, assumirã valores default. O exemplo a seguir ilustra como preencher os parâmetros necessários:

  {
    "InputFileUrl": "file{sftp://user(:password)@dns(:port)}, remotefilepath{path_to_file_in_sftp}",
    "OutputFileUrl": "file{sftp://user(:password)@dns(:port)}, remotefilepath{path_for_file_to_be_saved_at}",
    "InputKeysHeader" : "Documento",
    "InputFileDelimiter": "	",
    "InputFileHasHeader": false,
    "OutputFileDelimiter": "	",
    "APIName": "people",
    "Datasets": "basic_data",
    "QueryTemplate": "doc{{0}}"
  }
  

IMPORTANTE! Os campos de InputFileUrl e OutputFileUrl são independentes. Pode ser especificado um arquivo de entrada presente no S3 e um arquivo de saída postado em uma pasta de SFTP, ou qualquer outra combinação dos mecanismos listados acima.

Uma senha será adicionada a um arquivo de retorno dependendo do tipo de ambiente de destino. Para ambientes internos, como S3, FTP ou SFTP, onde o arquivo é armazenado dentro do ambiente corporativo, não é adicionada uma senha ao arquivo. No entanto, para ambientes externos, acessíveis publicamente via URL, uma senha gerada automaticamente é sempre incluída para garantir a segurança do arquivo.

Se preferível, é possível especificar a senha a ser adicionada a um arquivo por meio do campo 'OutputFilePassword' ao fazer uma requisição, permitindo assim que arquivos enviados para ambientes externos podem ter uma senha definida manualmente. Vale ressaltar que, caso o campo 'OutputFilePassword' seja incluído na requisição, mas esteja vazio, preenchido apenas com espaços ou nulo, a senha atribuída ao arquivo será gerada automaticamente.

Em todos os casos onde uma senha é aplicada ao arquivo, ela será enviado por e-mail ao endereço cadastrado do usuário e aos e-mails listados no campo CopyEmails, também presente no reques atual.

Retorno

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, que pode ser utilizado para recuperar outras informações sobre o mesmo ou para cancelar sua execução (veja os outros métodos da API de Processamento em Lote).

A tabela a seguir descreve os campos do objeto de retorno desse método.

Códigos de Status

A tabela a seguir descreve os possíveis códigos e mensagens de retorno.

Exemplos

Exemplo de requisição para rodar a consulta do dataset de Dados Básicos de Pessoas para um arquivo de entrada com uma única coluna com os CPFs:

{
  "InputFileUrl": "web{https://www.example.com/mysamplefile.txt}",
  "InputKeysHeader" : "Documento",
  "InputFileDelimiter": "	",
  "InputFileHasHeader": false,
  "OutputFileDelimiter": "	",
  "APIName": "people",
  "Datasets": "basic_data",
  "QueryTemplate": "doc{{0}}"
}

Exemplo de requisição para consultar no modelo de backtest os dados básicos e e-mails de empresas para um arquivo de entrada com três colunas delimitadas por TAB: um id externo, o documento, e uma data de referência:

{
  "InputFileUrl": "web{https://www.example.com/mysamplefile.txt}",
  "InputFileDelimiter": "\t"
  "InputKeysHeader" : "Id_Externo\tDocumento\tData_Referencia",
  "InputFileDelimiter": "	",
  "InputFileHasHeader": false,
  "OutputFileDelimiter": "	",
  "APIName": "companies",
  "Datasets": "basic_data,emails",
  "QueryTemplate": "external_id{{0}},doc{{1}},referencedate{{2}}"
}

Exemplo de requisição para consultar, usando chaves alternativas, os datasets de dados básicos e telefones de pessoas, para um arquivo de entrada com duas colunas de entrada - nome e data de nascimento (no formato dia/mês/ano) - delimitadas por ponto-e-vírgula (";"):

{
  "InputFileUrl": "web{https://www.example.com/mysamplefile.txt}",
  "InputFileDelimiter": ";"
  "InputKeysHeader" : "Nome\tData_Nascimento",
  "InputFileDelimiter": "	",
  "InputFileHasHeader": false,
  "OutputFileDelimiter": "	",
  "APIName": "people",
  "Datasets": "basic_data,phones",
  "QueryTemplate": "name{{0}},birthdate{{1}},dateformat{dd/MM/yyyy}"
}

Exemplo de requisição para consultar o dataset on-demand de status na Receita Federal de CNPJs e retornar os resultados no formato JSON, para um arquivo com uma única coluna de entrada com os documentos, copiando um e-mail qualquer sobre o status de execução:

{
  "InputFileUrl": "web{https://www.example.com/mysamplefile.txt}",
  "OutputFileFormat": "json",
  "InputFileDelimiter": "	",
  "InputFileHasHeader": false,
  "OutputFileDelimiter": "	",
  "APIName": "companies",
  "Datasets": "ondemand_rf_status",
  "QueryTemplate": "doc{{0}}"
  "CopyEmails": ["[email protected]"],
}

Exemplo de requisição para rodar a consulta do dataset de Dados Básicos de Pessoas para um arquivo de entrada disponibilizado em um bucket do S3:

{
  "InputFileUrl": "file{s3://Sample_Access_Key:Sample_Secret_Key@Sample_Bucket}, remotefilepath{Sample_Folder/mysamplefile.txt}",
  "InputKeysHeader" : "Documento",
  "InputFileDelimiter": "	",
  "InputFileHasHeader": false,
  "OutputFileDelimiter": "	",
  "APIName": "people",
  "Datasets": "basic_data",
  "QueryTemplate": "doc{{0}}"
}

Exemplo de requisição para consultar uma view pré-definida no processo de Batch, ao invés de datasets, para um arquivo com uma única coluna de entrada com os documentos:

{
   "InputFileUrl": "file{s3://Sample_Access_Key:Sample_Secret_Key@Sample_Bucket}, remotefilepath{Sample_Folder/mysamplefile.txt}",
  "InputKeysHeader" : "Documento",
  "InputFileDelimiter": "	",
  "InputFileHasHeader": false,
  "OutputFileDelimiter": "	",
  "APIName": "people",
  "View": "minha_view_predefinida",
  "QueryTemplate": "doc{{0}}"
}

Exemplo de requisição com configuração de 2 retentativas para cada consulta realizada, com 30 segundos de espera entre cada consulta, para um arquivo com uma única coluna de entrada com os documentos:

{
  "InputFileUrl": "file{s3://Sample_Access_Key:Sample_Secret_Key@Sample_Bucket}, remotefilepath{Sample_Folder/mysamplefile.txt}",
  "InputKeysHeader" : "Documento",
  "InputFileDelimiter": "	",
  "InputFileHasHeader": false,
  "OutputFileDelimiter": "	",
  "APIName": "people",
  "Datasets": "basic_data",
  "QueryTemplate": "doc{{0}}",
  "MaxQueryRetries": 2,
  "QueryRetryBackoff": 30
}

BODY raw

{
  "InputFileUrl": "[URL do seu arquivo de entrada]",
  "InputFileDelimiter": "\t",
  "InputFileHasHeader": false,
  "OutputFileFormat": "txt",
  "OutputFileDelimiter": "\t",
  "OutputRemoveEmptyColumns": false,
  "InputKeysHeader" : "Documento",
  "InputFileSampleRate": -1,
  "CopyEmails": ["[email protected]","[email protected]"],
  "APIName": "companies",
  "Datasets": "basic_data,addresses_extended,phones_extended,emails_extended,activity_indicators,relationships,related_people_phones,related_people_emails",
  "QueryTemplate": "doc{{0}}"
}