{"id":19825535,"url":"https://github.com/anderakooken/szarca-api-java","last_synced_at":"2026-04-12T03:32:38.988Z","repository":{"id":189032176,"uuid":"678050277","full_name":"anderakooken/szarca-api-java","owner":"anderakooken","description":"API for Data Science apps (DW, Power BI, Python)","archived":false,"fork":false,"pushed_at":"2023-08-17T22:47:34.000Z","size":110,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-11T09:13:36.431Z","etag":null,"topics":["java","mongodb","oracle","springboot","sqlserver"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/anderakooken.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-08-13T14:21:12.000Z","updated_at":"2023-08-17T23:42:31.000Z","dependencies_parsed_at":null,"dependency_job_id":"bedf3cbf-42bd-4d1b-9dc6-70f7f8c5c39b","html_url":"https://github.com/anderakooken/szarca-api-java","commit_stats":null,"previous_names":["anderakooken/szarca-api-java"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anderakooken%2Fszarca-api-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anderakooken%2Fszarca-api-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anderakooken%2Fszarca-api-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anderakooken%2Fszarca-api-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anderakooken","download_url":"https://codeload.github.com/anderakooken/szarca-api-java/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241181435,"owners_count":19923439,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","mongodb","oracle","springboot","sqlserver"],"created_at":"2024-11-12T11:08:00.685Z","updated_at":"2025-12-31T01:09:05.044Z","avatar_url":"https://github.com/anderakooken.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Szarca API - Java / JSON\n\nAPI 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.\n\n## Ambiente\n\nO 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](https://insomnia.rest/download) ou [Postman](https://www.postman.com).\n\n## Estrutura do Software\n\n|Arquivo |                          |                         |\n|----------------|-------------------------------|-----------------------------|\n|`start.bat`        | `Inicializador para Windows`            |   Executar o arquivo para iniciar com a janela do CMD   |\n| `start.sh`       |`Inicializador para Linux`| |\n|`szarca-api-x.x.x.jar`| Executável | Funções do sistema\n|`szarca-api.db`| Banco de dados (SQLite)           | Tabelas (Usuários, Funções e Fontes de dados) |\n| `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|\n| `szarca-api.db.default-x.x.x.rar`       |`Banco de dados padrão`| Caso precise reinstalar o sistema|\n| `parameters.json`       |Parametros de configuração do sistema| |\n\n## Inicialização:\n\n### Windows e Linux\nPara 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`.\n\n### Docker / Kubernetes\nExecute o arquivo `szarca-api-x.x.x.jar --server.port=9032`.\n\n### Exemplo de requisição:\n\nPara 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`.\n\nHeader\n```\ncurl --location 'http://localhost:9032/' \\\n--header 'Content-Type: application/json' \\\n--data ''\n```\nRequisição\n```json\n{\n    \"logon\":\n        {   \n            \"user\":\"root\",\n            \"passwd\":\"root\"\n        },\n        \"function\":\"users()\",\n        \"param\":{}\n}\n```\n|Parâmetros|                          |                         |\n|----------------|-------------------------------|-----------------------------|\n|user / passwd| usuário e senha do software | Por padrão, root/root \n|function| Função que trará as informações da fonte de dados | Por padrão, o sistema já possui : `users()` -\u003e lista os usuários do sistema, `functions()` -\u003e lista as funções e `sources()` -\u003e lista as fontes de dados. Geralmente conexões com bancos de dados relacionais e não relacionais.\n|param | Filtros que serão executados na consulta | Deverá ser informado como JSONArray. Exemplo: `\"param\":{\"data\":\"00/00/0000\",\"cliente\":\"idcliente\"}`\n\n### Adicionando a primeira fonte de dados\n\nAs 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.\n\nHeader\n\n*Funções de gerenciamento `\"management\"` devem ser enviadas para `http://localhost:9032/admin/`*\n*Por padrão, o sistema já vem habilitado para receber solicitações de gerenciamento*\n```\ncurl --location 'http://localhost:9032/admin/' \\\n--header 'Content-Type: application/json' \\\n--data ''\n```\nRequisição\n```json\n{\n    \"management\": {\n        \"function\":\"addSource\",\n        \"param\":{\n            \"name\" : \"minhaConexao\",\n            \"database\" : \"mysql\",\n            \"host\" : \"127.0.0.1\",\n            \"port\" : \"3306\",\n            \"user\" : \"meuUsuarioMySQL\",\n            \"passwd\" : \"minhaSenhaMySQL\",\n            \"schema\" : \"meuSchemaMySQL\"\n        }\n    }\n}\n```\n|Parâmetros|                          |                         |\n|----------------|-------------------------------|-----------------------------|\n|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`.\n|name| Identificador único da fonte de dados (ID) |\n\nAo realizar o procedimento, deverá receber a seguinte resposta:\n```json\n{\n    \"system\": {\n        \"environment\": \"Java\",\n        \"author\": \"@anderakooken\",\n        \"name\": \"Szarca\",\n        \"version\": \"2.2.0\",\n        \"architecture\": \"json\"\n    },\n    \"return\": {\n        \"type\": \"true\"\n    }\n}\n```\nOnde 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.\n\nVamos consultar a lista de fontes de dados:\n\nHeader\n```\ncurl --location 'http://localhost:9032/' \\\n--header 'Content-Type: application/json' \\\n--data ''\n```\nRequisição\n\n```json\n{\n\t\"logon\": {\"user\":\"root\",\"passwd\":\"root\"},\n\t\"function\":\"sources()\", \"param\":{}\n}\n```\n\n#### Remoção da Fonte de Dados\n\nPara remover a fonte de dados, realize a requisição abaixo informando como `name` o identificador único da fonte (ID).\n\nHeader\n```\ncurl --location 'http://localhost:9032/admin/' \\\n--header 'Content-Type: application/json' \\\n--data ''\n```\nRequisição\n```json\n{\n    \"management\": {\n        \"function\":\"removeSource\",\n        \"param\":{\n            \"name\" : \"minhaConexao\"\n        }\n    }\n}\n```\n\n### Adicionando a primeira função\n\nAs 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](https://www.base64encode.org).\n\nVamos supor que tenhas a seguinte consulta no seu banco de dados.\n```sql\nSELECT nome, email, matricula FROM usuarios WHERE id_usuario = @idUsuario\n```\nO parâmetro `@idUsuario` terá o seu valor informado no momento das requisições da função.\n\nA consulta deverá ser convertida em Base64 para aceitação:\n```\nU0VMRUNUIG5vbWUsIGVtYWlsLCBtYXRyaWN1bGEgRlJPTSB1c3VhcmlvcyBXSEVSRSBpZF91c3VhcmlvID0gQGlkVXN1YXJpbw==\n```\n\nHeader\n```\ncurl --location 'http://localhost:9032/admin/' \\\n--header 'Content-Type: application/json' \\\n--data ''\n```\nRequisição\n```json\n{\n    \"management\": {\n        \"function\":\"addFunction\",\n        \"param\":{\n            \"name\" : \"meusUsuarios\",\n            \"source\" : \"minhaConexao\",\n            \"setCache\" : \"0\",\n            \"cacheDuration\" : \"0\",\n            \"queryText\" : \"U0VMRUNUIG5vbWUsIGVtYWlsLCBtYXRyaWN1bGEgRlJPTSB1c3VhcmlvcyBXSEVSRSBpZF91c3VhcmlvID0gQGlkVXN1YXJpbw==\",\n            \"queryTextParam\" : \"[\\\"idUsuario\\\"]\",\n            \"date\" : \"2022-01-15 00:00:00\",\n            \"status\" : \"1\",\n            \"forceColumns\" : \"0\",\n            \"queryColumnsText\" : \"\",\n            \"tableCollection\" : \"\",\n            \"fileQueryText\" : \"\",\n            \"plainText\" : \"\"\n            \n        }\n    }\n}\n```\n#### Parâmetros Obrigatórios\n\n|Parâmetros|                          |                         |\n|----------------|-------------------------------|-----------------------------|\n|name| Identificador único da função |\n|source| Identificador único da fonte de dados (ID) |\n|setCache| Se a função deve um arquivo na pasta cache, marque `1`, ou `0` consulta online a fonte de dados|\n|cacheDuration| Tempo de duração do arquivo cache. Em minutos. |\n|queryText| Consulta convertida em `Base64` |\n|queryTextParam| Parâmetro para filtrar a consulta | No exemplo, `@idUsuario` \u003c-\u003e `[\"idUsuario\"]`, filtrará apenas o usuário que será informado na requisição futura\n|date| Data de criação | Pode ser preenchida livremente no formato indicado `2000-01-01 00:00:00`\n|status| `1` para função em produção, `0` para desativar|\n|forceColumns| Altera o nome das colunas do retorno e força para um Alias informado |\n|tableCollection| Para uso em banco de dados não relacional| Exemplo: Coleções no MongoDB\n\nVamos consultar as funções:\n\nHeader\n```\ncurl --location 'http://localhost:9032/' \\\n--header 'Content-Type: application/json' \\\n--data ''\n```\nRequisição\n\n```json\n{\n\t\"logon\": {\"user\":\"root\",\"passwd\":\"root\"},\n\t\"function\":\"functions()\", \"param\":{}\n}\n```\n\n### Criando o primeiro usuário\n\nO 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.\n\nPara tal, execute a seguinte requisição:\n\nHeader\n```\ncurl --location 'http://localhost:9032/admin/' \\\n--header 'Content-Type: application/json' \\\n--data ''\n```\nRequisição\n```json\n{\n    \"management\": {\n        \"function\":\"addUser\",\n        \"param\":{\n            \"user\" : \"usuario\",\n             \"passwd\" : \"senha\",\n            \"email\" : \"usuario@dominio.com\",\n            \"roles\" : [\"minhaConexao\"]\n        }\n    }\n}\n```\n\n|Parâmetro|                          |                         |\n|----------------|-------------------------------|-----------------------------|\n|roles| Poderá ser múltiplo, caso existam varias fontes | `[\"minhaConexao\",\"fonte2\",\"fonte3\"]`\n\nVamos consultar os usuários:\n\nHeader\n```\ncurl --location 'http://localhost:9032/' \\\n--header 'Content-Type: application/json' \\\n--data ''\n```\nRequisição\n\n```json\n{\n\t\"logon\": {\"user\":\"root\",\"passwd\":\"root\"},\n\t\"function\":\"users()\", \"param\":{}\n}\n```\n\n#### Remoção da Permissão de Usuário a uma Fonte de Dados\n\nPara 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.\n\nHeader\n```\ncurl --location 'http://localhost:9032/admin/' \\\n--header 'Content-Type: application/json' \\\n--data ''\n```\nRequisição\n```json\n{\n    \"management\": {\n        \"function\":\"removeSecuritySource\",\n        \"param\":{\n            \"user\" : \"usuario\",\n            \"source\" : \"minhaConexao\"\n        }\n    }\n}\n```\n\n### Realizando a primeira requisição a API\n\nHeader\n```\ncurl --location 'http://localhost:9032/' \\\n--header 'Content-Type: application/json' \\\n--data ''\n```\nRequisição\n\n```json\n{\n    \"logon\":{\n\t\t\"user\":\"usuario\",\n\t\t\"passwd\":\"senha\"\n\t},\n\t\"function\":\"meusUsuarios\",\n\t\"param\":{\n\t\t\"idUsuario\" : \"15\"\n\t}\n}\n\n```\nExibição do conjunto de resultados\n\n```json\n\n{\n    \"system\": {\n        \"environment\": \"Java\",\n        \"author\": \"@anderakooken\",\n        \"name\": \"Szarca\",\n        \"version\": \"2.2.0\",\n        \"architecture\": \"json\"\n    },\n    \"return\": {\n        \"date\": \"2023-05-13 10:00:28\",\n        \"ipAddress\": \"0:0:0:0:0:0:0:1\",\n        \"type\": \"true\",\n        \"message\": {\n            \"cache\": {\n                \"definiteTime\": \"0\"\n            },\n            \"function\": \"meusUsuarios\",\n            \"resultset\": [],\n            \"source\": \"minhaConexao\",\n            \"parameters\": {}\n        },\n        \"user\": {\n            \"name\": \"usuario\",\n            \"login\": \"usuario\",\n            \"email\": \"usuario@dominio.com\"\n        }\n    }\n}\n\n```\n|Retorno|                          |                         |\n|----------------|-------------------------------|-----------------------------|\n|resultset| Conjunto de resultados em JSONArray  |\n\n\n### Bloquear o acesso do gerenciamento\n\nAntes 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.\n\n### Usando o cache\n\nPara 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.\n\n### Habilitar ALIAS\n\nO ALIAS funciona basicamente igual a linguagem SQL, onde trocamos o nome do campo real por um apelido, exemplo:\n\n```sql \nSELECT u.mat as Matricula, u.nome as NomeUsuario from Usuario \n``` \n\nAo alterar o valor do `forceColumns` para `1`, o sistema solicitará que o objeto`queryColumnsText` contenha os valores a serem convertidos.\n\n```json\n{\"queryColumnsText\" : \"[{\\\"mat\\\":\\\"Matricula\\\"},{\\\"nome\":\"NomeUsuario\\\"}]\"}\n```\n* Importante, uma vez habilitado o ALIAS, todos os campos contidos na consulta deverão ser informados na `queryColumnsText` ou não haverá resposta na requisição.\n\n### NoSQL - Bancos Não Relacionais\n\nAtualmente 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.\n\n### Uso de E-mails\n\nPara envio de e-mails, será necessário incluir um fonte de dados:\n\nHeader\n```\ncurl --location 'http://localhost:9032/admin/' \\\n--header 'Content-Type: application/json' \\\n--data ''\n```\nRequisição\n```json\n{\n    \"management\": {\n        \"function\":\"addSource\",\n        \"param\":{\n            \"name\" : \"smtp_pessoal\",\n            \"database\" : \"smtp\",\n            \"host\" : \"mail.meudominio.com\",\n            \"port\" : \"587\",\n            \"user\" : \"eu@meudominio.com\",\n            \"passwd\" : \"U0VMRUNUIG5v==\",\n            \"schema\" : \"Nome/Sobrenome\"\n        }\n    }\n}\n```\n|Parâmetros|                          |                         |\n|----------------|-------------------------------|-----------------------------|\n|name| Identificador único da fonte de dados (ID) |\n|database| Obrigatoriamente com o valor `smtp`| Informa ao sistema para usar protocolo de envio\n|host| IP do servidor para envio de e-mails |\n|schema| Nome que será exibido nos e-mails enviados|\n\nA senha do e-mail deverá ser convertida em Base64 para aceitação:\n```\nU0VMRUNUIG5v==\n```\n#### Instruções\n\nAs 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](https://www.base64encode.org).\n\nVamos colocar uma mensagem de teste.\n```\n@saudacao, meu nome é @nome. Este e-mail é apenas um teste.\n```\nOs parâmetros `@saudacao` e `@nome` terão os seus valores informados no momento da requisição da função.\n\nA consulta deverá ser convertida em Base64 para aceitação:\n```\nQHNhdWRhY2FvLCBtZXUgbm9tZSDDqSBAbm9tZS4gRXN0ZSBlLW1haWwgw6kgYXBlbmFzIHVtIHRlc3RlLg==\n```\n\n#### Função para Envio de E-mail\n\nHeader\n```\ncurl --location 'http://localhost:9032/admin/' \\\n--header 'Content-Type: application/json' \\\n--data ''\n```\nRequisição\n```json\n{\n    \"management\": {\n        \"function\":\"addFunction\",\n        \"param\":{\n            \"name\" : \"emailTeste\",\n            \"source\" : \"smtp_pessoal\",\n            \"setCache\" : \"0\",\n            \"cacheDuration\" : \"0\",\n            \"queryText\" : \"QHNhdWRhY2FvLCBtZXUgbm9tZSDDqSBAbm9tZS4gRXN0ZSBlLW1haWwgw6kgYXBlbmFzIHVtIHRlc3RlLg==\",\n            \"queryTextParam\" : \"[\\\"saudacao\\\",\\\"nome\\\"]\",\n            \"date\" : \"2022-01-15 00:00:00\",\n            \"status\" : \"1\",\n            \"forceColumns\" : \"0\",\n            \"queryColumnsText\" : \"teste1@email.com,teste2@mail.com\",\n            \"tableCollection\" : \"\",\n            \"fileQueryText\" : \"\",\n            \"plainText\" : \"Assunto do E-mail\"\n            \n        }\n    }\n}\n```\n#### Parâmetros Obrigatórios\n\n|Parâmetros|                     |                         |\n|-------------------|-------------------------------|-----------------------------|\n|name| Identificador único da função |\n|source| Identificador único da fonte de dados (ID) |\n|queryText| Corpo do E-mail convertido em `Base64` |\n|queryTextParam| Parâmetro para filtrar a consulta | No exemplo, `@saudacao` \u003c-\u003e `[\"saudacao\"]`, filtrará apenas o usuário que será informado na requisição futura |\n|queryColumnsText | E-mail dos destinatários | Podem ser vários e-mails separados por `,`. |\n|plainText | Titulo/Assunto do E-mail |\n\n#### Restrições no uso do `queryColumnsText` no E-mail\n\nO 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.\n\n#### Chamada de Função - E-mail\n\nHeader\n```\ncurl --location 'http://localhost:9032/' \\\n--header 'Content-Type: application/json' \\\n--data ''\n```\nRequisição\n```json\n{\n    \"logon\":{\n\t\t\"user\":\"seu_usuario\",\n\t\t\"passwd\":\"sua_senha\"\n\t},\n\t\"function\":\"emailTeste\",\n\t\"param\":{\n\t\t\"saudacao\" : \"ola, bom dia.\",\n        \"nome\" : \"John Doe\"\n\t}\n}\n```\nExibição do conjunto de resultados\n\n```json\n{\n    \"system\": {\n        \"environment\": \"Java\",\n        \"administrator\": \"@anderakooken\",\n        \"name\": \"Szarca\",\n        \"version\": \"2.3.0\",\n        \"architecture\": \"json\"\n    },\n    \"return\": {\n        \"date\": \"2023-05-17 14:02:58\",\n        \"ipAddress\": \"0:0:0:0:0:0:0:1\",\n        \"type\": \"true\",\n        \"message\": {\n            \"cache\": {\n                \"definiteTime\": \"0\"\n            },\n            \"function\": \"emailTeste\",\n            \"resultset\": [\n                {\n                    \"message\": \"E-mail Enviado com Sucesso.\",\n                    \"status\": \"true\"\n                }\n            ],\n            \"source\": \"smtp_pessoal\",\n            \"parameters\": {\n                \"saudacao\": \"ola, bom dia\",\n                \"nome\": \"John Doe\"\n            }\n        },\n        \"user\": {\n            \"name\": \"anderakooken\",\n            \"login\": \"anderakooken\",\n            \"email\": \"you@mail.com\"\n        }\n    }\n}\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanderakooken%2Fszarca-api-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanderakooken%2Fszarca-api-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanderakooken%2Fszarca-api-java/lists"}