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 の基本情報を入力します。
アクセス権限：公開 API は直接アクセス可能ですが、プライベート API はクライアントがトークンを申請してからアクセスできます（ここでは後々のテストを考慮し、公開 API を選択しています）。
パス：任意の多層構造を設定可能で、例として /a/b/c や /a/b/c/d などが挙げられます。
Content-Type：application/x-www-form-urlencoded の場合、パラメータの設定が必要です。application/json の場合は 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 を入力し、ボタンを押してインターフェースにアクセスし、トークンを取得します。
このトークンをヘッダーの Authorization フィールドに設定し、再度「リクエスト送信」ボタンを押すと、API に正常にアクセスできることを確認できます。

IP ファイアウォールの設定

ファイアウォール設定

ファイアウォールを有効にすることで、特定の IP アドレスを遮断することができます。

監視

DBAPI はメタデータベース（PostgreSQL／MySQL／SQLite）のみで利用できますが、画面上のモニタリング機能（API 呼び出しログ、アクセス数、成功率などの監視）を利用する場合は、別途ログデータベース（ユーザー自身で構築）が必要となります。API アクセスログの保存には、ClickHouse／MySQL／PostgreSQL／Doris のいずれかを推奨しますが、他のリレーショナルデータベースを使用することも可能です。

現在、ClickHouse／MySQL／PostgreSQL 用のログデータベース初期化スクリプトが sql ディレクトリに用意されています。

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 呼び出しログを検索できます。

その他の機能

API ドキュメントのエクスポート

API メニューのツールボタンをクリックし、次に「API ドキュメントのエクスポート」ボタンを押してください。

プラグイン体系

DBAPI は5種類のプラグイン機構を提供しており、プラグインマーケットからプラグインをダウンロードできます。独自にプラグインを開発する場合は、プラグインドキュメントをご参照ください。

キャッシュプラグイン

実行結果をキャッシュします。たとえば 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 全体の返却データ形式を変換できます。

データ変換プラグインとグローバルデータ変換プラグインの違い

データ変換プラグインは実行器の実行結果（例：SQL 実行器でクエリを実行した結果）の形式を変換するのに対し、グローバルデータ変換プラグインは API 全体の返却データ形式を変換します。

パラメータ処理プラグイン

リクエストパラメータをユーザー独自のロジックで処理します。
たとえば、リクエストパラメータの値をすべて大文字に変換する、あるいは暗号化されたパラメータを受け取る際、ユーザーが定義したロジックで復号するといった処理が可能です。

バージョン対応について

パラメータ処理プラグインは、個人版では 4.0.16、企業版では 4.1.10 以降でサポートされています。

注意事項

データソースのサポート

Oracle やその他のデータソースを使用する場合は、該当する JDBC ドライバーパッケージを DBAPI のデプロイ後に配置する必要があります。クラスター環境では、各ノードごとに JAR パッケージを手動で配置してください。
統一管理の観点から、extlib ディレクトリへの配置を推奨します。

SQL の記述規則

MyBatis の動的 SQL 構文と同様に、パラメータの #{} や ${} が使用可能です。動的 SQL 構文ドキュメントを参照してください。外側の <select> や <update> などのタグは不要で、直接 SQL 内容を記述してください。
MyBatis と同じく、SQL 内の「<」記号は直接書かず、< として記述してください。

DBAPI 使用ガイド ​

製品紹介 ​

核心機能 ​

基礎概念 ​

エグゼキューター ​

API グループ ​

クライアント ​

クイックスタート ​

システムへのログイン ​

データソースの設定 ​

API の作成手順 ​

1. API グループの作成 ​

2. API の作成 ​

3. API の公開 ​

クライアント管理 ​

トークンの使用方法 ​

IP ファイアウォールの設定 ​

監視 ​

ログ収集方法 ​

モニタリングの概要 ​

API 呼び出しログの確認 ​

その他の機能 ​

API ドキュメントのエクスポート ​

プラグイン体系 ​

キャッシュプラグイン ​

アラートプラグイン ​

データ変換プラグイン ​

グローバルデータ変換プラグイン ​

パラメータ処理プラグイン ​

注意事項 ​

データソースのサポート ​

SQL の記述規則 ​

DBAPI 使用ガイド

製品紹介

核心機能

基礎概念

エグゼキューター

API グループ

クライアント

クイックスタート

システムへのログイン

データソースの設定

API の作成手順

1. API グループの作成

2. API の作成

3. API の公開

クライアント管理

トークンの使用方法

IP ファイアウォールの設定

監視

ログ収集方法

モニタリングの概要

API 呼び出しログの確認

その他の機能

API ドキュメントのエクスポート

プラグイン体系

キャッシュプラグイン

アラートプラグイン

データ変換プラグイン

グローバルデータ変換プラグイン

パラメータ処理プラグイン

注意事項

データソースのサポート

SQL の記述規則