A consulta à API de Eventos permite a qualquer usuário recuperar um registro de log e auditoria de uma consulta realizada no passado, seja através do identificador da consulta ou através dos parâmetros utilizados na entrada da consulta. Todas as consultas realizadas na Plataforma de Dados, em qualquer uma de suas APIs, geram um registro de log e auditoria com uma série de informações relevantes para análise posterior, como o tempo de execução da consulta, o IP da máquina que realizou a chamada, e o próprio resultado entregue para o cliente após a sua execução.
Todos os registros de consulta são armazenados por tempo indefinido, e estão disponíveis para acesso a qualquer momento.
Funcionamento
A forma mais simples de se consultar a API de Eventos é informando o ID de Consulta (QueryId) da requisição que se deseja recuperar. Recomendamos fortemente que todos os QueryIds sejam sempre armazenados pelos clientes, porque esse é o elemento mais forte que amarra as consultas realizadas com os registros de log e auditoria. No entanto, caso o cliente não tenha certeza sobre o QueryId, ou queira recuperar todas as consultas realizadas com um conjunto específico de parâmetros, a API permite também a utilização de outros parâmetros de busca, listados a seguir:
q: Esse parâmetro especifica os parâmetros de entrada utilizados em uma consulta, e permite recuperar, por exemplo, todas as consultas feitas em um CPF específico;
Tags: Este parâmetro especifica as tags personalizadas usadas em requisições para categorizar as consultas, permitindo recuperar todas as consultas associadas a uma tag específica;
QueryDate: Esse parâmetro permite ao usuário filtrar por data as consultas retornadas quando está pesquisando usando o parâmetro q, descrito acima. Pode ser usado também em conjunto com o QueryId para acelerar as consultas. No caso de ser utilizado junto com o QueryId, não precisa ser necessariamente a data exata em que a consulta foi realizada, pode ser uma aproximação;
DateFormat: Esse parâmetro só deve ser enviado em conjunto com o QueryDate, e define o formato em que a data foi informada;
PageSize: Esse parâmetro só deve ser enviado em conjunto com o q, e define o tamanho da "página" de resultados que serão entregues, ou seja, a quantidade de registros de log que serão retornados em uma primeira chamada. Caso não seja informado, serão retornados os primeiros 50 resultados;
Cursor: Esse parâmetro é utilizado para realizar a paginação de resultados por um conjunto de retornos obtidos a partir de uma consulta com o parâmetro q, e só deve ser utilizado após uma chamada inicial. Deve sempre receber um valor de Cursor que tenha sido retornado por uma chamada anterior;
Obrigatóriamente deve ser informado o parâmetro QueryId, Tags ou q. Todos os outros parâmetros são opcionais.
Exemplos
Como recuperar o resultado de uma consulta específica:
{
"QueryId": "[seu query id]"
}
Como recuperar o resultado de uma consulta específica mais rápido, com uma data de referência:
{
"QueryId": "[seu query id]",
"QueryDate": "2019-07-25",
"DateFormat": "yyyy-MM-dd"
}
Como recuperar todas as consultas que utilizam tags específicas:
{
"Tags": {
"Key1": "Value1",
"Key2": "Value2"
}
}
Como recuperar todas as consultas realizadas contra um CPF específico, de 10 em 10:
{
"q": "doc{xxxxxxxxxxx}",
"PageSize": 10
}
Como fazer a paginação por resultados:
{
"q": "doc{xxxxxxxxxxx}",
"PageSize": 10,
"Cursor": "[valor de cursor retornado pela chamada anterior]"
}
Nota: Por padrão, um usuário tem acesso à todos os registros de eventos associados com a empresa a qual ele pertence.