Guia de Uso do DBAPI

Apresentação do Produto

• O DBAPI é uma ferramenta de baixo código voltada para desenvolvedores de data warehouses. Basta escrever SQL na interface e configurar os parâmetros para gerar automaticamente interfaces HTTP. Ele ajuda os programadores a desenvolver rapidamente interfaces de dados no backend, sendo especialmente adequado para o desenvolvimento de APIs de backend utilizadas em relatórios de BI e painéis de visualização de dados.

• O DBAPI atua como um centro de gestão de todas as interfaces de dados da empresa, funcionando como uma plataforma para a administração dos serviços de dados oferecidos externamente. Oferece funcionalidades de criação e publicação dinâmica de interfaces de dados, gerenciamento unificado das mesmas e capacidade de monitoramento e controle dos clientes que acessam essas interfaces, permitindo acompanhar as chamadas feitas pelos clientes e gerenciar seus respectivos níveis de permissão.

Endereço para Experimentação

Características Principais

• ✅ Pronto para uso: Não requer programação e não depende de outros softwares (no modo standalone, apenas o ambiente de execução Java é necessário).
• ✅ Implantação leve: O consumo de recursos é extremamente reduzido; um servidor com 2 núcleos e 4 GB de memória já garante operação estável.
• ✅ Suporte multiplataforma: Compatível com modos standalone e cluster, suportando Windows, Linux e macOS.
• ✅ Configuração dinâmica: Permite criação e modificação dinâmicas de APIs e fontes de dados, com implantação quente sem interrupções.
• ✅ Controle de permissões: Oferece gerenciamento de permissões ao nível de API, incluindo listas brancas e negras de IPs.
• ✅ Ampla compatibilidade: Suporta todos os bancos de dados relacionais que seguem o protocolo JDBC (MySQL, SQL Server, PostgreSQL, Oracle, Hive, Dameng, Kingbase, Doris, OceanBase, GaussDB, entre outros).
• ✅ SQL dinâmico: Compatível com SQL dinâmico no estilo MyBatis, proporcionando edição, execução e depuração integradas.
• ✅ Suporte completo: Aceita instruções SELECT, INSERT, UPDATE, DELETE e chamadas a procedimentos armazenados.
• ✅ Gerenciamento de transações: Permite a execução de múltiplas instruções SQL, com controle flexível sobre a abertura e o fechamento de transações.
• ✅ Extensões por plugins: Oferece diversos mecanismos de extensão, como cache, transformação de dados, alertas de falha e processamento de parâmetros.
• ✅ Migração facilitada: Permite importação e exportação de configurações de APIs, facilitando a migração entre ambientes de teste e produção.
• ✅ Processamento de parâmetros: Suporta passagem de parâmetros via API e parâmetros JSON aninhados complexos, além de validação de entradas.
• ✅ Monitoramento e estatísticas: Fornece consulta de registros de chamadas de API e geração de estatísticas de acesso.
• ✅ Controle de tráfego: Implementa mecanismos de limitação de taxa para APIs.
• ✅ Orquestração de fluxos: Permite orquestração avançada de APIs.
• ✅ Integração aberta: Disponibiliza a interface OpenAPI, facilitando a integração com outros sistemas.

Conceitos Fundamentais

Executor

O executor é uma abstração responsável pela execução da lógica de negócio da API. Atualmente, são suportados vários tipos:

Tipo de Executor	Descrição
Executor SQL	Executa instruções SQL no banco de dados e retorna os resultados
Executor Elasticsearch	Executa instruções DSL do Elasticsearch e retorna os resultados
Executor HTTP	Funciona como cliente HTTP, encaminhando requisições e retornando os resultados

[!NOTA] Na versão pessoal, apenas o executor SQL está disponível.

Grupo de APIs

Utilizado para organizar e categorizar APIs, agrupando aquelas relacionadas a um mesmo domínio de negócio, facilitando a manutenção e a localização.

Cliente

Refere-se aos aplicativos que fazem chamadas às APIs da plataforma, como aplicações em Python, Java, etc. Cada cliente possui um identificador único clientId e uma chave secreta secret, criados e atribuídos pelo administrador do sistema, que também define as permissões de acesso à API.

Introdução Rápida

Login no Sistema

Utilize as credenciais padrão admin/admin para efetuar o login.

Configuração da Fonte de Dados

1. Acesse a página de gerenciamento de fontes de dados e clique em "Criar Fonte de Dados".

   

2. Preencha as informações de conexão ao banco de dados e salve.

   

3. Após salvar, retorne à página de fontes de dados, onde poderá editar ou excluir a nova fonte criada.

   

[!AVISO] Observações Importantes:

• É compatível com todos os bancos de dados que suportam o protocolo JDBC.
• Ao utilizar outros tipos de banco de dados ou o Oracle, é necessário informar manualmente a classe do driver JDBC e colocar o respectivo arquivo JAR no diretório extlib ou lib, reiniciando o serviço após a alteração (no modo cluster, essa operação deve ser realizada em todos os nós).
• O diretório lib já contém drivers para MySQL, SQL Server, PostgreSQL e ClickHouse; caso a versão seja incompatível, substitua manualmente.
• Recomenda-se colocar seus próprios arquivos JAR de driver no diretório extlib para facilitar a gestão centralizada.

Processo de Criação de uma API

1. Criação de um Grupo de APIs

• Acesse a página de gerenciamento de APIs e clique no botão "Criar Grupo de APIs" no lado esquerdo.

  

• No pop-up, insira o nome do grupo e salve.

  

• Após salvar, observe que um novo grupo apareceu no menu esquerdo; clique no botão "Mais" ao lado do grupo para editar ou excluir.

  

2. Criação de uma API

• Dentro do grupo desejado, clique no botão "Criar API" para acessar a página de configuração.

  

• Clique em "Informações Básicas" e preencha os dados fundamentais da API.

  

  Permissões de Acesso: As APIs públicas podem ser acessadas diretamente, enquanto as privadas exigem que o cliente solicite um token antes de poder acessá-las (por enquanto, selecionaremos a opção pública para facilitar os testes).

  Rota: Pode ser configurada com múltiplos níveis hierárquicos, como /a/b/c, /a/b/c/d.

  Content-Type: Para APIs do tipo application/x-www-form-urlencoded, é necessário definir os parâmetros; já para APIs do tipo application/json, é preciso fornecer um exemplo de parâmetro JSON.

• Em seguida, selecione o executor e preencha as informações correspondentes.

  

  Escrita de SQL: Utilize a sintaxe dinâmica do MyBatis (sem necessidade de tags externas <select>, <insert>, <delete> ou <update>). Os parâmetros devem ser indicados por #{} ou ${}, e a sintaxe específica pode ser consultada no Documento de Sintaxe Dinâmica do SQL.

  Controle de Transações: Por padrão, as transações estão desativadas. Para instruções INSERT/UPDATE/DELETE, recomenda-se habilitar a transação; assim, caso ocorra falha na execução de alguma instrução, a transação será revertida. Se houver várias instruções dentro da API, ative a transação para que todas sejam executadas em um único bloco.

  Observação Importante: Para bancos de dados como o HIVE, que não suportam transações, evite habilitar essa funcionalidade, pois isso resultará em erro.

  Transformação de Dados: Caso seja necessário realizar alguma transformação nos dados, informe o nome da classe Java do plugin correspondente; se não for especificado, a transformação não será realizada. Se o plugin precisar de parâmetros, indique-os aqui. Consulte o Documento de Plugins para mais detalhes.

  Suporte a Múltiplas Instruções SQL: Clique no botão "Adicionar" para abrir uma nova janela de escrita de SQL. Uma única API pode executar diversas instruções, e os resultados finais serão agregados e retornados juntos — por exemplo, em consultas paginadas, onde é necessário obter tanto os detalhes quanto o total de registros. Cada janela de escrita de SQL permite apenas uma instrução.

  

[!DICA] Se um único executor contiver múltiplas instruções SQL, cada uma delas terá sua própria configuração de plugin de transformação de dados. Lembre-se de que os plugins de transformação sempre atuam sobre os resultados de uma única instrução SQL.

• Clique no botão de maximização da janela para acessar a interface de depuração do SQL.

  

• Execute o SQL clicando no botão "Executar". Se houver parâmetros, configure-os conforme necessário.

  

• Clique no botão "Plugin Global" para preencher as informações do plugin global.

  

  Cache: Caso deseje implementar cache de dados, informe o nome da classe Java do plugin de cache; se não for especificado, o cache não será ativado. Se o plugin precisar de parâmetros, indique-os aqui.

  Alerta: Se for necessário emitir um alerta em caso de falha na execução da API, informe o nome da classe Java do plugin de alerta; se não for especificado, o alerta não será ativado. Se o plugin precisar de parâmetros, indique-os aqui.

  Transformação Global de Dados: Caso seja necessário realizar alguma transformação nos dados, informe o nome da classe Java do plugin correspondente; se não for especificado, a transformação não será realizada. Se o plugin precisar de parâmetros, indique-os aqui.

  Processamento de Parâmetros: Se for necessário processar parâmetros, informe o nome da classe Java do plugin correspondente; se não for especificado, o processamento não será realizado. Se o plugin precisar de parâmetros, indique-os aqui.

  Consulte o Documento de Plugins para mais detalhes.

• Clique em "Salvar" para concluir a criação da API. Em seguida, volte à lista de APIs clicando no menu correspondente.

3. Publicação da API

• Clique no botão "Mais" ao lado da API e encontre o botão "Publicar". Clique nele para disponibilizar a API.

  

• Clique novamente no botão "Mais" ao lado da API e encontre o botão "Testar Requisição". Clique nele para acessar a página de teste.

  

• Clique no botão "Enviar Requisição" para enviar a solicitação. Se houver parâmetros, preencha-os conforme necessário.

  

Gerenciamento de Clientes

• Acesse o menu de clientes e clique no botão "Criar Cliente".

  

• Preencha as informações do cliente e salve.

  

Ao criar um cliente, serão gerados um clientId e uma secret. O administrador do sistema deverá informar esses valores ao cliente (ou seja, ao solicitante da API).

O cliente utiliza seu próprio clientId e secret para acessar a rota http://192.168.xx.xx:8520/token/generate?clientId=xxx&secret=xxx, onde pode obter dinamicamente um token. Somente com esse token o cliente poderá acessar APIs privadas (desde que o administrador tenha concedido autorização para tal).

É imprescindível definir um tempo de expiração para o token ao criar o cliente; dessa forma, cada vez que o cliente solicitar um novo token, ele receberá um valor com prazo de validade específico. Enquanto estiver dentro desse período, o token anterior continuará válido para acessar a API. Caso contrário, será necessário solicitar um novo token.

[!DICA] Se desejar que o token permaneça válido indefinidamente, defina um tempo de expiração muito longo, como 100 anos.

• Clique no botão "Autorizar" para conceder permissões de acesso à API ao cliente.

  

• Selecione o grupo ao qual deseja conceder permissões e salve.

  

Instruções de Uso do Token

• Interface para Solicitação de Token:

  http://192.168.xx.xx:8520/token/generate?clientId=xxx&secret=xxx

• Ao solicitar acesso a uma API privada, é necessário incluir o valor do token no campo Authorization do cabeçalho para conseguir acessar com sucesso. (Para APIs públicas, não é necessário definir o cabeçalho.)

• Exemplo de Chamada em Python:

import requests
headers = {"Authorization": "5ad0dcb4eb03d3b0b7e4b82ae0ba433f"}
re = requests.post("http://127.0.0.1:8520/api/userById", {"idList": [1, 2]}, headers=headers)
print(re.text)

• Altere a API anterior para torná-la privada e, em seguida, clique no botão "Testar Requisição".

  

• Nesse momento, ao clicar no botão "Enviar Requisição", perceberá que a API não está acessível.

  

• Insira o clientId e o secret, clique no botão para acessar a API e obtenha o token.

  

• Coloque o token no campo Authorization do cabeçalho e clique no botão "Enviar Requisição"; agora a API estará acessível.

  

Configuração do Firewall de IP

Ativar o firewall permite bloquear determinados IPs.

Monitoramento

O DBAPI pode ser utilizado apenas com base em um metadado (postgresql/mysql/sqlite); porém, se você também desejar utilizar os recursos de monitoramento disponíveis na interface (como registros de chamadas de API, volume de acessos, taxa de sucesso, entre outros), será necessário contar com um banco de dados de logs adicional (que deverá ser configurado pelo próprio usuário) para armazenar os registros de acesso às APIs. Recomenda-se o uso de clickhouse/mysql/postgresql/doris; é claro que você também pode optar por outros bancos de dados relacionais.

Atualmente, scripts de inicialização dos bancos de dados de logs para clickhouse/mysql/postgresql estão disponíveis no diretório sql.

[!NOTA] Se você não necessita do recurso de monitoramento, não é preciso configurar um banco de dados de logs; basta definir access.log.writer=null no arquivo conf/application.properties. (Essa é a configuração padrão.)

Formas de coleta de logs

1. Coleta por arquivo: Por padrão, o DBAPI grava os registros de acesso às APIs em um arquivo no disco, logs/dbapi-access.log. O usuário pode utilizar ferramentas como datax, flume ou outras para coletar esses logs e enviá-los ao banco de dados de logs.

2. Conexão direta ao banco de dados: Caso seja configurado access.log.writer=db no arquivo conf/application.properties, o DBAPI escreverá os registros de acesso às APIs diretamente e de forma assíncrona no banco de dados de logs. Essa abordagem é indicada para cenários com volumes relativamente baixos de logs.

3. Buffering via Kafka: Ao configurar access.log.writer=kafka no arquivo conf/application.properties, o DBAPI enviará os registros de acesso às APIs para o Kafka. Nesse caso, cabe ao usuário coletar os logs do Kafka e persisti‑los no banco de dados de logs. Essa solução é recomendada para ambientes com grandes volumes de logs, pois permite que o Kafka atue como buffer de dados.

[!NOTA] Observe que, nessa modalidade, é necessário informar o endereço do Kafka no arquivo conf/application.properties.

Além disso, o DBAPI já inclui uma ferramenta para consumir os logs do Kafka e gravá‑los no banco de dados de logs; utilize o script bin/dbapi-log-kafka2db.sh.

Resumo do Monitoramento

• Clicando no menu de Monitoramento, é possível visualizar os registros das chamadas de API.

  

Visualização dos Registros de Chamadas de API

• Ao clicar na aba Detalhes, é possível realizar buscas nos registros de chamadas de API.

  

Outras Funcionalidades

Exportação de Documentação de API

• No menu da API, clique no botão de ferramentas e, em seguida, no botão de exportação da documentação da API.

  

Sistema de Plugins

O DBAPI oferece cinco categorias de mecanismos de plugins. Você pode baixar plugins no Mercado de Plugins. Caso deseje desenvolver seus próprios plugins, consulte a Documentação de Plugins.

Plugin de Cache

• Permite armazenar em cache os resultados dos executores; por exemplo, no executor SQL, os resultados de consultas podem ser armazenados em cache, evitando consultas frequentes ao banco de dados e reduzindo a carga sobre este.
• A lógica de cache deve ser implementada pelo próprio usuário, podendo utilizar ehcache, redis, mongodb, entre outros.
• Quando não for encontrado nenhum dado no cache, o executor será acionado e o resultado será então armazenado em cache.

[!DICA] Situação com múltiplas instruções SQL No caso de um executor SQL que contenha várias instruções, o plugin de cache encapsula os resultados de todas as instruções — se houver plugins de transformação configurados para uma única instrução, estes serão aplicados primeiro — e armazena o conjunto como um todo em cache.

Plugin de Alerta

• Quando ocorre um erro interno na API, o plugin de alerta pode enviar notificações de erro por e-mail, SMS, DingTalk, Feishu, WeChat Corporativo, entre outros.
• A lógica de geração de alertas deve ser definida pelo próprio usuário.

Plugin de Transformação de Dados

• Às vezes, o SQL não consegue obter diretamente o formato de dados desejado; nesses casos, é útil recorrer a plugins de transformação de dados, permitindo que o usuário escreva sua própria lógica de manipulação e conversão dos dados.
• Por exemplo, é possível aplicar técnicas de ofuscação ou pseudonimização a números de telefone ou números de cartão bancário obtidos nas consultas SQL.

[!DICA] Situação com múltiplas instruções SQL Para executores SQL que contêm várias instruções, cada instrução terá seu próprio plugin de transformação de dados configurado; esse tipo de plugin sempre opera sobre os resultados individuais de cada consulta SQL.

Plugin Global de Transformação de Dados

• Os dados retornados pela API têm, por padrão, o formato {success: true, msg: xxx, data: xxx}.
• Em alguns casos, é necessário adaptar o formato da resposta; por exemplo, o framework de low-code front-end AMIS exige que as respostas das APIs incluam um campo status. Nesses casos, o plugin global de transformação de dados pode ser utilizado para ajustar o formato de toda a resposta da API.

[!NOTA] Diferença entre plugin de transformação de dados e plugin global de transformação de dados O plugin de transformação de dados atua sobre os resultados do executor (por exemplo, transforma os resultados de uma consulta SQL realizada pelo executor), enquanto o plugin global de transformação de dados realiza a conversão sobre a resposta completa da API.

Plugin de Processamento de Parâmetros

• Permite ao usuário realizar processamentos personalizados nos parâmetros de requisição.
• Por exemplo, converter todos os valores dos parâmetros para maiúsculas.
• Ou ainda, quando a API recebe parâmetros criptografados, o usuário pode implementar uma lógica personalizada para descriptografar esses valores.

[!NOTA] Nota sobre suporte por versão O plugin de processamento de parâmetros passou a ser suportado a partir da versão pessoal 4.0.16 e da versão corporativa 4.1.10.

Considerações Finais

Suporte a Fontes de Dados

• Caso deseje utilizar Oracle ou outras fontes de dados, é necessário colocar manualmente o respectivo driver JDBC no diretório extlib ou no diretório lib após a implantação do DBAPI (em clusters, cada nó precisa receber o jar correspondente).
• Recomenda-se armazenar os drivers no diretório extlib para facilitar a gestão unificada.

Normas de Escrita de SQL

• Assim como na sintaxe dinâmica de SQL do MyBatis, também são suportados os parâmetros #{} e ${}; consulte a documentação sobre sintaxe dinâmica de SQL. Não é necessário incluir tags externas como <select> ou <update>; basta escrever o conteúdo SQL diretamente.
• Lembre‑se de que, assim como no MyBatis, os sinais de menor que (<) devem ser representados como < e não como <.