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 TReports.
Os endpoints expostos por esses serviços serão chamados automaticamente pela ferramenta TReports utilizando para isso o cadastro de provedores de dados localizado no front-end do TReports.
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
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)
Devem-se retornar os campos a seguir:
Exemplo:
|
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.
|
Todas as linhas de produto devem estabelecer uma URL base, a partir da qual os serviços REST de provedor integrado serão disponibilizados.
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 TReports no campo "Rota" conforme figura abaixo:
Com o objetivo de facilitar o entendimento do documento, a URL base do RM descrita acima será utilizada no restante do documento para melhor localização dos endpoints. |
Segue abaixo os serviços REST que precisam ser implementados:
Na descrição de cada serviço podemos encontrar os seguintes elementos:
GET /api/trep/v1/dbdataproviders/parameters
Recebe | Não recebe parâmetros |
Retorna | Application/JSON |
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;
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
{ "providerParams" : [{ "name" : "aliasName", "description" : "Nome do alias do RM", "value" : "CorporeRM", "isPassword" : false }] } |
Os parâmetros retornados por esse serviço aparecerão na grid de parâmetros localizada no "cadastro de provedores de dados" do front-end do TReports, conforme abaixo: |
POST /api/trep/v1/dbdataproviders/testconnection
Recebe | Application/JSON |
Retorna | Application/JSON |
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".
{ "providerParams" : [{ "name" : "aliasName", "description" : "Nome do alias do RM", "value" : "CorporeRM", "isPassword" : false }] } |
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
{ “testSuccess” : true; } |
Esse método é utilizado no click do botão "Testar conexão" localizado no "cadastro de provedores de dados" do front-end do TReports, conforme abaixo:
POST /api/trep/v1/dbdataproviders/testquery
Recebe | Application/JSON |
Retorna | Application/JSON |
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" : [{ "name" : "aliasName", "description" : "Nome do alias do RM", "value" : "CorporeRM", "isPassword" : false }], "sqlText": "select * from pfunc where codcoligada = :codcol", "sqlParameters": [{ "paramName": "codcol", "paramValue": "1", "paramType": "system.Int32" }] } |
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
{ “testSuccess” : true; } |
POST /api/trep/v1/dbdataproviders/schema/table
Recebe | Application/JSON |
Retorna | Application/JSON |
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" : [{ "name" : "aliasName", "description" : "Nome do alias do RM", "value" : "CorporeRM", "isPassword" : false }], "tableSourceName": "PFUNC", } |
No JSON de retorno, deve constar as seguintes informações:
schemaTable: Objeto contendo as seguinte informações:
Obs: Abaixo uma tabela definindo o mapeamento correto dos tipos das colunas. O nome do tipo definido na coluna "Tipo do TReports" deve ser retornado na propriedade "columnType" do objeto de retorno.
Definição do tipo | Nome do tipo a ser retornado | Tipo da framework .Net |
---|---|---|
Sequência de caracteres | String | System.string |
Data | DateTime | System.DateTime |
Representa um número de 64-bit de precisão dupla com valores que variam do negativo 1.79769313486232e308 ao positivo 1.79769313486232e308, bem como zero positivo ou negativo | Double | System.Double |
Representa um número de 32 bits de precisão simples com valores que variam do negativo 3.402823e38 ao positivo 3.402823e38, bem como zero positivo ou negativo | Float | System.Single |
Representa um número de com valroes que variam entre 79,228,162,514,264,337,593,543,950,335 ao positivo 79,228,162,514,264,337,593,543,950,335. É apropriado para cálculos financeiros que requere um grande número de dígitos e frações sem falhas em arrendondamentos. | Decimal | System.Decimal |
Representa inteiros com sinal com valores que variam de 32768 negativo a 32767 positivo. | Integer16 | System.Int16 |
Representa inteiros com sinal com valores que variam de 2.147.483.648 negativo ao 2.147.483.647 positivo | Integer32 | System.Int32 |
Representa inteiros com sinal com valores que variam de negativo 9,223,372,036,854,775,808 ao positivo 9,223,372,036,854,775,807 | Integer64 | System.Int64 |
Representa os valores "true" ou "false" | Boolean | System.Boolean |
Array de bytes. Geralmente usado para representação de uma imagem. | Bytes | System.Byte[] |
{ |
Esse método é utilizado na tela de cadastro de entidade do tront-end do TReports, ao escolher uma fonte de dados ligada a uma tabela física:
POST /api/trep/v1/dbdataproviders/schemasql
Recebe | Application/JSON |
Retorna | Application/JSON |
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:
sqlParameters: Lista de objeto contendo informações dos parâmetros da sentença sql:
paramName: Nome do parâmetro da sentença sql;
{ "providerParams" : [{ "name" : "aliasName", "description" : "Nome do alias do RM", "value" : "CorporeRM", "isPassword" : false }], "sqlText": "select * from pfunc where codcoligada = :codcol", "sqlParameters": [{ "paramName": "codcol", "paramValue": "1", "paramType": "system.Int32" }] } |
No JSON de retorno, deve constar as seguintes informações:
schemaSql: objeto contendo as seguinte informações:
Obs: Abaixo uma tabela definindo o mapeamento correto dos tipos das colunas. O nome do tipo definido na coluna "Tipo do TReports" deve ser retornado na propriedade "columnType" do objeto de retorno.
Definição do tipo | Tipo do TReports | Tipo da framework .Net |
---|---|---|
Sequência de caracteres | String | System.string |
Data | DateTime | System.DateTime |
Representa um número de 64-bit de precisão dupla com valores que variam do negativo 1.79769313486232e308 ao positivo 1.79769313486232e308, bem como zero positivo ou negativo | Double | System.Double |
Representa um número de 32 bits de precisão simples com valores que variam do negativo 3.402823e38 ao positivo 3.402823e38, bem como zero positivo ou negativo | Float | System.Single |
Representa um número de com valroes que variam entre 79,228,162,514,264,337,593,543,950,335 ao positivo 79,228,162,514,264,337,593,543,950,335. É apropriado para cálculos financeiros que requere um grande número de dígitos e frações sem falhas em arrendondamentos. | Decimal | System.Decimal |
Representa inteiros com sinal com valores que variam de 32768 negativo a 32767 positivo. | Integer16 | System.Int16 |
Representa inteiros com sinal com valores que variam de 2.147.483.648 negativo ao 2.147.483.647 positivo | Integer32 | System.Int32 |
Representa inteiros com sinal com valores que variam de negativo 9,223,372,036,854,775,808 ao positivo 9,223,372,036,854,775,807 | Integer64 | System.Int64 |
Representa os valores "true" ou "false" | Boolean | System.Boolean |
Array de bytes. Geralmente usado para representação de uma imagem. | Bytes | System.Byte[] |
{ “schemaSql” : { "columns": [ {"columnName": "CODCOLIGADA", "columnType": "System.Int32"}, {"columnName": "CHAPA", "columnType": "System.string"}, {"columnName": "SALARIO", "columnType": "System.double"}] } } |
Esse método é utilizado na tela de cadastro de entidade do tront-end do TReports, ao escolher uma fonte de dados ligada a uma sentença sql:
POST /api/trep/v1/dbdataproviders/relations
Recebe | Application/JSON |
Retorna | Application/JSON |
Esse método é utilizado para retornar os relacionamentos existentes entre duas tabelas físicas.
No Json de entrada devem ser enviadas os seguintes informações:
{ "providerParams" : [{ "name" : "aliasName", "description" : "Nome do alias do RM", "value" : "CorporeRM", "isPassword" : false }], "parentTableName": "PFUNC", "childTableName": "PFDEPEND" } |
No JSON de retorno, deve constar as seguintes informações:
relations: lista contendo as seguinte propriedades:
{ "relationName": "PFUNC_PFDEPEND", "childTableName": "PFDEPEND", { "childColumns": [ { }] |
Esse método é utilizado na tela de cadastro de relacionamento do tront-end do TReports, ao escolher uma tabela filha ou pai:
POST /api/trep/v1/dbdataproviders/search/tables
Recebe | Application/JSON |
Retorna | Application/JSON |
Esse método é utilizado para retornar as tabelas pesquisadas em um determinado provedor de dados.
No Json de entrada devem ser enviadas os seguintes informações:
{ "providerParams" : [{ "name" : "aliasName", "description" : "Nome do alias do RM", "value" : "CorporeRM", "isPassword" : false }], "findTable": "PF", "page": 1, "pageSize": 10 } |
No JSON de retorno, deve constar as seguintes informações:
hasNext: Informa se existem mais registro para serem recuperados na paginação;
searchTables: lista contendo os nomes e descrição das tabelas recuperadas:
{ "hasNext": "false", "tableSourceName": "PFUNC", }, { "tableSourceName": "PFDEPEND", } ] |
Esse método é utilizado na tela de cadastro de fonte de dados. Aparecerá um lookup de pesquisa nessa tela se a fonte de dados estiver ligada a um provedor de dados integrado. Caso seja uma fonte de dados ligada a um provedor de banco de dados relacional, o usuário informará o nome da tabela manualmente.
POST /api/trep/v1/dbdataproviders/data
Recebe | Application/JSON |
Retorna | Application/JSON |
Esse método é utilizado para retornar os dados do relatórios.
No Json de entrada devem ser enviadas as seguintes informações:
entityName: Nome da entidade cadastrada no TReports que receberá os dados.
sqlParameters: Lista de objeto contendo informações dos parâmetros da sentença sql:
paramName: Nome do parâmetro da sentença sql;
{ "providerParams" : [{ "name" : "aliasName", "description" : "Nome do alias do RM", "value" : "CorporeRM", "isPassword" : false }], "sentenceMember": { "entityName": "Funcionarios", "sqlText": "select * from pfunc where codcoligada = :codcol", "sqlParameters": [{ "paramName": "codcol", "paramValue": "1", "paramType": "system.Int32" }], "maxRecords": 10 } } |
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:
Os dados recuperados devem ser retornados no formato xml ou no formato json. É necessário enviar no cabeçalho da resposta o tipo de conteúdo enviado. Content-type = application/xml ou Content-type = application/json |
{ "data": "xml ou json contendo o resultado da execução da sentença sql" } |
Um código exemplo demonstrando um provedor trabalhando com json e xml está disponível em treports-provider-sample.
|
|