Histórico da Página
NOME DO REQUISITO
Linha de Produto: | T-Reports |
Segmento: | T-Reports |
Módulo: | T-Reports. |
- Pré-requisitos
- Plataforma com suporte REST e autenticação Basic.
- Suporte a tratamento cross-domain, por conta das requisições de serviços em servidores de domínio diferente.
- O modelo de implementação dessa API foi criado seguindo o documento "Guia de implementação de API" disponível no link abaixo:
http://tdn.totvs.com/pages/viewpage.action?pageId=274849083
- Definições gerais
Os retornos dos serviços REST devem estar encapsulados dentro de um objeto JSON com a seguinte especificação:
Mensagens de erroPara todas as mensagens que representam um erro (códigos HTTP 4xx e 5xx) deve-se retornar obrigatoriamente os campos a seguir:
{
code:
""
,
message:
""
,
detailedMessage:
""
}
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 sucessoMensagens de sucesso (código http 2xx devem) devem retornar diretamente a entidade que representa o objeto resultado da operação do endpoint. Ex:
Exemplo:
POST http:
//totvs.com.br/api/trep/v1/dbdataproviders/testeconnection
{
testConnection
:
"true"
}
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/Informações Com o intuito de facilitar o entendimento do documento, a URL base do RM descrita acima será utilizada no restante do documento.
- Descrição dos serviços
Os serviços REST descritos a seguir estão divididos em:
- 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 retorno de dados;
Na descrição de cada serviço podemos encontrar os seguintes elementos:
- Definição da URL do serviço;
- Parâmetros de request (entrada) e response (saída);
- Descrição do serviço com detalhes relativos ao seu funcionamento;
- Serviço de leitura de parâmetros de provedor;
GET /api/trep/v1/dbdataproviders/parameters
Recebe
Não recebe parâmetros
Retorna
Application/JSON
Esse método é utilizado para obter os parâmetros do provedor integrado do tipo "dados relacionais". 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,
}]
}
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 T-Reports, conforme abaixo:
Serviço de teste de conexão do provedor
POST /api/trep/v1/dbdataproviders/testconnectionRecebe
Application/JSON
Retorna
Application/JSON
Esse método é utilizado para testar a conexão de um provedor integrado do tipo "dados relacionais".
No Json de entrada devem ser enviados os parâmetros recuperados pelo serviço acima "GET /api/trep/v1/dbdataproviders/parameters".Informações title Exemplo de json de entrada {
“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 do bem sucedido. Pode ser true ou false
Informações title Exemplo de json de retorno {
“testSuccess” : true;
}
Esse método é utilizado no click do botão "Teste conexão" localizado no "cadastro de provedores de dados" do front-end do T-Reports, conforme abaixo:
Serviço de teste de sentenças sql
POST /api/trep/v1/dbdataproviders/testqueryRecebe
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: Parâmetros do provedor de dados. Devem ser enviados os parâmetros recuperados pelo serviço acima "GET /api/trep/v1/dbdataproviders/parameters".
- 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;
Informações title Exemplo de json de entrada {
“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 do bem sucedido. Pode ser true ou false
Informações title Exemplo de json de retorno {
“testSuccess” : true;
}
Serviço de leitura de schema de tabelas físicas;
GET /api/trep/v1/dbdataproviders/schematableRecebe
Application/JSON
Retorna
Application/JSON
Esse método é utilizado para retornar o schema (estrutura) de uma tabela localizada fisicamente em um determinado provedor de dados.
No Json de entrada devem ser enviadas os seguintes informações:
- providerParams: Parâmetros do provedor de dados. Devem ser enviados os parâmetros recuperados pelo serviço acima "GET /api/trep/v1/dbdataproviders/parameters".
- tableSourceName: Nome da tabela do banco de dados;
tablesSourceGetRelations: Lista de todas as tabelas físicas cadastradas no dicionário de dados do relatório. Através dessa lista, todas os relacionamentos entre essas tabelas poderão ser recuperados automaticamente. Evitando assim, o cadastro manual dos relacionamentos.
Informações title Exemplo de json de entrada {
“providerParams” : [{
“name” : “aliasName”,
“description” : “Nome do alias do RM”,
“value” : “CorporeRM”,
“isPassword” : false,
}],
"tableSourceName": "PFUNC",
"tablesSourceGetRelations": [
{"tableSourceName", "PFUNC"},
{"tableSourceName", "PFUNC"}
]
}
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
- columnName
Informações | ||
---|---|---|
| ||
{ “schemaTable” : { "tableSourceName": "PFUNC", "tableSourceDescription": "Funcionários", "columns": [ {"columnName": "CODCOLIGADA", "columnDescription": "Codigo da coligada", "columnType": "System.Int32"}, {"columnName": "CHAPA", "columnDescription": "Chapa do funcionario", "columnType": "System.string"}, {"columnName": "SALARIO", "columnDescription": "Salario do funcionário", "columnType": "System.double"}] }, “relations” : [{ "relationName": "PFUNC_PFDEPEND", "parentSourceName": "PFUNC", "childSourceName": "PFDEPEND", "parentColumns": [{"columnName": "CODCOLIGAGA"}, {"columnName": "CHAPA"}], "childColumns": [{"columnName": "CODCOLIGAGA"}, {"columnName": "CHAPA"}], ] |