API que permite executar consultas em diversos bancos de dados relacionais (Oracle, SQLServer [...]) e retornar os resultados no formato JSON. A ideia do software é padronizar informações distribuídas e possibilitar o uso em programas de BI, tal como Power BI, SSIS ou Pentaho, por exemplo, ou para consumo em outras API.
O aplicativo usa o Springboot Framework, então é recomendado o uso do Open JDK 17 LTS ou superior. Para realização dos testes de requisições no formato JSON, sugiro utilizar o Insomnia ou Postman.
| Arquivo | ||
|---|---|---|
start.bat |
Inicializador para Windows |
Executar o arquivo para iniciar com a janela do CMD |
start.sh |
Inicializador para Linux |
|
szarca-api-x.x.x.jar |
Executável | Funções do sistema |
szarca-api.db |
Banco de dados (SQLite) | Tabelas (Usuários, Funções e Fontes de dados) |
cache/ |
Diretório onde serão armazenados os arquivos em cache |
Caso seja usado nas funções, deverá atentar-se as permissões de escrita |
szarca-api.db.default-x.x.x.rar |
Banco de dados padrão |
Caso precise reinstalar o sistema |
parameters.json |
Parametros de configuração do sistema |
Para iniciar, execute o arquivo start.bat ou start.sh. O serviço responderá na porta 9032 por padrão, recebendo as requisições no formato JSON. Para alterar a porta, edite o arquivo start no seu editor de texto e altere o valor --server.port=9032.
Execute o arquivo szarca-api-x.x.x.jar --server.port=9032.
Para iniciar, execute o arquivo start.bat ou start.sh. O serviço responderá na porta 9032 por padrão, recebendo as requisições no formato JSON. Para alterar a porta, edite o arquivo start no seu editor de texto e altere o valor --server.port=9032.
Header
curl --location 'http://localhost:9032/' \
--header 'Content-Type: application/json' \
--data ''
Requisição
{
"logon":
{
"user":"root",
"passwd":"root"
},
"function":"users()",
"param":{}
}| Parâmetros | ||
|---|---|---|
| user / passwd | usuário e senha do software | Por padrão, root/root |
| function | Função que trará as informações da fonte de dados | Por padrão, o sistema já possui : users() -> lista os usuários do sistema, functions() -> lista as funções e sources() -> lista as fontes de dados. Geralmente conexões com bancos de dados relacionais e não relacionais. |
| param | Filtros que serão executados na consulta | Deverá ser informado como JSONArray. Exemplo: "param":{"data":"00/00/0000","cliente":"idcliente"} |
As fontes de dados são geralmente as credenciais para banco de dados e outras aplicações. Como exemplo, iniciaremos com a adição de acesso a base MySQL como um Source.
Header
Funções de gerenciamento "management" devem ser enviadas para http://localhost:9032/admin/
Por padrão, o sistema já vem habilitado para receber solicitações de gerenciamento
curl --location 'http://localhost:9032/admin/' \
--header 'Content-Type: application/json' \
--data ''
Requisição
{
"management": {
"function":"addSource",
"param":{
"name" : "minhaConexao",
"database" : "mysql",
"host" : "127.0.0.1",
"port" : "3306",
"user" : "meuUsuarioMySQL",
"passwd" : "minhaSenhaMySQL",
"schema" : "meuSchemaMySQL"
}
}
}| Parâmetros | ||
|---|---|---|
| function | Função que executará comandos na base do sistema | addSource, addUser, addFunction para adicionar fontes, usuários e funções. Para remover, basta trocar add por remove, exemplo removeSource. |
| name | Identificador único da fonte de dados (ID) |
Ao realizar o procedimento, deverá receber a seguinte resposta:
{
"system": {
"environment": "Java",
"author": "@anderakooken",
"name": "Szarca",
"version": "2.2.0",
"architecture": "json"
},
"return": {
"type": "true"
}
}Onde no objeto return o tipo type deverá ser true. Caso retorne false, a estrutura da requisição foi no formado incorreto ou a fonte de dados já existia.
Vamos consultar a lista de fontes de dados:
Header
curl --location 'http://localhost:9032/' \
--header 'Content-Type: application/json' \
--data ''
Requisição
{
"logon": {"user":"root","passwd":"root"},
"function":"sources()", "param":{}
}Para remover a fonte de dados, realize a requisição abaixo informando como name o identificador único da fonte (ID).
Header
curl --location 'http://localhost:9032/admin/' \
--header 'Content-Type: application/json' \
--data ''
Requisição
{
"management": {
"function":"removeSource",
"param":{
"name" : "minhaConexao"
}
}
}As funções são geralmente as consultas SQL aos banco de dados relacionais e não relacionais. Como exemplo, iniciaremos com a adição de uma consulta SQL para a fonte de dados que adicionamos. O sistema só aceita consultas com o texto convertido em Base64.
Vamos supor que tenhas a seguinte consulta no seu banco de dados.
SELECT nome, email, matricula FROM usuarios WHERE id_usuario = @idUsuarioO parâmetro @idUsuario terá o seu valor informado no momento das requisições da função.
A consulta deverá ser convertida em Base64 para aceitação:
U0VMRUNUIG5vbWUsIGVtYWlsLCBtYXRyaWN1bGEgRlJPTSB1c3VhcmlvcyBXSEVSRSBpZF91c3VhcmlvID0gQGlkVXN1YXJpbw==
Header
curl --location 'http://localhost:9032/admin/' \
--header 'Content-Type: application/json' \
--data ''
Requisição
{
"management": {
"function":"addFunction",
"param":{
"name" : "meusUsuarios",
"source" : "minhaConexao",
"setCache" : "0",
"cacheDuration" : "0",
"queryText" : "U0VMRUNUIG5vbWUsIGVtYWlsLCBtYXRyaWN1bGEgRlJPTSB1c3VhcmlvcyBXSEVSRSBpZF91c3VhcmlvID0gQGlkVXN1YXJpbw==",
"queryTextParam" : "[\"idUsuario\"]",
"date" : "2022-01-15 00:00:00",
"status" : "1",
"forceColumns" : "0",
"queryColumnsText" : "",
"tableCollection" : "",
"fileQueryText" : "",
"plainText" : ""
}
}
}| Parâmetros | ||
|---|---|---|
| name | Identificador único da função | |
| source | Identificador único da fonte de dados (ID) | |
| setCache | Se a função deve um arquivo na pasta cache, marque 1, ou 0 consulta online a fonte de dados |
|
| cacheDuration | Tempo de duração do arquivo cache. Em minutos. | |
| queryText | Consulta convertida em Base64 |
|
| queryTextParam | Parâmetro para filtrar a consulta | No exemplo, @idUsuario <-> ["idUsuario"], filtrará apenas o usuário que será informado na requisição futura |
| date | Data de criação | Pode ser preenchida livremente no formato indicado 2000-01-01 00:00:00 |
| status | 1 para função em produção, 0 para desativar |
|
| forceColumns | Altera o nome das colunas do retorno e força para um Alias informado | |
| tableCollection | Para uso em banco de dados não relacional | Exemplo: Coleções no MongoDB |
Vamos consultar as funções:
Header
curl --location 'http://localhost:9032/' \
--header 'Content-Type: application/json' \
--data ''
Requisição
{
"logon": {"user":"root","passwd":"root"},
"function":"functions()", "param":{}
}O usuário root não realiza consultas em fontes externas e funções adicionadas pelo usuário, sendo seu uso exclusivo na administração das informações do software e nesse caso, teremos que criar o primeiro login de acesso.
Para tal, execute a seguinte requisição:
Header
curl --location 'http://localhost:9032/admin/' \
--header 'Content-Type: application/json' \
--data ''
Requisição
{
"management": {
"function":"addUser",
"param":{
"user" : "usuario",
"passwd" : "senha",
"email" : "[email protected]",
"roles" : ["minhaConexao"]
}
}
}| Parâmetro | ||
|---|---|---|
| roles | Poderá ser múltiplo, caso existam varias fontes | ["minhaConexao","fonte2","fonte3"] |
Vamos consultar os usuários:
Header
curl --location 'http://localhost:9032/' \
--header 'Content-Type: application/json' \
--data ''
Requisição
{
"logon": {"user":"root","passwd":"root"},
"function":"users()", "param":{}
}Para remover o acesso a fonte de dados para um determinado usuário, realize a requisição abaixo informando como user o nome do login do usuário e source o nome da fonte de dados.
Header
curl --location 'http://localhost:9032/admin/' \
--header 'Content-Type: application/json' \
--data ''
Requisição
{
"management": {
"function":"removeSecuritySource",
"param":{
"user" : "usuario",
"source" : "minhaConexao"
}
}
}Header
curl --location 'http://localhost:9032/' \
--header 'Content-Type: application/json' \
--data ''
Requisição
{
"logon":{
"user":"usuario",
"passwd":"senha"
},
"function":"meusUsuarios",
"param":{
"idUsuario" : "15"
}
}
Exibição do conjunto de resultados
{
"system": {
"environment": "Java",
"author": "@anderakooken",
"name": "Szarca",
"version": "2.2.0",
"architecture": "json"
},
"return": {
"date": "2023-05-13 10:00:28",
"ipAddress": "0:0:0:0:0:0:0:1",
"type": "true",
"message": {
"cache": {
"definiteTime": "0"
},
"function": "meusUsuarios",
"resultset": [],
"source": "minhaConexao",
"parameters": {}
},
"user": {
"name": "usuario",
"login": "usuario",
"email": "[email protected]"
}
}
}
| Retorno | ||
|---|---|---|
| resultset | Conjunto de resultados em JSONArray |
Antes de colocar o sistema em produção, atente-se ao arquivo parameters.json, no objeto "enableManagement" : true. Por padrão, o sistema já é habilitado para usar o usuário root, nesse caso, marcado como valor true. Contudo, por segurança, marque o valor como false para evitar alterações indevidas por terceiros.
Para habilitar o armazenamento do conjunto de resultados no diretório cache/, marque objeto setCache com o valor 1 e cacheDuration com o valor em minutos, exemplo 30, onde as requisições consultarão o cache ao invés de consultar a fonte de dados. Essa função é útil em caso de dados que são atualizados em grande sazonalidade.
O ALIAS funciona basicamente igual a linguagem SQL, onde trocamos o nome do campo real por um apelido, exemplo:
SELECT u.mat as Matricula, u.nome as NomeUsuario from Usuario Ao alterar o valor do forceColumns para 1, o sistema solicitará que o objetoqueryColumnsText contenha os valores a serem convertidos.
{"queryColumnsText" : "[{\"mat\":\"Matricula\"},{\"nome":"NomeUsuario\"}]"}- Importante, uma vez habilitado o ALIAS, todos os campos contidos na consulta deverão ser informados na
queryColumnsTextou não haverá resposta na requisição.
Atualmente o sistema permite conexões com o MongoDB, porém no momento da criação das funções, o valor parâmetro tableCollection deverá conter obrigatoriamente o nome da coleção.
Para envio de e-mails, será necessário incluir um fonte de dados:
Header
curl --location 'http://localhost:9032/admin/' \
--header 'Content-Type: application/json' \
--data ''
Requisição
{
"management": {
"function":"addSource",
"param":{
"name" : "smtp_pessoal",
"database" : "smtp",
"host" : "mail.meudominio.com",
"port" : "587",
"user" : "[email protected]",
"passwd" : "U0VMRUNUIG5v==",
"schema" : "Nome/Sobrenome"
}
}
}| Parâmetros | ||
|---|---|---|
| name | Identificador único da fonte de dados (ID) | |
| database | Obrigatoriamente com o valor smtp |
Informa ao sistema para usar protocolo de envio |
| host | IP do servidor para envio de e-mails | |
| schema | Nome que será exibido nos e-mails enviados |
A senha do e-mail deverá ser convertida em Base64 para aceitação:
U0VMRUNUIG5v==
As funções neste caso, diferentes de consultas SQL, será o corpo do e-mail propriamente dito. Como exemplo, iniciaremos com a adição de texto para o e-mail. O sistema só aceita consultas com o texto convertido em Base64.
Vamos colocar uma mensagem de teste.
@saudacao, meu nome é @nome. Este e-mail é apenas um teste.
Os parâmetros @saudacao e @nome terão os seus valores informados no momento da requisição da função.
A consulta deverá ser convertida em Base64 para aceitação:
QHNhdWRhY2FvLCBtZXUgbm9tZSDDqSBAbm9tZS4gRXN0ZSBlLW1haWwgw6kgYXBlbmFzIHVtIHRlc3RlLg==
Header
curl --location 'http://localhost:9032/admin/' \
--header 'Content-Type: application/json' \
--data ''
Requisição
{
"management": {
"function":"addFunction",
"param":{
"name" : "emailTeste",
"source" : "smtp_pessoal",
"setCache" : "0",
"cacheDuration" : "0",
"queryText" : "QHNhdWRhY2FvLCBtZXUgbm9tZSDDqSBAbm9tZS4gRXN0ZSBlLW1haWwgw6kgYXBlbmFzIHVtIHRlc3RlLg==",
"queryTextParam" : "[\"saudacao\",\"nome\"]",
"date" : "2022-01-15 00:00:00",
"status" : "1",
"forceColumns" : "0",
"queryColumnsText" : "[email protected],[email protected]",
"tableCollection" : "",
"fileQueryText" : "",
"plainText" : "Assunto do E-mail"
}
}
}| Parâmetros | ||
|---|---|---|
| name | Identificador único da função | |
| source | Identificador único da fonte de dados (ID) | |
| queryText | Corpo do E-mail convertido em Base64 |
|
| queryTextParam | Parâmetro para filtrar a consulta | No exemplo, @saudacao <-> ["saudacao"], filtrará apenas o usuário que será informado na requisição futura |
| queryColumnsText | E-mail dos destinatários | Podem ser vários e-mails separados por ,. |
| plainText | Titulo/Assunto do E-mail |
O sistema não aceitará que esse objeto tenha seus valores recebidos por um parâmetro, porque não serve ao proposito da aplicação. No caso, o desenvolvedor deverá criar sua própria rotina em scripts ou aplicações externas.
Header
curl --location 'http://localhost:9032/' \
--header 'Content-Type: application/json' \
--data ''
Requisição
{
"logon":{
"user":"seu_usuario",
"passwd":"sua_senha"
},
"function":"emailTeste",
"param":{
"saudacao" : "ola, bom dia.",
"nome" : "John Doe"
}
}Exibição do conjunto de resultados
{
"system": {
"environment": "Java",
"administrator": "@anderakooken",
"name": "Szarca",
"version": "2.3.0",
"architecture": "json"
},
"return": {
"date": "2023-05-17 14:02:58",
"ipAddress": "0:0:0:0:0:0:0:1",
"type": "true",
"message": {
"cache": {
"definiteTime": "0"
},
"function": "emailTeste",
"resultset": [
{
"message": "E-mail Enviado com Sucesso.",
"status": "true"
}
],
"source": "smtp_pessoal",
"parameters": {
"saudacao": "ola, bom dia",
"nome": "John Doe"
}
},
"user": {
"name": "anderakooken",
"login": "anderakooken",
"email": "[email protected]"
}
}
}