Este documento tem objetivo apresentar como é possível obter dados de usuários, marcações, funcionários e dispositivos do Clock in utilizando Named Queries.
A Plataforma Carol disponibiliza duas formas de autenticação para uso de rotas privadas para Named Queries: OAuth2 e API Key. Mais detalhes acesse aqui.
A Plataforma Carol disponibiliza a opção do page size / offset.
Para obter os 5 primeiros registros da primeira pagina utilizando o offset=0
e pageSize=5
.
- curl -X POST 'https://api.carol.ai/api/v3/queries/named/<NOME_DA_NAMED_QUERY> ?offset=0 &pageSize=5' -H 'X-Auth-Key: <KEY>' -H 'X-Auth-ConnectorId: <CON_ID>'
Para obter os 5 registros da segunda página, utilizando o offset=5 e pageSize=5.
- curl -X POST 'https://api.carol.ai/api/v3/queries/named/<NOME_DA_NAMED_QUERY> ?offset=5 &pageSize=5' -H 'X-Auth-Key: <KEY>' -H 'X-Auth-ConnectorId: <CON_ID>'
Caso houvessem mais registros, seria possível utilizar o offset=10
e pageSize=5
.
Também é possível retornar todos os dados em uma única request. Isto não é recomendado pois a resposta pode ser lenta e podem haver limitação de quantidade de registros. Para tanto basta remover o campo offset
e setar o campo pageSize=-1
.
- curl -X POST 'https://api.carol.ai/api/v3/queries/named/<NOME_DA_NAMED_QUERY> ?pageSize=-1' -H 'X-Auth-Key: <KEY>' -H 'X-Auth-ConnectorId: <CON_ID>'
Por padrão, Named Queries retornam todos os dados dos Data Models (local onde os dados estão), mas é possível utilizar filtros para obter apenas os dados necessários. No caso abaixo os campos mdmpersonid e mdmname foram utilizados como filtro. Sempre lembrando que os campos do Data Model sempre estão dentro do objeto mdmGoldenFieldAndValues. A Plataforma Carol retorna outros campos que fazem parte da estrutura interna dela mas que não parecem fazer sentido para este caso.
- curl -X POST 'https://api.carol.ai/api/v3/queries/named/<NOME_DA_NAMED_QUERY> ?offset=0 &pageSize=5 &fields=mdmGoldenFieldAndValues.mdmpersonid,mdmGoldenFieldAndValues.mdmname' -H 'X-Auth-Key: <KEY>' -H 'X-Auth-ConnectorId: <CON_ID>'
Para obter a lista completa de Named Queries disponíveis no ambiente, basta entrar em Explore e depois em Named Queries. A lista será apresentada. Nesta área é possível editar, excluir e incluir novas Named Queries. Sempre lembrando que elas vão retornar os registros dos Data Models. Para saber mais sobre Named Queries acesse aqui.
- curl -X POST 'https://api.carol.ai/api/v3/queries/named/userList ?offset=0 &pageSize=5 &fields=mdmGoldenFieldAndValues' -H 'X-Auth-Key: <KEY>' -H 'X-Auth-ConnectorId: <CON_ID>'
- { "count": 5, "totalHits": 11, "took": 12, "hits": [ { "mdmGoldenFieldAndValues": { "mdmshouldsendwelcomeemail": true, "mdmphonenumber": "1232321", //.... } }, { "mdmGoldenFieldAndValues": { // ... } }, ], "aggs": {} }
- curl -X POST 'https://api.carol.ai/api/v3/queries/named/clockinrecordsListByPeriod ?offset=0 &pageSize=5 &fields=mdmGoldenFieldAndValues' -H 'X-Auth-Key: <KEY>' -H 'X-Auth-ConnectorId: <CON_ID>'
Response similar a da consulta de usuários
- curl -X POST 'https://api.carol.ai/api/v3/queries/named/employeeList ?offset=0 &pageSize=5 &fields=mdmGoldenFieldAndValues' -H 'X-Auth-Key: <KEY>' -H 'X-Auth-ConnectorId: <CON_ID>'
Response similar a da consulta de usuários
- curl -X POST 'https://api.carol.ai/api/v3/queries/named/deviceList ?offset=0 &pageSize=5 &fields=mdmGoldenFieldAndValues' -H 'X-Auth-Key: <KEY>' -H 'X-Auth-ConnectorId: <CON_ID>'
Response similar a da consulta de usuários
Para verificar quais são os filtros das Named Queries, basta entrar na área citada anteriormente e executar uma Named Query para testes. Ao executar, a Carol apresentará quais são os filtros. Também é possível adicionar novos filtros. Segue abaixo exemplo de como enviar valores para os filtros via requisições HTTP POST.
- curl -X POST 'https://api.carol.ai/api/v3/queries/named/<NOME_DA_NAMED_QUERY> ?offset=0 &pageSize=5 &fields=mdmGoldenFieldAndValues' -H 'X-Auth-Key: <KEY>' -H 'X-Auth-ConnectorId: <CON_ID>' -d '{ "key1": "value1", "key2": "value2" }'