A Carol possui autenticação OAuth, podendo ser explorado a autenticação API Key (também conhecido como API Token ou Connector Token)algumas formas para efetuar o consumo de dados por aplicativos terceiros. O formato mais convencional é através de "filters" ou "named queries".

Índice

Visão Geral

Abaixo um fluxo demonstrando o processo de login integrado ao API Key:de consumo de dados da Carol através de filter ou named queries:

Image Added<<Diagrama sequencia login OAuth + API Key>>

Abaixo é listado os principais serviços ligados ao fluxo OAuthde consumo de dados:

Image RemovedImage Added

Esses serviços permitem efetuar a autenticação na Carol e efetuar a validação de um token já existente. Vamos ver os detalhes desses serviços:

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

...

Estes serviços permitem o consumo de dados através de consultas (filter/queries) ou através de consultas nomeadas (named-queries). Ambos recursos serão detalhados nos próximos capítulos.

Filter/Queries

A forma mais convencional de consumo de dados na Carol é através de consultas (filter/queries) e consultas nomeadas (named queries). Esses recursos permitem o consumo de dados considerando a estrutura de dados definida no data model.

A Carol possui uma série de recursos ligados às consultas para consumo dos dados. Para buscar detalhes do serviços, você pode consultar o seguinte link: https://docs.carol.ai/docs/querying-data

O print-screen abaixo mostra o serviço utilizado para executar os filtros/queries:

Image Added

Este serviço retorna uma lista de golden records, no qual será detalhado no próximo capítulo.

Named Queries

Outra forma de trabalhar com consultas na Carol é através de named queries. As named queries permitem armazenar o filtro/query na Carol, permitindo assim uma manutenção mais ágil da named query.

A named query possui os mesmos recursos disponíveis na documentação acima compartilhada (https://docs.carol.ai/docs/querying-data), tendo como diferença é que o filtro fica armazenado na Carol e o aplicativo externo (consumidor) vai apenas referenciar à consulta armazenada na Carol. Os beneficios ligados a este recurso são:

• Cache de dados.
• Melhor manutenibilidade da consulta.
• Fácil reutilização e propagação da mesma query para todos os aplicativos consumidores.

Abaixo é apresentado o serviço responsável por executar uma named query:

Image Added

A seguir, um exemplo de um "Filter":

{
    "excludeMergePending": false,
    "filtering": true,
    "minimumShouldMatch": 1,
    "mustList": [
      {
        "mdmFilterType": "TYPE_FILTER",
        "mdmValue": "deviceGolden"
      },
      {
        "mdmFilterType": "TERM_FILTER",
        "mdmKey": "mdmGoldenFieldAndValues.integraterm",
        "mdmValue": true
      },
      {
        "mdmFilterType": "WILDCARD_FILTER",
        "mdmKey": "mdmGoldenFieldAndValues.devicedescription",
        "mdmValue": "{{deviceDescription}}"
      }
    ],
    "resolveRelationships": false
  }

Criando/Atualizando uma named query

As named queries são filtros dentro de um envelope (estrutura Json), armazenados na Carol. Os filtros ficam encapsulados conforme abaixo:

{
  "mdmCacheRevalidationTimeInSeconds": 0,
  "mdmCacheTimeInSeconds": 0,
  "mdmFilterQuery": {
    "excludeMergePending": false,
    "filtering": true,
    "minimumShouldMatch": 1,
    "mustList": [
      {
        "mdmFilterType": "TYPE_FILTER",
        "mdmValue": "deviceGolden"
      },
      {
        "mdmFilterType": "TERM_FILTER",
        "mdmKey": "mdmGoldenFieldAndValues.integraterm",
        "mdmValue": true
      },
      {
        "mdmFilterType": "WILDCARD_FILTER",
        "mdmKey": "mdmGoldenFieldAndValues.devicedescription",
        "mdmValue": "{{deviceDescription}}"
      }
    ],
    "resolveRelationships": false
  },
  "mdmQueryDescription": "Retorna a lista de dispositivos",
  "mdmQueryName": "deviceList",
  "mdmQueryPaid": false,
  "mdmQueryParams": [
    {
      "mdmDescription": {},
      "mdmEditable": true,
      "mdmInherited": false,
      "mdmLabel": {},
      "mdmName": "deviceDescription",
      "mdmRequired": false,
      "mdmValueType": "string"
    }
  ],
  "mdmReturnFields": [],
  "mdmTimeoutInSeconds": 55,
  "mdmType": "deviceGolden"
}

Um destaque para o atributo "mdmFilterQuery" que possui o filtro que será executado quando a named query "deviceList" for executada.

O print-screen exibe qual o serviço responsável por adicionar a named query:

Image Added

Após salvar a named query, um código (mdmId) é retornado referente a named query. Este código é utilizado para atualizar e eliminar a named query. O serviço abaixo é o responsável por atualizar a named query:

Image Added

O serviço a seguir retorna a lista de named queries existentes, fazendo com que seja possível recuperar todas as named queries existentes neste momento no ambiente:

Image Added

Eliminando uma named query

Após adicionar uma named query (e obter o código mdmId) é possível eliminar a named query com o serviço abaixo:

Image Added

O parâmetro "force" indica se a named query deverá ser elininado mesmo q eu tenha referência por outros recursos, como um Insight ou Carol App.

Próximos Passos

Você pode entender a estrutura dos registros de Golden Record consumidos nesta documentação: https://tdn.totvs.com/display/public/CARL/Detalhes+Golden+Record

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

curl -X POST "https://clockin.carol.ai/api/v1/oauth2/token" -H "accept: application/json" -H "content-type: application/x-www-form-urlencoded" -d "grant_type=password&connectorId=clockinmobile&username=robson.poffo%40totvs.com&password=SENHA_AQUI&subdomain=clockin&orgSubdomain=global"

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

curl -X GET "https://clockin.carol.ai/api/v1/oauth2/token/1e2fe288fa3a4ca38257294008081317/userAccessDetails" -H "accept: application/json"

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"

<!-- 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>