Carol

Árvore de páginas

A Carol possui autenticação OAuth, podendo ser explorado a autenticação API Key (também conhecido como API Token ou Connector Token).


Índice


Visão Geral


Abaixo um fluxo demonstrando o processo de envio de dados para a Carol:



Abaixo é listado os principais serviços ligados ao fluxo staging area:



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.


Definindo o schema da staging table


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.


O seguinte schema é um exemplo de como a definição ocorre na plataforma Carol:


{"mdmFlexible": "false", "mdmExportData": "false","mdmStagingMapping":{"properties":{"cod-emitente":{"type":"integer"},"cgc":{"type":"string"}, "nome-emit":{"type":"string"}}},"mdmCrosswalkTemplate":{"mdmCrossreference":{"emitente":["cod-emitente"]}}}


O identifier (chamado também de crosswalk) é a definição da chave primária de uma staging table. O identifier na Carol funciona com o objetivo de atualizar um registro na staging area, fazendo com que um registro já existente seja atualizado por novos valores. O identifier também é utilizado no processo de eliminação de registros, como veremos um pouco mais para frente.


A plataforma Carol dispoem os serviços necessários para criar, atualizar e apagar o schema de tabelas, conforme a seguir:


Criar uma staging table:


Atualizar o schema de uma staging table:


Eliminar (drop) uma staging table:


Manutenção do schema de uma staging table

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.



Clicando em uma staging table e na sequencia em "View Sample Data" (ou "View Data" for staging tables marcadas como Lookup table) poderemos acessar o menu abaixo, que permite acessar a opção "Manage Fields":


A opção "Manage Fields" abrirá a tela abaixo, que permite adicionar, remover ou alterar os atributos pertencentes ao identifier da staging table:



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.


Enviando dados para uma staging table


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.



Dados imutáveis

A plataforma Carol armazenao os dados na camada Carol Data Storage (CDS). Esta camada possui a característica de ser imutável, o que faz com que a Carol armazene todas as versões que o dado teve. Em outras palavras, quando um dado é alterado a plataforma preservará as duas versões (antes de atualização e a versão mais recente).


A plataforma possui o processo de consolidação para que versões anteriores do registro sejam descartados. Este processo pode ser agendado para execução frequente e automática.


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.


Parâmetros Request Envio de dados

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.


Lookup Staging Table

Lookup Staging Table por padrão possuem todos os dados disponíveis na camada real-time, camada utilizada para otimização de performance durante o processamento dos dados. Staging tables que não estejam marcadas como Lookup terão apenas um percentual disponível, em carater de uma amostragem dos dados da staging table.


Vale ressaltar que este serviço efetua o envio dos dados através de uma requisição assíncrona. Isso quer dizer que quando o serviço responder o código 200, os dados não estarão disponíveis na staging table ou no data model (explore). Alguns segundos podem ser necessários para que isso ocorrá.


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.


Enviando dados para uma staging table através do método síncrono


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 uma limitação no número de registros para o envio, e o mesmo não poderá ser utilizado para grande número de registros pois a requisição poderá levar segundos para retornar.



Este serviço possui os mesmos recursos do serviço assíncrono.

Eliminando dados através da staging area


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âmetroDescrição
tableO nome da staging table que está sendo eliminado os registros.
connectorIdO código do conector que a staging table acima pertence.
propagateCleanupParâ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.

Enviando e consumindo informações Heart-beat

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:


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

  • connectorID: query-param, obrigatório, referente ao código do conector que receberá os dados de heart-beat.
  • databases: permite o envio especifico dos bancos de dados conectados neste conector (veja mais detalhes no JSon abaixo de exemplo).
  • freeSpace: espaço disponível no ambiente que envia os dados
  • hostAddress: endereço de IP da origem dos dados
  • startTime: data/hora de início do evio dos dados
  • recordCountLastHour: quantidade de dados enviados na última hora.
  • recordCountLast24Hours: quantidade de dados enviados nas últimas 24 horas.
  • now: data/hora da último envio do heart-beat.


Processo flexível - permite envio de dados customizados

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:


Obter heart-beat
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:


Dados heart-beat
{
  "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]"
}


Limite de registros a serem enviados por requisição


  • A Carol possui o endpoint abaixo para envio de registros e o mesmo possui um padrao de 41MB e com limite de 80MB por requisição

Exemplo de request: 

https://totvsdouglas.qarol.ai/api/v3/staging/sendingLimit


/api/v3/staging/sendingLimit


{
  "quantity": 41,
  "unit": "MEGABYTES"
}

Próximos Passos


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.


Os próximos passos são a obteção (consumo) desses dados, conforme é descrito no próximo capítulo.