A Carol possui autenticação OAuth, podendo ser explorado a autenticação API Key (também conhecido como API Token ou Connector Token).
Índice | ||||
---|---|---|---|---|
|
Abaixo um fluxo demonstrando o processo de envio de dados para a Carol:
...
Esses serviços permitem efetuar a definição da estrutura de dados (schema), efetuar o envio de dados pelo processo SYNC e processo ASYNC bem como eliminação de dados na Carol.
Todos os dados enviados para a Carol devem possuir um schema, que é basicamente a definição da estrutura que será armazenado na Carol. O conceito do schema segue o mesmo principio do schema de tabelas em banco de dados relacional.
...
A plataforma Carol dispoem os serviços necessários para criar, atualizar e apagar o schema de tabelas, conforme a seguir:
Além dos endpoints descritos acima, as operações de manutenção de uma staging table e eliminação (drop) de uma staging table estão disponíveis através da UI da Carol. Quando acessado um conector na Carol (menu lateral esquerdo) podemos acessar as staging tables pertencentes ao conector.
...
Ao término dos ajustes, o botão "Save Changes" irá atualizar o schema da staging table, da mesma forma que o serviço PUT acima descrito.
A staging table possui o objetivo de armazenar dados (registros/documentos) na sua estrutura. O serviço abaixo é o responsável por receber um conjunto de dados (array de documentos JSON). Conforme definido no capítulo anterior, o atributo Identifier irá determinar se os registros serão adicionados na Carol ou se eles irão atualizar dados já existentes.
...
O serviço acima descrito permite o envio de dados seguinte a RFC1952 que permite o envio de dados compactados. Altamente recomendado que os dados sejam enviados desta forma, reduzindo assim o tempo de latência na requisição.
Informações | ||
---|---|---|
| ||
A request de envio de dados permite a utilização do nome do conector no parâmetro "connectorId" tornando o aplicativo mais simples e menos dependente ao ambiente do cliente. O nome do conector pode ser obtido na tela de "Connectors" na Carol. O nome da tabela deve possuir caracteres e número, sendo obrigatório iniciar com um caracter. Caracteres especiais não são permitidos. O "body" deve ser um array de objetos Json seguindo o "schema" definido para a "staging table" no passo anterior. |
Uma vez que o dado foi inserido através deste serviço, ele poderá ser visualizado na UI da Carol. As staging tables possuem um percentual para visualização dos dados de amostragem (sample data) - por isso espera-se que nem todos os dados sejam visualizados pela UI.
...
O próximo capítulo irá descrever o mesmo serviço, porém, síncrono, que irá retornar 200 quando os dados estão na staging table ou caso estejam disponíveis como golden record.
Este serviço possui o mesmo objetivo que o serviço detalhado no capítulo anterior, porém, irá retornar o código 200 na requisição http quando os dados estiverem disponíveis na Carol. Os dados estarem disponíveis signfiica estarem na staging table (caso a staging table não esteja mapeada) ou estarem disponíveis como Golden Record caso a staging table tenha um mapeamento para um Data Model.
...
Este serviço possui os mesmos recursos do serviço assíncrono.
Este serviço possui o objetivo de eliminar dados na Carol, através dos valores dos atributos definidos como Identifier para a staging table.
...
Os parâmetros são os aseguir:
Parâmetro | Descrição |
---|---|
table | O nome da staging table que está sendo eliminado os registros. |
connectorId | O código do conector que a staging table acima pertence. |
propagateCleanup | Parâmetro que indica se a eliminação dos registros devem ser propagados para o Golden Record e registros rejeitados, desta forma eliminando completamente este registro da Carol. |
body | Json com a lista de IDs que deverão ser eliminados. Um exemplo deste parâmetro é: [{"emitente":{"cod-emitente":"33"}}, {"emitente":{"cod-emitente":"44"}}] |
Desta forma que processos externos podem efetuar a eliminação de registros na Carol.
A Carol permite o envio de informações relacionados à integração de dados de cada conector. Os dados a serem enviados é de responsabilidade do conector, e estes dados são visualizados na Carol, dentro do conector através da opção "Show Connector Details":
Quando o conector fica sem enviar dados por mais do que 24 horas um alerta é exibido, conforme abaixo:
O envio do heart-beat ocorre através da request abaixo:
Bloco de código | ||||
---|---|---|---|---|
| ||||
curl -X PUT "https://clockin.carol.ai/api/v1/heartbeats/90d7bcd37c424d85a733a42117528792" -H "accept: application/json" -H "Authorization: 29dfe258523c416c96e7b1b2ff1a8dfc" -H "content-type: application/json" -d "{ \"mdmConnectorId\": \"90d7bcd37c424d85a733a42117528792\", \"mdmCreatedUser\": \"[email protected]\", \"mdmEntityType\": \"mdmHeartbeat\", \"mdmHeartbeatData\": { \"databases\": [ { \"database\": \"Microsoft SQL Server\", \"fullVersion\": \"13.00.1601\", \"id\": \"d2844ee37088c437109a55c40f36d745abad48d2\", \"version\": \"13.0\" }, { \"database\": \"Directory\", \"id\": \"defb02fc824ea527814cbd2d78f04bfde99a180d\" } ], \"encoding\": \"UTF-8\", \"freeSpace\": \"126397394944\", \"hostAddress\": \"10.172.158.209\", \"javaVersion\": \"11.0.5\", \"javaVmName\": \"OpenJDK 64-Bit Server VM\", \"lastConnectionTimestamp\": { \"d2844ee37088c437109a55c40f36d745abad48d2\": \"2019-11-28T13:31:55Z\", \"defb02fc824ea527814cbd2d78f04bfde99a180d\": \"1970-01-01T00:00:00Z\" }, \"now\": \"2019-11-28T14:01:55Z\", \"osArch\": \"amd64\", \"osName\": \"Windows 10\", \"osVersion\": \"10.0\", \"recordCountLast24Hours\": \"0\", \"recordCountLastHour\": \"0\", \"startTime\": \"2019-11-14T18:56:58Z\", \"tenant\": \"clockin\", \"timezone\": \"GMT-03:00\", \"user\": \"robson.poffototvs.com\", \"version\": \"2.30.5\" }, \"mdmHeartbeatInterval\": 0, \"mdmId\": \"13b7fdffa90340fc92b418a0f4944db2\", \"mdmLastHeartbeatTime\": \"2020-06-21T20:47:49.899Z\", \"mdmLastUpdated\": \"2020-06-21T20:47:49.904Z\", \"mdmTenantId\": \"4c2c9090e7c611e893bf0e900682978b\", \"mdmUpdatedUser\": \"[email protected]\"}" |
Parâmetros importantes
Informações | ||
---|---|---|
| ||
O heart-beat permite o envio de mais dados além do descrito acima. A lista é flexível e qualquer chave/valor pode ser enviado/recebido pela Carol. |
A request abaixo permite obter o último heart-beat enviado para a Carol:
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
curl 'https://api.carol.ai/api/v1/heartbeats/90d7bcd37c424d85a733a42117528792' -H 'authority: api.carol.ai' -H 'accept: application/json' -H 'authorization: 29dfe258523c416c96e7b1b2ff1a8dfc' -H 'content-type: application/json' -H 'origin: https://clockin.carol.ai' --compressed |
O retorno é semelhate ao abaixo:
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "mdmConnectorId": "90d7bcd37c424d85a733a42117528792", "mdmCreatedUser": "[email protected]", "mdmEntityType": "mdmHeartbeat", "mdmHeartbeatData": { "databases": [ { "database": "Microsoft SQL Server", "fullVersion": "13.00.1601", "id": "d2844ee37088c437109a55c40f36d745abad48d2", "version": "13.0" }, { "database": "Directory", "id": "defb02fc824ea527814cbd2d78f04bfde99a180d" } ], "encoding": "UTF-8", "freeSpace": "126397394944", "hostAddress": "10.172.158.209", "javaVersion": "11.0.5", "javaVmName": "OpenJDK 64-Bit Server VM", "lastConnectionTimestamp": { "d2844ee37088c437109a55c40f36d745abad48d2": "2019-11-28T13:31:55Z", "defb02fc824ea527814cbd2d78f04bfde99a180d": "1970-01-01T00:00:00Z" }, "now": "2019-11-28T14:01:55Z", "osArch": "amd64", "osName": "Windows 10", "osVersion": "10.0", "recordCountLast24Hours": "0", "recordCountLastHour": "0", "startTime": "2019-11-14T18:56:58Z", "tenant": "clockin", "timezone": "GMT-03:00", "user": "robson.poffototvs.com", "version": "2.30.5" }, "mdmHeartbeatInterval": 0, "mdmId": "13b7fdffa90340fc92b418a0f4944db2", "mdmLastHeartbeatTime": "2020-06-21T20:47:49.899Z", "mdmLastUpdated": "2020-06-21T20:47:49.904Z", "mdmTenantId": "4c2c9090e7c611e893bf0e900682978b", "mdmUpdatedUser": "[email protected]" } |
Exemplo de request:
https://totvsdouglas.qarol.ai/api/v3/staging/sendingLimit
/api/v3/staging/sendingLimit
{
"quantity": 41,
"unit": "MEGABYTES"
}
Agora que os processos para envio dos dados foram apresentados, é possível efetuar um processo completo de sincronização dos dados com a plataforma Carol. Esses passos descritos nesta seção são os mesmos que o Carol Connect (2C) utiliza.
...