リモート・サーバーのエンドポイントURLをアプリケーション実行中に動的に変更する

Oracle APEX 24.2ではリモート・サーバーのエンドポイントURLを、アプリケーションの実行中に動的に変更することができるようになりました。

Oracle APEXのPrincipal Product ManagerのSalim Hlayelさんが、オラクルの公式ブログに寄稿している記事「What's new in APEX 24.2: REST Data Source Enhancements」にてFlexible Remote Serverとして紹介しています。

以下より、Flexible Remote Serverの使い方を紹介します。

準備として２つのRESTサービスを作成します。

APEXのワークスペースとしてREST1を作成し、サンプル・データセットのEMP/DEPTを、言語として英語を選択してインストールします。

SQLワークショップからRESTfulサービスを開き、ORDSにスキーマを登録します。

左ペインより有効なオブジェクトを選択し、表EMPをAutoRESTが有効なオブジェクトして作成します。認可は不要です。

以下のURLから従業員の一覧を取得することができるようになります。一覧は英語になります。

http://localhost:8181/ords/rest1/emp

APEXのワークスペースとしてREST2を作成し、同様の作業を行い表EMPの一覧を取得できるようにします。ただし、サンプル・データセットのEMP/DEPTは日本語でインストールします。

http://localhost:8181/ords/rest2/emp

一覧は日本語になります。

これらのREST APIを切り替えて呼び出すひとつのリモート・サーバーを作成します。そのリモート・サーバーをソースとした対話モード・レポートのページを作成します。

最初にリモート・サーバーを作成します。

ワークスペース・ユーティリティのリモート・サーバーを開きます。

作成済みのリモート・サーバーが一覧されます。作成をクリックします。

作成するリモート・サーバーの名前はEMP Sourceとします。サーバー・タイプはRESTデータ・ソースです。

エンドポイントURLとして#proto#://#host#:#port#/ords/#workspace#を記載します。ただし、この値はリモート・サーバーの一覧に表示されるだけのようです。リモート・サーバーのエンドポイントURLは、PL/SQLコードによって生成されます。

最新のAPEXのバージョンでは修正されていますが、以前のバージョンでエンドポイントURLの末尾に/がある場合に発生する不具合がありました。エンドポイントURLの末尾に/を付けない方が安全です。

インストール時にプロンプトを表示はオフにしています。オンにしていると、このアプリケーションを異なるワークスペースにインポートしたときにプロンプトが表示されます。しかし、PL/SQLコードによりエンドポイントURLが決まる形式のリモート・サーバーは、静的IDが同じであれば、ワークスペースが異なっていても同じコードが書かれているべきです。そのため、この設定をオンにするケースはあまり無いでしょう。

静的識別子（静的IDのこと）はEMP_Sourceとし、PL/SQLコードに以下を記述します。p_config.base_urlに与えている文字列に置換文字列として、#proto#、#host#、#port#および#workspace#を含めています。これらを置き換える値をコード中で指定しています。置き換える文字列として、ページ・アイテムP1_PROTO、P1_HOST、P1_PORTおよびP1_WORKSPACEの値を使います。ページ・デザイナでページ番号１を編集している場合は、これらのページ・アイテムの値がセッション・ステートに保存されていると期待できます。しかし、RESTデータ・ソースを作成するときは、これらのページ・アイテムの値は未設定でしょう。そのときに選択されるデフォルト値をNVLで設定しています。

PL/SQLコードに記述したプロシージャ名config_remote_serverを、構成プロシージャとして設定します。

以上の設定を行い、作成をクリックします。

リモート・サーバーEMP Sourceが作成されます。動的がはいになります。

リモート・サーバーEMP Sourceを使用するAPEXアプリケーションを作成します。

空のアプリケーションを作成します。名前はFlexible Remote Serverとします。

アプリケーションが作成されたら、共有コンポーネントのRESTデータ・ソースを開きます。

作成済みのRESTデータ・ソースの一覧画面より、作成を実行します。

RESTデータ・ソースの作成はデフォルトの最初からのまま変更せず、次へ進みます。

Oracle REST Data Servicesの機能であるAutoRESTによるエンドポイントURLを呼び出すため、RESTデータ・ソース・タイプにOracle REST Data Servicesを選択します。

名前はEmployees、URLエンドポイントとして、あえてhttp://localhost:8181/ords/rest2/empを指定します。このエンドポイントはrest2なので日本語のデータを返します。リモート・サーバーのPL/SQLコードはワークスペースの指定がない場合はrest1、つまり英語のエンドポイントを返します。

次へ進みます。

リモート・サーバーとして先ほど作成したEMP Sourceを選択します。ベースURLはhttp://localhost:8181/ords/rest1になります。サービスURLパスは/empです。

次へ進みます。

認証が必要ですはオフにし、検出をクリックします。

英語のデータが一覧されます。選択したリモート・サーバーを対象として、検出が実行されていることが確認できます。

RESTデータ・ソースの作成をクリックします。

RESTデータ・ソースEmployeesが作成されます。エンドポイントURLは、リモートサーバーに定義したエンドポイントURLに/empが付加されます。

ページ・デザイナでホーム・ページを開きます。

リモート・サーバーEMP SourceのエンドポイントURLに含まれるワークスペース名#workspace#を置換するページ・アイテムP1_WORKSPACEを作成します。それ以外の置換文字列はデフォルトを使用し、ページ・アイテムの作成は省略します。

識別の名前はP1_WORKSPACE、タイプは選択リスト、ラベルはWorkspaceとします。設定の選択時のページ・アクションとして値のリダイレクトと設定を選択します。

LOVのタイプに静的値を選択し、静的値の表示値と戻り値のペアとして、English - rest1、Japanese - rest2を設定します。

LOVの追加値の表示はオフです。

詳細の変更されていない変更の警告は無視を選択します。選択リストの値を値のリダイレクトと設定によって切り替える場合、値を変更した後にページがリダイレクトされるため、警告が必ず発生します。ここで無視を設定すると、警告の発生を抑止できます。

リモート・サーバーのコードでページ・アイテムP1_WORKSPACEの値を参照するため、セッション・ステートのストレージはセッションごと(永続)とします。

リージョンを作成します。

識別の名前はEmployeesとし、タイプに対話モード・レポートを選択します。

ソースの位置はRESTソース、RESTソースは先ほど作成したEmployeesを選択します。

以上でアプリケーションは完成です。

アプリケーションを実行して動作を確認します。

Workspaceが空白の場合は、リモート・サーバーはワークスペースとしてデフォルトのrest1を選択します。そのため、レポートの表示は英語になります。

WorkspaceにJapaneseを選択すると、ワークスペースとしてrest2が選択されるため、レポートの表示は日本語に変わります。

WorkspaceにEnglishを選択すると、ワークスペースとしてrest1が選択されるため、レポートの表示は英語に変わります。

以上で、リモート・サーバーのエンドポイントURLが、ページ・アイテムの値によって動的に変更されることが確認できました。

今回の記事は以上です。

簡単なアプリケーションですが、今回作成したアプリケーションのエクスポートを以下に置きました

https://github.com/ujnak/apexapps/blob/master/exports/sample-flexible-remote-server.zip

Oracle APEXのアプリケーション作成の参考になれば幸いです。

完

リモート・サーバーを入れ替えてRESTデータ・ソースの実行環境を切り替える

リモート・サーバーを上手に使うことで、RESTデータ・ソースによって操作する環境を簡単に切り替えることができます。例えば、テスト環境と本番環境の切り替えなどを行うことができます。

以下よりリモート・サーバーの使い方を紹介します。 

RESTデータ・ソースを作成する際に、リモート・サーバーが作成されます。

すでにリモート・サーバーが作成済みの場合は、それが選択されます。

リモート・サーバーはアプリケーションではなく、ワークスペースに作成されます。

ワークスペース・ユーティリティのリモート・サーバーより、作成済みのリモート・サーバーを確認できます。

例えば本番環境のRESTサービスが以下のように作成されているとします。

https://本番環境のホスト/ords/apexdev/emp/test

ソースは以下です。

select * from emp

開発環境にも同じRESTサービスが実装されています。

https://開発環境のホスト/pls/apex/japancommunity/emp-dev/test

ソースは以下です。

select * from emp

空のAPEXアプリケーションを作成し、最初に開発環境にアクセスするRESTデータ・ソースを作成します。

共有コンポーネントのRESTデータ・ソースを開きます。

RESTデータ・ソースの作成を開始します。

RESTデータ・ソースの作成は最初から行います。

次へ進みます。

RESTデータ・ソース・タイプ、名前をそれぞれ指定し、URLエンドポイントとして、開発環境を指すURLを入力します。

次へ進みます。

切り替える環境と一致しない部分をベースURLとして指定します。切り替える環境と一致する部分はサービスURLパスに記述します。今回の例ではURLの最後のtestの部分だけが一致するため、サービスURLパスはtestになります。

すでに作成済みのリモート・サーバーが選択され、そのベースURLが設定したい値と異なる場合は、リモート・サーバーに新規作成を選びます。ただし、この画面からリモート・サーバーを新規作成すると、名前と静的識別子が自動生成されます。分かりにくい名前になるため、あらかじめワークスペース・ユーティリティよりリモート・サーバーを作成しておくことをお勧めします。

次へ進みます。

ページ区切りタイプはリモート・サーバーの設定に関係しません。

次に進みます。

認証もリモート・サーバーに関係しません。

検出をクリックします。

RESTデータ・ソースが検出され、プレビューが表示されます。

RESTデータ・ソースの作成をクリックします。

RESTデータ・ソースが作成されます。エンドポイントURLはベースURLとサービスURLパスの結合なので、これらをどのように分けてもエンドポイントURLは変わりません。

このRESTデータ・ソースを使う対話モード・レポートを作成します。

識別のタイトルをEmployees、タイプを対話モード・レポートとします。ソースの位置としてRESTソースを選択し、RESTソースとして作成したRESTデータ・ソースを選択します。

ページを実行します。開発環境にある表EMPの内容が、REST API経由で表示されます。

これから、本番環境をリモート・サーバーとして登録します。その後、RESTデータ・ソースを本番環境を参照するように切り替えます。

ワークスペース・ユーティリティのリモート・サーバーを開き、作成を実行します。

リモート・サーバーの名前、静的識別子を設定し、サーバー・タイプとしてRESTデータ・ソースを選択します。

エンドポイントURLは、RESTデータ・ソースのベースURLとして扱われるURLです。RESTデータ・ソースのサービスURLパスと結合し、本番環境のRESTサービスを呼び出すURLになります。

必ずしも必要ではありませんが、インストール時にプロンプトを表示にチェックを入れておきます。このリモート・サーバーを使用しているRESTデータ・ソースを含むAPEXアプリケーションをインポートする際に、プロンプトが表示されるようになります。

以上で作成をクリックします。

本番環境のリモート・サーバーが作成されます。テスト環境向けのリモート・サーバーの名称は、分かりやすいように変更しておくと良いでしょう。

RESTデータ・ソースの呼び出す環境を切り替えます。

共有コンポーネントのRESTデータ・ソースより、作成済みのRESTデータ・ソースを開きます。

リモート・サーバーを開発環境から本番環境のサーバーへ切り替えます。

リモート・サーバーを切り替えると、自動的にベースURLが更新されます。

変更の適用をクリックします。これで、環境の切り替えは完了です。

先ほど作成した対話モード・レポートを表示します。同じデータなので違いがわかりませんが、REST APIの呼び出し先は切り替わっています。

リモート・サーバーのインストール時にプロンプトを表示の設定ですが、これをオンにしていると、APEXアプリケーションのインポート時に以下の画面が開きます。

この画面より、ベースURLの変更ができます。すでにリモート・サーバーが作成されている場合（すでに存在しますがYesの場合）、登録済みのリモート・サーバーのベースURLが表示されます。そのまま次に進むと、インポートするAPEXアプリケーションから見ると、ベースURLが変更され、REST API経由で呼び出される環境が変更されます。

インストール時にプロンプトを表示がオフの場合は、すでにリモート・サーバーが作成されている場合は、そのベースURLが上書きされます。インポートするAPEXアプリケーションから見ると、同じ環境が呼び出されますが、既存のアプリケーションに影響を与えるため注意が必要です。

本番環境や開発環境といった用途の違うワークスペースの間で、同じ名前、静的識別子のリモート・サーバーのベースURLは同じにするというルールを設ける場合は、リモート・サーバーのインストール時にプロンプトを表示はオフ、同じ名前、静的識別子のリモート・サーバーで、本番環境のリモート・サーバーは本番環境であるRESTサービスを呼び出し、開発環境のリモート・サーバーは開発環境であるRESTサービスを呼び出すといった運用の場合は、インストール時にプロンプトを表示はオン、という運用になるかと思います。

リモート・サーバーの使い方の紹介は以上になります。

Oracle APEXのアプリケーション作成の参考になれば幸いです。

完