Índice:

Objetivo:

     O objetivo desse documento é especificar os serviços para criação de provedores integrados para dados relacionais.

Essa especificação deve ser utilizada como guia para o desenvolvimento de provedores integrados para dados relacionais do T-Reports.

Os endpoints expostos por esses serviços serão chamados automaticamente pela ferramenta T-Reports utilizando para isso o cadastro de provedores de dados localizado no front-end do T-Reports.

A documentação dos provedores de dados está disponível em :Provedor de Dados#1

Você pode encontrar um provedor integrado de exemplo com swagger em nosso repositório no Github:

https://github.com/totvs/treports-provider-sample

Pré-requisitos:

1. Plataforma com suporte REST e autenticação Basic.
2. Suporte a tratamento cross-domain, por conta das requisições de serviços em servidores de domínio diferente.
3. Modelo de implementação de acordo com o documento "Guia de implementação de API" disponível no link: http://tdn.totvs.com/pages/viewpage.action?pageId=274849083

Definições gerais:

      O retorno dos serviços REST dos endpoints descritos abaixo devem estar encapsulados dentro de um objeto JSON com a seguinte especificação

Mensagens de erro (códigos HTTP 4xx e 5xx retornados no cabeçalho da resposta)

1. 1. Devem-se retornar os campos a seguir:

      {     code: "",     message: "", } Exemplo: POST http://totvs.com.br/api/trep/v1/dbdataproviders/testeconnection {     code: "",     message: "Erro ao testar conexão com o banco de dados",     detailedMessage: "Banco de dados oracle não disponível" }

      Mensagens de sucesso (código http 2xx retornados no cabeçalho da resposta)

      Devem-se retornar diretamente a entidade que representa o objeto resultado da operação do endpoint.
      

      Exemplo: POST http://totvs.com.br/api/trep/v1/dbdataproviders/testeconnection {   testConnection: "true" }

   2. Todas as linhas de produto devem estabelecer uma URL base, a partir da qual os serviços REST de provedor integrado serão disponibilizados. 

   3. Como exemplo, no ERP RM foi definida a seguinte  URL base: 
      /api/trep/v1/dbdataproviders/ 

Essa Url base deve ser informada no cadastro de provedores de dados localizado no front-end do T-Reports no campo "Rota" conforme figura abaixo:

Definição dos serviços:

      Segue abaixo os serviços REST que precisam ser implementados:

• Serviço de leitura de parâmetros gerais;
• Serviço de teste de conexão;
• Serviço de teste de sentenças sql;
• Serviço de leitura de schema de tabelas físicas;
• Serviço de leitura de schema de sentença sql;
• Serviço de leitura de dados;

Na descrição de cada serviço podemos encontrar os seguintes elementos:

• Definição da URL do serviço;
• Descrição do serviço com detalhes relativos ao seu funcionamento;
• Detalhamento dos parâmetros de entrada (request) e saída (response);

a) Serviço de leitura de parâmetros de provedor:

GET /api/trep/v1/dbdataproviders/parameters      

Esse método é utilizado para obtenção dos parâmetros do provedor integrado. A necessidade e definição desses parâmetros é de responsabilidade do dono do provedor. 

No JSON de retorno, deve constar as seguintes informações:

• name: Nome do parâmetro;

• description: Descrição do parâmetro;

• value: Valor do parâmetro;

• isPassword: Define se o valor do parâmetro será gravado e mostrado de forma criptografada. Pode ser true ou false
  
  

  Informações
  title Exemplo de json de retorno
  {        "providerParams" : [{              "name" : "aliasName",              "description" : "Nome do alias do RM",              "value" : "CorporeRM",              "isPassword" : false        }] }

b) Serviço de teste de conexão do provedor:

POST /api/trep/v1/dbdataproviders/testconnection

Esse método é utilizado para testar a conexão de um provedor integrado. 

No Json de entrada devem ser enviados os parâmetros cadastrados na tela de "Provedores de dados". Esses parâmetros são os mesmos recuperados pelo serviço definido acima "GET /api/trep/v1/dbdataproviders/parameters".

 No JSON de retorno, deve constar as seguintes informações:

testSuccess: Informa se o teste no provedor foi bem sucedido ou não. Pode ser true ou false

Esse método é utilizado no click do botão "Testar conexão" localizado no "cadastro de provedores de dados" do front-end do T-Reports, conforme abaixo:

c) Serviço de teste de sentenças sql:

POST /api/trep/v1/dbdataproviders/testquery

Esse método é utilizado para testar a sintaxe de uma sentença sql. 

No Json de entrada devem ser enviadas os seguintes informações: 

• • providerParams: Parâmetros do provedor de dados.
  • sqlText: Texto da sentença sql;
  • sqlParameters: Parâmetros da sentença sql;
    • paramName: Nome do parâmetro da sentença sql;
    • paramValue: Valor do parâmetro da sentença sql;
    • paramType: Tipo do parâmetro;

No JSON de retorno, deve constar as seguintes informações:

testSuccess: Informa se o teste foi bem sucedido ou não. Pode ser true ou false

d) Serviço de leitura de schema de tabelas físicas:

POST /api/trep/v1/dbdataproviders/schema/table

Esse método é utilizado para retornar o schema (estrutura) de uma tabela ou view localizada fisicamente em um determinado banco de dados. 

No Json de entrada devem ser enviadas os seguintes informações: 

• providerParams: Parâmetros do provedor de dados. 
• tableSourceName: Nome da tabela ou view do banco de dados;

tablesSourceGetRelations: Lista contendo informações de todas as tabelas físicas cadastradas no dicionário de dados do relatório.

• tableSourceName: Nome da tabela ou view do banco de dados;

No JSON de retorno, deve constar as seguintes informações:

schemaTable: Objeto contendo as seguinte informações:

• tableSourceName: Nome da tabela de banco de dados;
• tableSourceDescription: Descrição da tabela de banco de dados. Essa informação pode ser recuperada de um dicionário de dados.
• columns: lista contendo as seguinte informações:
  • columnName: Nome da coluna;
  • columnDescription: Descrição da coluna da tabela. Essa informação pode ser recuperada de um dicionário de dados.;
  • columnType: tipo da coluna;

schemaRelations: lista contendo as seguinte informações:     

• • relationName: Nome do relacionamento recuperado de um dicionário de dados;
  • parentTableSourceName: Nome da tabela pai em um relacionamento;
  • childTableSourceName: Nome da tabela filha em um relacionamento;
  • parentColumns: lista de colunas da tabela pai em um relacionamento contendo as seguinte informações:
  • • columnName;
  • childColumns: lista de colunas filhas em um relacionamento contendo as seguinte informações:
    • columnName
      
      
      

Esse método é utilizado na tela de cadastro de entidade do tront-end do reports, ao escolher uma fonte de dados ligada a uma tabela física:

e) Serviço de leitura de schema de sentenças sql:

POST /api/trep/v1/dbdataproviders/schemasql

Esse método é utilizado para retornar o schema (estrutura) de uma sentença sql disparada em um determinado provedor de dados. 

No Json de entrada devem ser enviadas os seguintes informações: 

• providerParams: Parâmetros do provedor de dados.
• sqlText: Sentença sql cadastrada na fonte de dados do relatório;

• sqlParameters: Lista de objeto contendo informações dos parâmetros da sentença sql:

  • paramName: Nome do parâmetro da sentença sql;

  • paramValue: Valor do parâmetro da sentença sql;
  • paramType: Tipo do parâmetro;

No JSON de retorno, deve constar as seguintes informações:

• schemaSql: objeto contendo as seguinte informações:

  • columns: lista contendo as seguinte informações:
    • columnName: Nome da coluna;
    • columnType: tipo da coluna;

  Informações
  Esse método não contêm informações de relacionamento, visto que, trata-se de uma sentença sql. Nesse caso, as informações de relacionamento não poderão ser recuperadas automaticamente de dicionários de dados.

Esse método é utilizado na tela de cadastro de entidade do tront-end do reports, ao escolher uma fonte de dados ligada a uma sentença sql:

f) Serviço de leitura de dados:

POST /api/trep/v1/dbdataproviders/data

Esse método é utilizado para retornar os dados do relatórios. 

No Json de entrada devem ser enviadas as seguintes informações: 

• providerParams: Parâmetros do provedor de dados.
• sentenceMember: Objeto contendo as seguinte informações:

• • entityName: Nome da entidade cadastrada no reports que receberá os dados.

  • sqlText: sentença sql a ser disparada no banco de dados;

  • sqlParameters: Lista de objeto contendo informações dos parâmetros da sentença sql:

    • paramName: Nome do parâmetro da sentença sql;

    • paramValue: Valor do parâmetro da sentença sql;
    • paramType: Tipo do parâmetro;

• maxRecords: número máximo de registros a serem retornados. Se o valor for < 0 (default), serão retornados todos os registros.

No JSON de retorno, deve constar as seguintes informações:

• • • data: Dados recuperadas no banco de dados através da execução da sentença sql enviada no objeto de request: