DBAPI 사용 가이드

제품 소개

DBAPI는 데이터 웨어하우스 개발자를 위한 로우코드 도구로, 페이지에서 SQL을 작성하고 파라미터를 설정하는 것만으로 HTTP 인터페이스를 자동 생성합니다. 이는 프로그래머가 백엔드 데이터 인터페이스를 신속하게 개발할 수 있도록 지원하며, 특히 BI 보고서 및 데이터 시각화 대시보드의 백엔드 인터페이스 개발에 적합합니다.
DBAPI는 기업 전체 데이터 인터페이스의 관리 센터로서, 외부에 데이터 서비스를 제공하는 기업용 관리 플랫폼입니다. 데이터 인터페이스의 동적 생성 및 배포 기능을 제공하며, 인터페이스를 통합적으로 관리하고 클라이언트의 인터페이스 호출을 모니터링하며, 클라이언트의 접근 권한을 제어할 수 있는 기능도 갖추고 있습니다.

핵심 특징

✅ 즉시 사용 가능: 프로그래밍 없이 다른 소프트웨어에 의존하지 않음(단독 실행 모드에서는 Java 실행 환경만 필요)
✅ 경량 배포: 리소스 소모가 매우 적어 2코어 4GB 서버에서도 안정적으로 작동
✅ 다양한 플랫폼 지원: 단독 및 클러스터 모드를 지원하며 Windows, Linux, macOS를 모두 지원
✅ 동적 구성: API와 데이터 소스의 동적 생성 및 수정을 지원하며, 핫 디플로이에도 무감지
✅ 권한 관리: API 수준의 접근 권한 관리를 제공하며 IP 화이트리스트/블랙리스트 기능도 지원
✅ 광범위한 호환성: 모든 JDBC 기반 관계형 데이터베이스(MySQL, SQL Server, PostgreSQL, Oracle, Hive, 다몽, 런다진창, Doris, OceanBase, GaussDB 등)를 지원
✅ 동적 SQL: MyBatis 스타일의 동적 SQL을 지원하며, SQL 편집·실행·디버깅을 일체화된 기능으로 제공
✅ 전면적인 지원: Select/Insert/Update/Delete 문과 저장 프로시저 호출까지 지원
✅ 트랜잭션 관리: 여러 SQL 실행을 지원하며 트랜잭션 스위치를 유연하게 제어 가능
✅ 플러그인 확장성: 캐싱, 데이터 변환, 실패 알림, 파라미터 처리 등 다양한 플러그인 메커니즘 제공
✅ 편리한 마이그레이션: API 구성의 임포트·엑스포트 기능을 통해 테스트 환경에서 생산 환경으로의 이전이 용이
✅ 파라미터 처리: 인터페이스 전달 파라미터와 복잡한 중첩 JSON 파라미터를 지원하며, 파라미터 검증 기능도 제공
✅ 모니터링 및 통계: 인터페이스 호출 기록 조회와 접속 정보 통계 기능 제공
✅ 트래픽 제어: API 스로틀링 메커니즘 지원
✅ 프로세스 오케스트레이션: 복잡한 API 오케스트레이션 기능 지원
✅ 개방형 통합: OpenAPI 인터페이스를 제공하여 타 시스템과의 연동이 용이

기본 개념

엑섹터

엑섹터는 API 비즈니스 로직의 실행 추상화로, 현재 다음과 같은 여러 유형을 지원합니다:

엑섹터 유형	기능 설명
SQL 엑섹터	데이터베이스에서 SQL 문장을 실행하고 결과를 반환
Elasticsearch 엑섹터	Elasticsearch DSL 문장을 실행하고 결과를 반환
HTTP 엑섹터	HTTP 클라이언트로써 HTTP 요청을 전달하여 결과를 받아 반환

NOTE

개인용 버전에서는 현재 SQL 엑섹터만 지원됩니다.

API 그룹

API를 분류하여 관리하기 위한 기능으로, 관련된 API들을 하나의 그룹으로 묶어 유지보수와 검색을 용이하게 합니다.

클라이언트

플랫폼의 API를 호출하는 애플리케이션을 의미하며, Python, Java 등의 언어로 구현됩니다. 각 클라이언트에는 고유한 식별자 clientId와 키 secret이 있으며, 시스템 관리자가 생성하여 API 접근 권한을 부여합니다.

빠른 시작

시스템 로그인

기본 계정 및 비밀번호 admin/admin을 사용하여 시스템에 로그인합니다.

로그인 화면

데이터 소스 구성

데이터 소스 관리 페이지로 이동한 후, "데이터 소스 생성" 버튼을 클릭합니다.
데이터베이스 연결 정보를 입력하고 저장합니다.
저장 후 데이터 소스 페이지로 돌아가 새로 생성한 데이터 소스를 편집하거나 삭제할 수 있습니다.

중요 사항

JDBC 프로토콜을 지원하는 모든 데이터베이스를 지원합니다.
기타 유형의 데이터베이스나 Oracle을 사용할 경우, JDBC 드라이버 클래스명을 수동으로 입력하고 해당 JDBC 드라이버 JAR 파일을 extlib 또는 lib 디렉토리에 넣은 후 서비스를 재시작해야 합니다(클러스터 모드에서는 모든 노드에서 작업 필요).
lib 디렉토리에는 MySQL/SQL Server/PostgreSQL/ClickHouse 드라이버가 이미 포함되어 있으므로, 버전이 맞지 않을 경우 수동으로 교체해 주시기 바랍니다.
자신의 드라이버 JAR 파일은 extlib 디렉토리에 넣어 통합 관리하는 것을 권장합니다.

API 생성 절차

1. API 그룹 생성

API 관리 페이지로 이동한 후, 왼쪽의 "API 그룹 생성" 버튼을 클릭합니다.
팝업 창에서 그룹 이름을 입력하고 저장합니다.
저장 후 왼쪽에 새로운 그룹이 생성되었으며, 그룹 위의 더 보기 버튼을 클릭하면 그룹을 편집하거나 삭제할 수 있습니다.

2. API 생성

대상 그룹에서 "API 생성" 버튼을 클릭하여 설정 페이지로 이동합니다.
기본 정보 탭을 클릭하여 API 기본 정보를 입력합니다.
접근 권한: 공개 인터페이스는 직접 접근 가능하며, 비공개 인터페이스는 클라이언트가 토큰을 신청해야만 접근 가능합니다(이후 테스트를 위해 우선 공개 인터페이스를 선택).
경로: /a/b/c, /a/b/c/d 등 원하는 만큼의 다중 레벨 경로를 설정할 수 있습니다.
Content-Type: application/x-www-form-urlencoded 타입의 API라면 파라미터를 설정해야 하며, application/json 타입의 API라면 JSON 파라미터 예제를 입력해야 합니다.
엑섹터 탭을 클릭하여 엑섹터 정보를 입력합니다.
SQL 작성: MyBatis 동적 SQL 문법을 사용하며, 외부 <select> <insert> <delete> <update> 태그는 필요 없습니다. 파라미터는 #{} 또는 ${}로 표기하며, 동적 SQL 문법은 동적 SQL 문법 문서를 참고하시기 바랍니다.
트랜잭션 제어: 기본적으로 트랜잭션은 비활성화되어 있습니다. insert/update/delete 문장이라면 트랜잭션을 활성화하는 것이 좋습니다. 트랜잭션을 활성화하면 SQL 실행에 실패하더라도 트랜잭션이 롤백됩니다. API 내에 여러 SQL이 포함되어 있다면, 트랜잭션을 활성화하여 모든 SQL이 하나의 트랜잭션 안에서 실행되도록 설정하세요.
주의 사항: HIVE 등 트랜잭션을 지원하지 않는 데이터베이스에서는 트랜잭션을 활성화하지 마시기 바랍니다. 그렇지 않으면 오류가 발생할 수 있습니다.
데이터 변환: 데이터 변환이 필요한 경우, 데이터 변환 플러그인의 Java 클래스명을 입력합니다. 입력하지 않으면 변환되지 않습니다. 플러그인이 파라미터를 요구한다면 파라미터를 함께 입력하세요. 자세한 내용은 플러그인 문서를 참조하시기 바랍니다.
다중 SQL 지원: 추가 버튼을 클릭하면 SQL 작성 창이 추가되며, 하나의 API 내에서 여러 SQL을 실행할 수 있습니다. 최종 결과는 여러 개의 데이터를 하나로 묶어 반환되며, 예를 들어 페이징 쿼리처럼 상세 조회와 총 건수 조회를 동시에 수행할 수 있습니다. 한 개의 SQL 작성 창에는 반드시 하나의 SQL만 작성할 수 있습니다.

TIP

하나의 엑섹터에 여러 SQL이 포함되어 있다면, 각 SQL마다 별도의 데이터 변환 플러그인 설정이 필요합니다. 데이터 변환 플러그인은 항상 단일 SQL 결과를 대상으로 변환을 수행합니다.

창을 최대화 버튼을 클릭하여 SQL 디버깅 화면으로 이동합니다.
SQL 실행 버튼을 클릭하여 SQL을 실행할 수 있으며, SQL에 파라미터가 포함되어 있다면 파라미터를 설정해야 합니다.
글로벌 플러그인 탭을 클릭하여 글로벌 플러그인 정보를 입력합니다.
캐싱: 데이터 캐싱이 필요한 경우, 캐싱 플러그인의 Java 클래스명을 입력합니다. 입력하지 않으면 캐싱이 활성화되지 않습니다. 플러그인이 파라미터를 요구한다면 파라미터를 함께 입력하세요.
알림: API 실행에 실패했을 때 알림이 필요한 경우, 알림 플러그인의 Java 클래스명을 입력합니다. 입력하지 않으면 실패 알림이 활성화되지 않습니다. 플러그인이 파라미터를 요구한다면 파라미터를 함께 입력하세요.
전체 데이터 변환: 데이터 변환이 필요한 경우, 데이터 변환 플러그인의 Java 클래스명을 입력합니다. 입력하지 않으면 변환이 이루어지지 않습니다. 플러그인이 파라미터를 요구한다면 파라미터를 함께 입력하세요.
파라미터 처리: 파라미터 처리가 필요한 경우, 파라미터 처리 플러그인의 Java 클래스명을 입력합니다. 입력하지 않으면 처리가 이루어지지 않습니다. 플러그인이 파라미터를 요구한다면 파라미터를 함께 입력하세요.
자세한 내용은 플러그인 문서를 참조하시기 바랍니다.
저장 버튼을 클릭하면 API가 생성되며, API 메뉴를 클릭하면 API 목록 페이지로 돌아갑니다.

3. API 배포

API 위의 더 보기 버튼을 클릭하면 온라인 버튼이 나타나며, 이를 클릭하여 API를 배포합니다.
API 위의 더 보기 버튼을 클릭하면 요청 테스트 버튼이 나타나며, 이를 클릭하여 요청 테스트 페이지로 이동합니다.
요청 보내기 버튼을 클릭하여 요청을 발송할 수 있으며, 파라미터가 필요한 경우 파라미터를 입력합니다.

클라이언트 관리

클라이언트 메뉴를 클릭한 후, "클라이언트 생성" 버튼을 클릭합니다.
클라이언트 정보를 입력하고 저장합니다.

클라이언트를 생성하면 clientId와 secret이 생성되며, 시스템 관리자는 이 clientId와 secret을 클라이언트(API 호출자)에게 알려야 합니다.

클라이언트는 자신의 clientId와 secret을 사용하여 http://192.168.xx.xx:8520/token/generate?clientId=xxx&secret=xxx 인터페이스를 호출함으로써 동적으로 토큰을 획득할 수 있습니다. 이후 클라이언트는 이 토큰을 사용하여 비공개 API에 접근할 수 있습니다(단, 시스템 관리자가 해당 클라이언트에게 이 비공개 API에 대한 접근 권한을 부여한 경우에 한함).

클라이언트 생성 시 반드시 토큰 만료 시간을 설정해야 하며, 이후 클라이언트가 매번 요청하는 토큰에는 해당 만료 시간이 적용됩니다. 이 유효기간 내에서는 이전에 발급받은 토큰을 사용하여 API에 접근할 수 있지만, 만료 시간이 지나면 다시 토큰을 신청해야 합니다.

TIP

토큰을 영구적으로 사용하고자 한다면, 만료 시간을 매우 긴 값(예: 100년)으로 설정하시기 바랍니다.

클라이언트 권한 부여 버튼을 클릭하여 클라이언트에 API 권한을 부여합니다.
권한 부여할 그룹을 선택하고 저장합니다.

토큰 사용 안내

토큰 발급 인터페이스:

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

비공개 API에 접근할 때는 토큰 값을 Authorization 헤더에 포함시켜야만 성공적으로 접근할 수 있습니다(공개 API의 경우 헤더 설정이 필요하지 않습니다).
Python 호출 예시:

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)

앞서 생성한 API를 비공개 API로 변경한 후, 다시 요청 테스트 버튼을 클릭합니다.
이때 요청 보내기 버튼을 클릭하면 API에 접근할 수 없다는 메시지를 확인할 수 있습니다.
clientId와 secret을 입력한 후, 버튼을 클릭하여 인터페이스에 접근해 토큰을 획득합니다.
token을 Authorization 헤더에 포함시킨 후, 요청 보내기 버튼을 클릭하면 API에 성공적으로 접근할 수 있음을 확인할 수 있습니다.

IP 방화벽 설정

방화벽 설정

방화벽을 활성화하면 특정 IP를 차단할 수 있습니다.

모니터링

DBAPI는 메타 데이터베이스(postgresql/mysql/sqlite)만으로도 사용할 수 있지만, 페이지상의 모니터링 기능(예: API 호출 기록, 접속량, 성공률 등)을 사용하려면 별도의 로그 데이터베이스를 필요로 합니다. 이는 사용자가 직접 구축해야 하며, clickhouse/mysql/postgresql/doris 등을 추천합니다. 물론 다른 관계형 데이터베이스를 사용할 수도 있습니다.

현재 sql 디렉터리에 clickhouse/mysql/postgresql용 로그 데이터베이스 초기화 스크립트가 제공됩니다.

NOTE

모니터링 기능을 사용하지 않는다면 로그 데이터베이스를 구축하지 않아도 되며, conf/application.properties 파일에서 access.log.writer=null로 설정하면 됩니다. (기본 설정도 access.log.writer=null입니다.)

로그 수집 방식

파일 수집: DBAPI는 기본적으로 API 접속 로그를 디스크 파일 logs/dbapi-access.log에 기록합니다. 사용자는 datax, flume 등의 도구를 이용해 로그를 로그 데이터베이스로 수집할 수 있습니다.
데이터베이스 직접 연결: conf/application.properties 파일에 access.log.writer=db를 설정하면, DBAPI가 API 접속 로그를 로그 데이터베이스에 비동기적으로 직접 기록합니다. 이 방법은 로그 양이 많지 않은 경우에 적합합니다.
Kafka 버퍼링: conf/application.properties 파일에 access.log.writer=kafka를 설정하면, DBAPI가 API 접속 로그를 Kafka에 기록합니다. 이후 사용자는 Kafka로부터 로그를 로그 데이터베이스로 수집해야 하며, 이 방식은 로그 양이 많은 환경에 적합합니다. Kafka가 데이터 버퍼링 역할을 수행합니다.

NOTE

이 방식에서는 conf/application.properties 파일에 Kafka 주소를 반드시 입력해야 합니다.

또한 DBAPI에는 Kafka 로그를 읽어 로그 데이터베이스로 쓰는 도구가 내장되어 있으므로, bin/dbapi-log-kafka2db.sh 스크립트를 활용하시기 바랍니다.

모니터링 요약

모니터링 메뉴를 클릭하면 API 호출 기록을 확인할 수 있습니다.

인터페이스 호출 기록 조회

상세 탭을 클릭하면 API 호출 기록을 검색할 수 있습니다.

기타 기능

인터페이스 문서 내보내기

API 메뉴에서 도구 버튼을 클릭한 뒤, 인터페이스 문서 내보내기 버튼을 누르면 됩니다.

플러그인 체계

DBAPI는 다섯 가지 유형의 플러그인 메커니즘을 제공하며, 플러그인 마켓에서 플러그인을 다운로드할 수 있습니다. 자체적으로 플러그인을 개발하려면 플러그인 문서를 참고하시기 바랍니다.

캐시 플러그인

실행기 결과를 캐싱합니다. 예를 들어 SQL 실행기에서는 조회형 SQL의 결과를 캐싱하여 데이터베이스에 대한 과도한 조회를 방지하고 부하를 줄입니다.
캐싱 로직은 사용자가 직접 작성하며, ehcache, redis, mongodb 등 다양한 저장소에 캐싱할 수 있습니다.
캐시에서 데이터를 찾지 못할 경우에만 실행기를 실행하고, 그 결과를 다시 캐싱합니다.

SQL 실행기 다중 SQL 시나리오

SQL 실행기에서 여러 SQL 문장을 포함하는 경우, 캐시 플러그인은 각 SQL 문장의 결과를 하나로 묶어 전체 결과를 캐싱합니다. 단, 각 SQL 문장에 변환 플러그인이 설정되어 있으면 먼저 해당 변환을 수행한 후 캐싱됩니다.

알림 플러그인

API 내부에서 오류가 발생했을 때, 알림 플러그인이 이메일, SMS, DingTalk, Feishu, WeCom 등 다양한 경로로 오류 메시지를 전송합니다.
알림 로직은 사용자가 직접 작성합니다.

데이터 변환 플러그인

때로는 SQL로 원하는 형식의 데이터를 한 번에 얻기 어려울 수 있습니다. 이때 코드를 통해 데이터를 처리하거나 변환하면 편리합니다. 사용자가 직접 데이터 변환 로직을 작성합니다.
예를 들어, SQL 조회 결과에 포함된 사용자 휴대폰 번호나 은행 카드 번호를 변환하여 개인정보를 보호할 수 있습니다.

SQL 실행기 다중 SQL 시나리오

SQL 실행기에서 여러 SQL 문장을 포함하는 경우, 각 SQL 문장마다 별도의 데이터 변환 플러그인이 설정되며, 이 플러그인은 항상 해당 SQL 문장의 결과만 변환합니다.

글로벌 데이터 변환 플러그인

API가 반환하는 데이터 형식은 기본적으로 {success: true, msg: xxx, data: xxx}입니다.
일부 경우, 프론트엔드 로우코드 프레임워크인 AMIS에서는 인터페이스가 반드시 status 필드를 포함해야 하므로, 이러한 요구에 맞춰 글로벌 데이터 변환 플러그인을 사용해 전체 API의 응답 데이터 형식을 변환할 수 있습니다.

데이터 변환 플러그인과 글로벌 데이터 변환 플러그인의 차이점

데이터 변환 플러그인은 실행기의 결과를 변환하는 데 초점을 맞추며, 글로벌 데이터 변환 플러그인은 전체 API의 결과를 변환합니다.

파라미터 처리 플러그인

요청 파라미터를 사용자가 정의한 방식으로 처리합니다.
예를 들어, 요청 파라미터 값을 모두 대문자로 변환하거나, 암호화된 파라미터를 해독하는 로직을 사용자 정의할 수 있습니다.

버전 지원 안내

파라미터 처리 플러그인은 개인용 버전 4.0.16 및 기업용 버전 4.1.10부터 지원됩니다.

유의사항

데이터 소스 지원

Oracle이나 기타 데이터 소스를 사용하려면, 해당 JDBC 드라이버를 DBAPI 배포 후 extlib 또는 lib 디렉터리에 수동으로 추가해야 합니다. 클러스터 배포 시에는 각 노드마다 JAR 파일을 수동으로 넣어야 합니다.
통합 관리를 위해 extlib 디렉터리에 배치하는 것을 권장합니다.

SQL 작성 규칙

MyBatis 동적 SQL 문법과 동일하게, 파라미터 ${}와 #{}를 사용할 수 있습니다. 동적 SQL 문법 문서를 참고하시기 바랍니다. 외부 <select>나 <update> 태그는 생략하고, SQL 내용만 직접 작성하시면 됩니다.
MyBatis와 마찬가지로, SQL에서 작은 괄호 <는 <로 표기해야 합니다.

DBAPI 사용 가이드 ​

제품 소개 ​

핵심 특징 ​

기본 개념 ​

엑섹터 ​

API 그룹 ​

클라이언트 ​

빠른 시작 ​

시스템 로그인 ​

데이터 소스 구성 ​

API 생성 절차 ​

1. API 그룹 생성 ​

2. API 생성 ​

3. API 배포 ​

클라이언트 관리 ​

토큰 사용 안내 ​

IP 방화벽 설정 ​

모니터링 ​

로그 수집 방식 ​

모니터링 요약 ​

인터페이스 호출 기록 조회 ​

기타 기능 ​

인터페이스 문서 내보내기 ​

플러그인 체계 ​

캐시 플러그인 ​

알림 플러그인 ​

데이터 변환 플러그인 ​

글로벌 데이터 변환 플러그인 ​

파라미터 처리 플러그인 ​

유의사항 ​

데이터 소스 지원 ​

SQL 작성 규칙 ​

DBAPI 사용 가이드

제품 소개

핵심 특징

기본 개념

엑섹터

API 그룹

클라이언트

빠른 시작

시스템 로그인

데이터 소스 구성

API 생성 절차

1. API 그룹 생성

2. API 생성

3. API 배포

클라이언트 관리

토큰 사용 안내

IP 방화벽 설정

모니터링

로그 수집 방식

모니터링 요약

인터페이스 호출 기록 조회

기타 기능

인터페이스 문서 내보내기

플러그인 체계

캐시 플러그인

알림 플러그인

데이터 변환 플러그인

글로벌 데이터 변환 플러그인

파라미터 처리 플러그인

유의사항

데이터 소스 지원

SQL 작성 규칙