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

Índice

indent	Índice
exclude	Índice

Visão Geral

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

<<Diagrama sequencia login Envio Dados Carol>>Image Added

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

Image Modified

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.

/api/v1/oauth2/token

Este endpoint permite efetuar a autenticação na Carol, validando se o usuário e a senha possuem acesso à plataforma. Abaixo é detalhado os parâmetros necessários:

...

Este parâmetro aceita um dos seguintes valores: password ou refresh_token.

Password é utilizado no fluxo de geração do token, enquanto refresh_token é utilizado par renovar um token já existente.

...

Abaixo é um exemplo da request usando o comando "curl":

...

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:

Image Added

Atualizar o schema de uma staging table:

Image Added

Eliminar (drop) uma staging table:

Image Added

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.

Image Added

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":

Image Added

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

Image Added

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.

Image Added

Informações

title	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.

Informações

title	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.

Informações

title	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.

Image Added

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.

Image Added

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.

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":

Image Added

Quando o conector fica sem enviar dados por mais do que 24 horas um alerta é exibido, conforme abaixo:

Image Added

O envio do heart-beat ocorre através da request abaixo:

Bloco de código

language	bash
linenumbers	true

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.

Informações

title	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:

Bloco de código

language	bash
title	Obter heart-beat
linenumbers	true

curl 'https://api

...

O resultado da request é semelhante ao abaixo:

{ "access_token": "1e2fe288fa3a4ca38257294008081317", "client_id": "4c2c9090e7c611e893bf0e900682978b_33dd1190ff2c11e8858be609736e2a59_c1367ca0e86311e8b979aedbc4a09666_mdmConnector", "expires_in": 3495, "refresh_token": "1fd8bc5763734ad0b8e18e2cd328f2f8", "state": "", "timeIssuedInMillis": 1591855130722, "token_type": "bearer" }

/api/v1/oauth2/token/{access_token}/userAccessDetails

Este endpoint permite resgatar detalhes referente ao token, inclusive verificar se o token ainda esta valido:

...

Access token gerado pelo endpoint "token".

Abaixo é um exemplo da request usando o comando "curl":

...

.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

language	js
title	Dados heart-beat
linenumbers	true

{
  "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

Image Added

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.

...

O resultado da request é semelhante ao abaixo:

{ "envUserId": "c1367ca0e86311e8b979aedbc4a09666", "externalAppId": "33dd1190ff2c11e8858be609736e2a59", "loginLevel": "mdmTenant", "orgId": "856e0510729e11e99928acde48001122", "refreshToken": "1fd8bc5763734ad0b8e18e2cd328f2f8", "system": false, "tenantId": "4c2c9090e7c611e893bf0e900682978b", "userId": "fe115382754247d883d9a11b88b3d96e" }

Próximos passos

Uma vez que a autenticação ocorreu, teremos o access_token disponível. Este valor deve ser insirido no swagger no atributo "Access Token" (parte superior central).

Image Removed

As subsequentes requests vão autenticadas conforme a request a seguir:

curl -X GET "https://clockin.carol.ai/api/v1/users?pageSize=10&sortOrder=ASC" -H "accept: application/json" -H "Authorization: 1e2fe288fa3a4ca38257294008081317"

HTML

<!-- esconder o menu --> 


<style>
div.theme-default .ia-splitter #main {
    margin-left: 0px;
}
.ia-fixed-sidebar, .ia-splitter-left {
    display: none;
}
#main {
    padding-left: 10px;
    padding-right: 10px;
    overflow-x: hidden;
}

.aui-header-primary .aui-nav,  .aui-page-panel {
    margin-left: 0px !important;
}
.aui-header-primary .aui-nav {
    margin-left: 0px !important;
}
</style>

Árvore de páginas

Versões comparadas

Versão antiga 2

Nova versão Atual

Chave

Índice

Visão Geral

/api/v1/oauth2/token

Definindo o schema da staging table

Criar uma staging table:

Atualizar o schema de uma staging table:

Eliminar (drop) uma staging table:

Manutenção do schema de uma staging table

Enviando dados para uma staging table

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

Eliminando dados através da staging area

Enviando e consumindo informações Heart-beat

/api/v1/oauth2/token/{access_token}/userAccessDetails

Limite de registros a serem enviados por requisição

Próximos Passos

Próximos passos

Árvore de páginas

Histórico da Página

Versões comparadas

Versão antiga 2

Nova versão Atual

Chave

Índice

Visão Geral

/api/v1/oauth2/token

Definindo o schema da staging table

Criar uma staging table:

Atualizar o schema de uma staging table:

Eliminar (drop) uma staging table:

Manutenção do schema de uma staging table

Enviando dados para uma staging table

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

Eliminando dados através da staging area

Enviando e consumindo informações Heart-beat

/api/v1/oauth2/token/{access_token}/userAccessDetails

Limite de registros a serem enviados por requisição

Próximos Passos

Próximos passos