RDBのテーブルを REST API Server として公開する Spring Boot アプリは、Oiyokan Initializrを使うとすばやく生成することができます。
この記事では、Oiyokan Initializr を入手して実行して、RDBからテーブルを選択して、Spring Boot アプリの生成および実行までを扱います。生成される webアプリは OData v4 が定める定義に従った REST API Server になります。
期待される読者スキル
- Spring Boot + web開発の知見があること
- Maven についての知見があること
- JDBC 設定についての知見があること
なお、この記事は Oiyokan Initializr Release 0.5 (2021-05-11) バージョンをもとに記載されています。また、一連の手順の実行のためにインターネット接続環境が必要です。
Oiyokan Initializrを利用して、REST API Server を生成
oiyokan-initializr を入手
まず最初に Oiyokan Initializr を入手します。https://github.com/igapyon/oiyokan-initializr/releases から Release モジュールを入手できます。
1-0. github.com にアクセスして oiyokan-initializr の Release ページを開きます
1-1. Release ページから Source code (zip) をダウンロードします
1-2. 作業に向いた都合のよいディレクトリに Source code (zip) を展開します
展開後の ZIPファイルは以下のような内容になります。
oiyokan-initializr を実行
Oiyokan Initializr は Spring Boot Web アプリとなっており、Maven をもちいてビルドおよび実行することができます。
2-1. Maven を利用して oiyokan-initializr をビルドおよび実行します
展開されたディレクトリに移動して、以下の mvn コマンドを実行します。
mvn package spring-boot:run
しばらくすると oiyokan-initializr の Webサーバが起動します。
- Note: 依存関係にある jarファイルを Maven Repository からダウンロードするため、初回実行時には時間がかかります
oiyokan-initializr を使用して REST API Server (OData v4) を生成
Oiyokan Initializr は Web ブラウザをもちいて使用するようになっています。デフォルトでは 8082 ポートで Webブラウザから接続することができます。
3-1. 起動後の oiyokan-initializr に Web ブラウザで接続します
以下の URLに Webブラウザで接続します。
http://localhost:8082/
アクセスに成功すると以下のような画面が開きます。
この画面を用いて、REST API Server の設定を入力していきます。
- Note:
application.propertiesファイルの server.port の値を変更することによりポート番号を任意のものに変更することができます。
3-2. START CREATING REST API SERVER FOR RDB をクリックします
START CREATING REST API SERVER FOR RDB をクリックすると REST API Server 作成を開始できます。
3-3. basic authentication ダイアログが表示される場合には、User: admin, Password: passwd123 を利用してログインしてください
BASIC認証のダイアログが表示されたら、User: admin, Password: passwd123 を利用してログインします。
- Note: Spring Boot に知見がある方は、このログイン認証を容易に変更あるいは除去などを実施できます。
- Note: 必要に応じて Spring Security を上書き設定しましょう
3-4. ADD DATABASE をクリックします
- Note:
Oiyokan Initializrで REST API Server プロジェクトを生成するには、少なくとも 1つのデータベースにアクセスできている必要があります。
3-5. データベース設定情報を入力します
REST API Server として公開したいデータベースへの接続情報を入力します。
- Note: Oiyokan で動作確認が行われているのは PostgreSQL最新版, MySQL最新版, SQLSV2008, ORCL18, h2 database最新版 に対してです。
- Note: もし、PostgreSQL, MySQL, SQLSV2008, ORCL18, h2 database 以外のデータベース接続を利用する場合には、pom.xml に JDBCドライバ記述を追記する必要があります。そのようなデータベースを利用する場合は、DB type から一番近い挙動をすると思われるDBを選択します。よくわからない場合は 'h2' を選択するようにします。
3-6. CONNECTION TEST をクリックします
入力したデータベース接続情報が適切であるかどうかをテストします。
- データベースに接続成功した場合には
Connection test successなどと表示されます。 - もしデータベース接続テストが失敗する場合には、JDBC設定情報やネットワーク経路、データベースが起動しているかどうかを確認して再度実行するようにします。
3-7. APPLY DATABASE SETTINGS をクリックします
データベースの接続成功を確認できたら、APPLY DATABASE SETTINGS をクリックしてデータベース接続情報の設定作業を終えます。
Entity を選択
次に REST API Server に公開したい Entity (テーブル) を設定します。
4-1. ADD ENTITY をクリックします
前の手順で作成したデータベース接続情報の右にある ADD ENTITY ボタンをクリックします。
4-2. REST API Server に公開したい Entity (テーブル) をチェックボックスをクリックして選択します
公開したい Entity (テーブル) を探し、テーブル名の左にあるチェックボックスを ON にします。
- Note: もし希望するテーブルが表示されない場合は、JDBC設定に誤りがある、現在JDBC接続に利用している利用しているユーザの権限が足りないなどの可能性がありますので、確認してください。
4-3. Entity の選択を終えたら APPLY ENTITY SELECTION をクリックします
Entity (テーブル) の選択が終わったら APPLY ENTITY SELECTION をクリックします。
- Note: Entity へは読み込みアクセスのみ提供したい場合は、
Allows Write access to the tableチェックボックスを OFF にします。- Note: テーブル名を
キャメル形式に変形させたい場合はConvert name to Camel Caseチェックボックスを ON にします。- Note: Salesforce Connect から接続する場合は、
$filter: Treat null as blankチェックボックスを ON にします。
REST API Server の生成
ここまでの手順を終えると、指定した内容をもとに REST API Server を生成することができます。
さっそく、Spring Boot プロジェクトを生成してダウンロードしてみましょう。
5-1. GENERATE REST API SERVER をクリックして、oiyokan-demo.zip という名前の ZIP ファイルをダウンロードします
GENERATE REST API SERVER をクリックして、生成された REST API Server をダウンロードします。
- Note: なお、この手順で生成される
oiyokan-demo.zipにはデータベース接続情報の記載を含むoiyokan-settings.jsonファイルが含まれます。必要ない場合は手順の後に必ず削除するようにします。
5-2. Oiyokan Initializr を終了します
ここまでの手順を終えると Oiyokan Initializr はもう実行している必要はありません。
CTRL+C などの操作により、Oiyokan Initializr を停止します。
生成された REST API Server を実行
おめでとうございます。ここまでの手順で REST API Server は開発できました。
ここからは、生成された REST API Server の動作の確認の手順です。
生成された REST API Server (OData v4) の実行
それでは生成された REST API Server を実行してみましょう。REST API Server のデフォルトの名前は oiyokan-demo になっています。
生成後の REST API Server も Spring Boot Webアプリとなっており、Maven コマンドによりビルドおよび実行することができます。
- Note: 必要に応じて、pom.xml内に記載された名称やディレクトリ名などを調整してください。
6-1. 作業に都合の良いディレクトリで oiyokan-demo.zip を zip展開します
- Note: ここで展開したファイルの
oiyokan-settings.jsonにはデータベースの接続情報が含まれますので、必要ない場合は手順の後で必ず削除してください。- Note: 生成直後の Spring Boot webアプリにはセキュリティ設定がおこなわれていないため、必要に応じて Spring Security設定などを実施してください。
6-2. zip 展開後のフォルダで以下のように Maven コマンドをもちいて oiyokan-demo を起動します
展開されたディレクトリに移動して、以下の mvn コマンドを実行します。
mvn package spring-boot:run
しばらくすると 生成後の REST API Server の Webサーバが起動します。
6-3. 起動後の oiyokan-demo に Web ブラウザで接続します
Web ブラウザを用いて以下のURLを開きます。
http://localhost:8080/
この手順により起動するサーバが REST API Server (OData v4) となります。REST によるデータベースアクセスが可能な状態です。
REST を用いたアクセス
生成した REST API Server には REST (OData v4) 手順を用いてデータの作成/検索/更新/削除をおこなうことができます。
oiyokan-demo には初期状態として簡易なホームページが設定されています。ここから REST サーバの状況を簡易に確認できます。
7-1. OData v4 ROOT をクリックすると、公開されている Entity の概要を確認できます
利用可能な REST アクセス情報は、REST ルートディレクトリにアクセスすることにより確認できます。デフォルトで /odata4.svc/ が REST (OData v4) ルートディレクトリです。
- Note: 内部情報: この画面は Apache Olingo の応答による実現です。
7-2. OData $metadata をクリックすると、公開されている Entity の詳細を確認できます
REST アクセスの詳細情報は $metadata にアクセスすることにより確認できます。
- Note: 内部情報: この画面は Apache Olingo の応答による実現です。
7-3. actor?$top=3 などといった OData v4 パラメータクエリ記法をもちいてデータを検索して表示できます
REST ルートディレクトリ (デフォルトでは /odata4.svc/) に Entity 名を付与したクエリにより、対象の Entity (テーブル) を検索および表示することができます。
- Note: Chromeのような Webブラウザからアクセスすると デフォルトでは XMLで応答します。クエリに $format=JSON を付与すると JSON 形式を強制できます。
なお、Oiyokan は以下の OData v4 クエリを利用可能です。
| クエリ | 意味 |
|---|---|
| $select | 検索結果項目の選択 |
| $count | 検索結果の件数の取得 |
| $filter | SQL文の WHERE 相当 |
| $orderby | SQL文の ORDER BY 相当 |
| $top | 検索結果上位の何件を取得するか指定 |
| $skip | 検索結果の上位の何件をスキップするか指定 |
これらクエリの詳しい仕様は OData v4 System Query Option で確認できます。
なお、Oiyokan 1.14 では $search および $expand はサポート外です。
7-4. POST, PATCH, DELETE メソッドをもちいて、データベースのレコードを操作することができます
RDB テーブルの変更は、POST, PATCH, DELETE をもちいて実現できます。
| HTTP method | 対応する SQL | 準拠する OData specification 記述 |
|---|---|---|
| GET | SELECT | Request (Individual, Query) |
| POST | INSERT | Create |
| PATCH | UPSERT | Update |
| PATCH (If-Match="*") | UPDATE | Update with header If-Match |
| PATCH (If-None-Match="*") | INSERT | Update with header If-None-Match |
| DELETE | DELETE | Delete |
| PUT (NOT supported) | (NOT supported) | OData v4 spec |
- データの更新には PATCH メソッドを
If-Match = "*"ヘッダー付きで利用することを推奨
- Note: Oiyokan は PUT はサポートしません。これは OData v4 仕様の推奨に基づいた判断の結果です。
後片付け
生成後 Spring Boot webアプリをそのまま利用するのではない場合には、後片付けをして削除の実施をお願いします。
8-1. 試行が終わったら、oiyokan-demo を終了します
CTRL+C などの操作により、Spring Boot webアプリを終了してください。
8-2. 試行が終わり次第、oiyokan-demo.zip および展開後のファイル oiyokan-settings.json を削除します
手順の中で生成したファイルおよびそれを展開したファイルは、内容確認して削除してください。
- Note: この一連の手順で登場する
oiyokan-settings.jsonファイルにはデータベース接続情報の記載が含まれます。oiyokan-demo.zipも含めて必要ない場合は手順の後に必ず削除します。- Note: もし mvn install を利用した場合は、によりインストールされた .m2 フォルダ内の REST API Server についても必要に応じて削除してください。
以上で Oiyokan Initializr の簡易な説明はおわりです。
YouTube上の動画による類似の説明
関連情報
- OData v4についての ほんの入門についてはこちらの記事を参照ください。
- Salesforce Connect から OData 4.0 として Oiyokan に接続する場合の注意点は、こちらの記事を参照ください。
- Oiyokan v1.14 での OData Edm と JDBC Types とのデフォルトのマッピングについては、こちらの記事を参照ください。
- 更新: 2021-06-05: YouTubeへのリンクを追加
- 初出: 2021-05-16