Histórico da Página
| Índice |
|---|
01. VISÃO GERAL
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.
02. AUTENTICAÇÃO
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.
03. PAGINAÇÃO
A Plataforma Carol disponibiliza a opção do page size / offset.
...
| Bloco de código |
|---|
- 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>' |
04. FILTROS
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.
...
| Bloco de código |
|---|
- 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>' |
05. NAMED QUERIES PARA CONSULTA
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.
05.1. Consulta de Usuários
| Bloco de código |
|---|
- 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>' |
| Bloco de código |
|---|
- {
"count": 5,
"totalHits": 11,
"took": 12,
"hits": [
{
"mdmGoldenFieldAndValues": {
"mdmshouldsendwelcomeemail": true,
"mdmphonenumber": "1232321",
//....
}
},
{
"mdmGoldenFieldAndValues": {
// ...
}
},
],
"aggs": {}
} |
05.2. Consulta de Marcações
| Bloco de código |
|---|
- 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>' |
| Bloco de código |
|---|
Response similar a da consulta de usuários |
05.3. Consulta de Funcionários
| Bloco de código |
|---|
- 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>' |
| Bloco de código |
|---|
Response similar a da consulta de usuários |
05.4. Consulta de Dispositivo
| Bloco de código |
|---|
- 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>' |
| Bloco de código |
|---|
Response similar a da consulta de usuários |
05.5. Consulta de Filtros
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.
...
| Bloco de código |
|---|
- 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" }' |
06. EXEMPLO DE USO PARA CONSULTA DE MARCAÇÕES DE PONTO:
Segue abaixo um exemplo prático de como testar e usar uma NAMED QUERY, além de dicas de uso.
06.1. Consultando e testando a NAMED QUERY que pretende usar:
1- Faça Login no seu Ambiente ({organização}.carol.ai/{ambiente});
...
3- No menu lateral esquerdo, também selecione a opção RT;
4- Digite o nome da NamedQuery NamedQuery que pretende utilizar;
5- De duplo clique sobre o nome e ela será aberta para consulta na tela direita;
6, 7 e 8- No caso desta NamedQuery NamedQuery (clockinrecordsListByPeriod), ela permite realizar filtros no Data Model CLOCK IN RECORDS usando os campos de código do dispositivo, período de data da marcação de ponto e a partir de qual número NSR;
9- Você pode testar a NamedQuery NamedQuery pressionando o botão RUN.
1- Preencha os filtros desejados e execute a consulta.
...
Assim pode consultar/exportar os dados retornados da consulta:
06.2. Exemplo da montagem de uma requisição:
- Só passando a NamedQuery, sem usar filtros
...
| Bloco de código | ||||
|---|---|---|---|---|
| ||||
{
"count": 6,
"totalHits": 6,
"took": 9,
"hits": [
{
"mdmGoldenFieldAndValues": {
"eventdatestr": "2024-08-14T17:40:00.000-03:00",
"mdmeventdate": "2024-08-14T20:40:00.000Z"
}
},
{
"mdmGoldenFieldAndValues": {
"eventdatestr": "2024-08-14T17:42:00.000-03:00",
"mdmeventdate": "2024-08-14T20:42:00.000Z"
}
},
{
"mdmGoldenFieldAndValues": {
"eventdatestr": "2024-08-21T08:49:00.000-03:00",
"mdmeventdate": "2024-08-21T11:49:00.000Z"
}
},
{
"mdmGoldenFieldAndValues": {
"eventdatestr": "2024-08-21T08:55:00.000-03:00",
"mdmeventdate": "2024-08-21T11:55:00.000Z"
}
},
{
"mdmGoldenFieldAndValues": {
"eventdatestr": "2024-08-21T08:57:00.000-03:00",
"mdmeventdate": "2024-08-21T11:57:00.000Z"
}
},
{
"mdmGoldenFieldAndValues": {
"eventdatestr": "2024-08-21T12:15:00.000-03:00",
"mdmeventdate": "2024-08-21T15:15:00.000Z"
}
}
],
"aggs": {}
} |
06.3. Para mais informações
- Acesse as documentações técnicas já mencionadas acima:
- Autenticação: aqui.
- Consumindo Dados TOTVS Carol: aqui.
- docs.carol.ai
- Consulte o Swagger dentro do seu ambiente:
...
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas