2021年1月5日火曜日

Oracle APEXでWebコンポーネントを扱う

 Oracle IndiaのSrihari RavvaさんがWeb Components in Oracle APEXとして、WebコンポーネントをOracle APEXで扱う方法を紹介しています。面白いトピックなので、自分でも試してみました。

環境に依存せずに作業を試行できるよう、いくつか手順を変えています。特にJavaScriptから呼び出すRESTful APIを独自のものから、Oracle APEXのRESTful APIのサンプルとして提供されているoracle.example.hrを使うようにしています。

確認作業は以下の順番で行います。

  1. Oracle APEX Builder Extension by FOSを導入する。
  2. RESTfulサービスのサンプルをインストール(またはリセット)する。
  3. 空のアプリケーションを作成する。
  4. 静的アプリケーション・ファイルに、WebコンポーネントとなるJavaScriptのコードを記述する。
  5. 静的リージョンを作成し、動作を確認する。
  6. 動的アクションを作成し、動作を確認する。
1、2、3が準備作業、4、5、6が元記事に記載のあるWebコンポーネントにまつわる作業です。

Oracle APEX Builder Extension by FOSを導入する



FOEX GmbHが開発した、Oracle APEXの静的アプリケーション・ファイル、静的ワークスペース・ファイルやプラグインのファイルを、Monaco Editorで直接編集可能にするブラウザの拡張機能です。

こちらよりChromeまたはFirefoxのウェブストアへ移動し、拡張機能を導入します。

この拡張機能を導入しなくても、手元で編集したファイルを静的アプリケーション・ファイルとしてアップロードすることもできます。

RESTfulサービスのサンプルをインストール(またはリセット)する


SQLワークショップよりRESTfulサービスを開きます。


RESTfulサービスは、Oracle REST Data Servicesによって実装されています。Oracle APEXでは、サービスを作成するためのユーザー・インターフェースのみ提供しています。Oracle REST Data Servicesによって、Oracle APEXのワークスペースに紐づいているスキーマが扱えるよう、ORDSにスキーマを登録を実行します。

今回はサンプル・サービスをそのまま利用するので、サンプル・サービスのインストールをONにし、スキーマ属性の保存を実行します。


以上でサンプル・サービスが利用可能になっています。すでにRESTfulサービスが有効になっている場合は、サンプル・サービスのリセットを実施します。


警告が表示されます。oracle.example.hrモジュールおよび表EMPとDEPTが削除され、再作成されることに注意してください。困る場合は、検証の際に使用する従業員の情報を調整することにして、リセットせずに作業を進めましょう。リセットすることに問題がなければ、サンプル・サービスのリセットを実行します。


ORDSハンドラ定義を開いて、完全なURLを確認します。今回使用するREST APIは、モジュールoracle.example.hrのURIテンプレートemployees/:id、メソッドはGETです。


Webコンポーネントの中から、この完全なURLに従業員番号(EMPNO)を引数として与えて呼び出します。スクリーンショットに表示されている完全なURLは、それぞれの環境で異なります。

空のアプリケーションを作成する


今回の検証を実装するアプリケーションを作成します。アプリケーション・ビルダーより作成を実行します。

新規アプリケーションをクリックします。

アプリケーションの名前は任意ですが、今回はWebコンポーネント検証としています。その他は何もせず、アプリケーションの作成を実行します。

以上でアプリケーションの準備も完了しました。

JavaScriptのコードを記述する


静的アプリケーション・ファイルに、WebコンポーネントとなるJavaScriptのコードを記述します。共有コンポーネントの静的アプリケーション・ファイルを開きます。


Oracle APEX Builder Extension by FOSがインストールされているとEdit Filesの領域が表示されます。Create Fileをクリックします。


File Nameとしてemployee-info.jsを指定し、Createを実行します。


以下のコードを貼り付け、Saveを実行します。
// JavaScriptコード
// temlate要素を生成する。
const template = document.createElement('template');
// 従業員情報を表示するテンプレートとなるHTMLとCSSを記述する。
// Shadow DOMにになるので、ここで定義されたCSSはカスタム要素のemployee-data内でのみ有効。
// ページレベルで定義されているCSSはカスタム要素には適用されない。
template.innerHTML = `
  <style>
  div.employee-data {
    background: #F5F4F2;
    width: 400px;
    margin-bottom: 10px;
    border-bottom: purple 8px solid;
    padding: 4px;
  }
  div.employee-data h2{
    color: purple;
  }
  </style>
  <div class="employee-data">
    <h2></h2>
    <div class="empno">EMPNO: <span></span> </div>
    <div class="job">JOB: <span></span> </div>
  </div>
`;
// カスタム要素のためのクラスを定義する。
// 一般的にはカスタム要素の名前が custom-element であれば、 CustomElement をクラス名とする。
// 今回は employee-info がカスタム要素なので、クラス名は EmployeeInfo となる。
class EmployeeInfo extends HTMLElement {
  constructor() {
    // かならず super をコンストラクタの先頭で呼び出す。HTMLElementとして正しく初期化される。
    super();
    // Shadow DOMをアタッチする。これによりカスタム要素が独立する。
    this.attachShadow({ mode: 'open' });
    // テンプレートをクローンし、ShadowRootに追加する。
    this.shadowRoot.appendChild(template.content.cloneNode(true));
    // RESTful APIを呼び出し従業員データを取得する。
    // 従業員番号(empno)の属性を引数として、RESTful APIを呼び出す。
    // RESTful APIの応答をテンプレートの穴埋めに使用する。
    fetch('https://apex.oracle.com/pls/apex/your_workspace/hr/employees/' + this.getAttribute('empno')).then(response => response.json()).then(data => {
      this.shadowRoot.querySelector('h2').innerText = data.ename;
      this.shadowRoot.querySelector('div.empno > span').innerText = data.empno;
      this.shadowRoot.querySelector('div.job > span').innerText = data.job;
    });
  }
}
// カスタム要素 employee-info と クラス EmployeeInfo を関連づける。
window.customElements.define('employee-info', EmployeeInfo);

employee-info.jsを保存すると、employee-info.js.mapおよびemployee-info.min.jsも作成されます。

処理内容については、コードのコメントを参照してください。

静的リージョンで動作確認をする

ページ・デザイナでホーム・ページ(Page 1)を開きます。HTMLヘッダーとして以下を設定し、ホーム・ページのロード時に、先ほど静的アプリケーション・ファイルとして作成したJavaScriptのファイルを読み込みます。

<script type="module" src="#APP_IMAGES#employee-info.min.js"></script>

静的アプリケーション・ファイルを標準のJavaScriptのファイルURLではなく、HTMLヘッダーのscriptタグで読み込んでいます。これは、スクリプトをmoduleとして認識させ、グローバルから参照できないようにするためです。

次にリージョンを作成し、名前はWeb Components、タイプは静的コンテンツとします。ソースのテキストには以下を設定します。

<employee-info empno="7839"></employee-info>

リージョンの設定ができたら、ページの保存と実行を行い、動作を確認します。

以下のように、従業員KINGが表示されたら、手順通り実装できています。


動的アクションを使って動作確認をする


Webコンポーネントの表示に動的アクションを使います。再度、新規にリージョンを作成します。名前はWeb Components - Dynamic Action、タイプは静的コンテンツです。ソースのテキストには以下を設定します。

<div id="employee_data_container"></div>

表示する従業員を指定するため、ページ・アイテムの作成を実行します。名前はP1_EMPLOYEES、タイプはチェック。ボックス・グループ、ラベルはEmployeesとします。LOVのタイプは静的値とします。


LOVの静的値として、以下のペアを設定します。

表示値

戻り値

BLAKE

7698

CLARK

7782

JONES

7566

SCOTT

7788


サンプルのRESTfulサービスが初期状態でない場合は、表示値としている従業員が存在しない場合もあります。存在する従業員を探してLOVの値を登録してください。

最後に動的アクションを登録します。左ペインから動的アクション・ビューを開き、動的アクションを作成します。

名前はDisplay Employee Dataとし、タイミングとして、イベントは変更、選択タイプはjQueryセレクタ、jQueryセレクタとしてinput[name=P1_EMPLOYEES]を指定します。


実行されるアクションとして、JavaScriptコードの実行を指定し、設定のコードに以下を設定します。

// チェック・ボックスより従業員番号を取得する
let empNo = $(this.triggeringElement).val();
// 従業員番号に対応するemployee-infoのタグを探して取得する。
let employeeNode = $("employee-info[empno=" + empNo + "]");
if ($(this.triggeringElement).is(':checked')) {
    // 要素が既に存在するか確認する。存在する場合は表示する。
    if (employeeNode.length == 1)
        employeeNode.show();
    else
        // そうでない場合は、要素を追加する。
        $('#employee_data_container').append('<employee-info empno="' + empNo + '"></employee-info>');
}
else {
    // チェックが外れたときは非表示にする。
    employeeNode.hide();
}

動的アクションの設定が完了したら、ページの保存と実行を行います。この記事の先頭にあるGIF動画の動作を確認できるはずです。

以上でOracle APEXでのWebコンポーネントの実装についての記事は終了です。

実際にはより複雑な実装になるかと思いますが、元記事を読んで、基本的な実装手順について参考になる内容だと思いました。また、Oracle APEXのプラグインとして実装することで、サーバー側の条件や認可スキームなども活用できるようになり、より便利なものになるでしょう。

完

2021年1月4日月曜日

対話グリッドの列の計算方法について

 Stefan Dobreさんによるこちらの記事 How to dynamically compute Interactive Grid Columns in #orclAPEX 20.2 の紹介です。

記事に記載されている実装を行うことで、理解してみました。色々と応用ができますし、同様の処理を大量の動的アクションで実装していた方は、ずっと分かりやすく書き換えることができるでしょう。

この機能は、Oracle APEXを20.2以降よりサポートされています。

以下が確認作業の順番です。

  1. 表とアプリケーションの作成
  2. CSVファイルのロード
  3. 計算によって導出される列を、対話グリッドのSQLに追加
  4. 対話グリッド上で、列の計算を行うコードを追加
1から2までは準備作業になります。Oracle APEXによるアプリケーション作成について経験のある方にとっては、冗長かもしれません。

表とアプリケーションの作成


サンプルの受注一覧のデータより、商品(PRODUCT_NAME)の価格(PRICE)と数量(QUANTITY)より、売り上げ(REVENUE)を計算します。売り上げは

REVENUE = PRICE * QUANTITY

として計算するため、表の列には含みません。

クイックSQLに与える設定は、以下とします。
# prefix: dmt
orders
  product_name vc255 /nn
  price num
  quantity num
SQLワークショップよりクイックSQLを開き、左側に上記のモデルを入力します。

SQLの生成、SQLスクリプトを保存、レビューおよび実行を順次実行します。


SQLスクリプトが開きます。DDLの変更は不要なので、そのまま実行します。確認画面が開くので、即時実行をクリックします。


表DMT_ORDERSが作成されます。続けてアプリケーション作成を実行します。


アプリケーション作成ウィザードが起動します。

作成するアプリケーションの名前は対話グリッドの計算とします。デフォルトで追加されているページをすべて削除し(編集をクリックして削除を実行)、代わりにページの追加をクリックして対話グリッドを追加します。


対話グリッドのページ名も対話グリッドの計算とします。表またはビュー、編集を許可を選択し、表またはビューとして表DMT_ORDERSを選択します。

ページの追加をクリックします。


以上の設定を行い、アプリケーションの作成を実行します。

アプリケーションが作成されます。今回の作業はページ番号1の対話グリッドの計算のページに対して実施します。



CSVファイルのロード



ロードするCSVファイルを、以下よりダウンロードします。

https://apex.oracle.com/pls/apex/japancommunity/r/simcontents/download?id=SampleOrders.csv

次にSQLワークショップのユーティリティより、データ・ワークショップを開きます。データのロードをクリックして開きます。


ファイルのアップロード(デフォルトで選択されています)より、ファイルの選択をクリックして、先ほどダウンロードしたSampleOrders.csvを選択します。


ロード先を既存の表、表としてクイックSQLで作成した表DMT_ORDERS、ファイル・エンコーディングは日本語(Shift JIS)を指定します。最初の行にヘッダーが含まれるはチェックする、列デリミタの,(カンマ)、囲み文字の"(ダブルクォート)は、デフォルトのままとします。

データのロードを行う前に、構成をクリックします。


受注番号のマップ先としてID(Number)、製品はPRODUCT_NAME(Varchar2)、単価はPRICE(Number)、数量はQUANTITY(Number)を指定します。単価と数量にはグループ・セパレータとして,(カンマ)、小数点文字として.(ピリオド)を指定します。私がテストしたときは、小数点文字のデフォルトが,(カンマ)になっていたので、設定変更は必須です。

表DMT_ORDERSに含まれる4つの列をマップして、変更の保存を行います。


構成が保存されたので、データのロードを実行します。


103行のデータがロードされていれば、ロードは成功です。続けてアプリケーションの作成を実行します。



列REVENUEをSQLに追加



対話グリッドのページをページ・デザイナで開き、対話グリッドのリージョンを左ペインより選択します。ソースのタイプをSQL問合せに切り替え、SQL問合せを以下の列REVENUEを追加したものに更新します。
select ID,
       PRODUCT_NAME,
       PRICE,
       QUANTITY,
       NVL(PRICE,0) * NVL(QUANTITY,0) as REVENUE
from DMT_ORDERS

列REVENUEが追加されます。元記事によると、今回のソリューションは編集可能な列にのみ適用可能なので、タイプを表示のみに設定することは不可です。しかし、列REVENUEは計算された結果でありユーザーからの入力は禁止したいので、外観のCSSクラスにis-readonlyを指定します。また、データベースのアップデート操作に含まれないよう問合せのみをONにします。


変更を保存して、ページを実行します。


この状態で列Price、Quantityを変更して、保存をクリックすると列Revenueに計算結果が反映されることが確認できます。

次に、保存をクリックせず、PriceやQuantityを変更するとすぐにRevenueが更新される実装を行います。


対話グリッド上の列の計算



Oracle APEX 20.2から利用可能になったcalcValueとdependsOnの機能を使用します。

列REVENUEのプロパティである詳細の列初期化JavaScriptファンクションに以下を記述します。


dependsOnとして、この列REVENUEが依存している列を指定します。REVENUEはPRICEとQUANTITYの積なので、dependsOnはPRICEとQUANTITYになります。

dependsOnで指定された列、PRICEまたはQUANTITYが変更されたときに呼び出されるファンクションをcalcValueとして記述します。戻り値が列REVENUEの値になります。

以上のコードを設定して、期待した動作になるか確認してみましょう。列REVENUEを計算しているJavaScriptのコードの部分については、理解が難しいところはないかと思います。


おまけ:書式マスクについて


数値列である列PRICEとQUANTITYに以下のような書式マスクの設定がされていると、3桁ごとに区切り文字として,(カンマ)が含まれます。

999G999G999G999G999G999G999G999G999G990

このままではparseInt()で適切な整数として変換されないので、replaceAll(",","")でカンマを取り除いています。

列PRICEやQUANTITYを変更すると列REVENUEが更新されますが、この計算結果には,(カンマ)が含まれません。一旦、対話グリッドを保存すると書式マスクが適用され、,(カンマ)が表示されます。

対話グリッドの計算結果としても,(カンマ)を含めるには、Intl.NumberFormatを使って以下のように記述することで対応できます。

以上で、対話グリッドの列の計算方法の紹介は終了です。

今回作成したアプリケーションのエクスポートを以下に置きました。
https://github.com/ujnak/apexapps/blob/master/exports/calcvalue-interactive-grids.zip

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

完

2020年12月31日木曜日

アクセス制御の実装サンプル解説(6) - 認可スキーム

 こちらの記事の継続で、本シリーズの最後の記事になります。

今までは認可スキームありきで、各種のページ・タイプへアクセス制御を実装してきました。この記事では、認可スキームについて説明します。

認可スキームは共有コンポーネントとして登録されます。登録済みの認可スキームを確認してみましょう。共有コンポーネントから認可スキームを開きます。

コントリビューション権限、リーダー権限、管理権限の3つが登録済みです。

この認可スキームはアプリケーション作成ウィザードの機能で、アクセス制御にチェックを入れているとウィザードによって、アプリケーションに作成されます。

または、ページ作成ウィザードでページ・タイプとして機能を選択し、アクセス制御を追加することもできます。

横道にそれますが、導入されたアクセス制御のコンポーネントはビルド・オプションの機能: アクセス制御に紐づけられています。

共有コンポーネントにビルド・オプションがあります。

これを開くと、ビルド・オプションの一覧が確認できます。アプリケーション作成ウィザード、ページ作成ウィザードで追加できる機能は(ログイン・ページを除き)、ビルド・オプションに紐づけられています。機能: アクセス制御をクリックして開いてみます。

アクセス制御に関連するコンポーネントの確認や、無効化(ステータスを除外へ変更)、機能の削除(コンポーネントの削除)が可能であることがわかります。

さて、認可スキームです。実体が分かりやすいのはリーダー権限です。こちらを開いてみます。


リーダー権限は、スキーム・タイプとしてはブールを戻すPL/SQLファンクションとして実装されています。


スキーム・タイプは他に以下の種類があります。
  • EXISTS SQL問合せ
  • NOT EXISTS SQL問合せ
  • ブールを戻すPL/SQLファンクション
  • ロールまたはグループ内にある
  • ロールまたはグループ内にない
  • 式1のアイテムがNOT NULL
  • 式1のアイテムがNULL
  • 式1のアイテムの値 != 式2
  • 式1のアイテムの値 = 式2
  • 式1のプリファレンスの値 != 式2
  • 式1のプリファレンスの値 = 式2
これらは還元すると、ブールを戻すPL/SQLファンクションになります。つまり、真偽値を返すPL/SQLファンクションが認可スキームです。戻り値がTRUEであればアクセスが許可され、FALSEであればアクセスが許可されません。

この認可スキームとなるファンクションが呼び出されるタイミングが評価ポイントであり、認可スキームの検証の頻度が高いとパフォーマンス面ではマイナスになりますが、権限の変更の反映が早くなります。

例えば認可スキームの検証がセッションごとに1回であると、サインインした後、再度サインインするまで権限の状態は変わりません。一般にOracle APEXのアプリケーションではサインアウトを意図的に行うことは少ないので、セッションのタイムアウトまで一旦許可されたアクセス権限は、そのまま維持されることになります。

ページ・ビューごとに1回であれば、サインアウト/サインインを行うことなく、新たにページを表示するたびにアクセス権限が評価され、変更された権限が適用されます。

リーダー権限として定義されているコードを見てみましょう。
if nvl(apex_app_setting.get_value(
   p_name => 'ACCESS_CONTROL_SCOPE'),'x') = 'ALL_USERS' then
    -- allow user not in the ACL to access the application
    return true;
else
    -- require user to have at least one role
    return apex_acl.has_user_any_roles (
        p_application_id => :APP_ID, 
        p_user_name      => :APP_USER);
end if;

アプリケーション定義のACCESS_CONTROL_SCOPEがALL_USERSであればTRUEを返す、それ以外はapex_acl.has_user_any_rolesの結果(何かロールが登録されていればTRUE)を返しています。

次にコントリビューション権限を見てみましょう。

コントリビューション権限のスキーム・タイプとして、ロールまたはグループ内にあるが設定され、タイプがアプリケーション・ロール、名前が管理者、コントリビュータとなっています。つまり、ユーザーがアプリケーション・ロールとして管理者かコントリビュータ・ロールを持っているとコントリビューション権限がTRUEとなります。

今回の要件では、管理者はデータの編集を行なわず(自分が担当者の場合に限定)、コントリビューション権限は持たないことにしているので、名前から管理者を除きます。

管理権限は、こちらの名前が管理者のみ(アプリケーション・ロールとして管理者を持っている)の認可スキームです。コントリビューション権限と大差ないので確認は省きます。

次に、アプリケーション・ロールの設定を確認します。共有コンポーネントからアプリケーション・アクセス制御を開きます。

アプリケーションに登録されているアプリケーション・ロールとユーザー・ロール割当てとして、ユーザーに割り当てられたアプリケーション・ロールを確認することができます。


共有コンポーネントのアプリケーション・アクセス制御を開いて、ユーザー・ロール割当てを実施するには、Oracle APEX開発環境にログインする必要があります。つまりOracle APEXの開発者アカウントが必要ですが、機能としてアクセス制御がアプリケーションに組み込んであれば、サイド・メニューの管理よりアクセス制御の設定を変更したり、ユーザーへのアプリケーション・ロールの追加/削除をすることができます。


機能: アクセス制御によって提供されるアクセス制御は、これを導入しないとアプリケーションのアクセス制御ができない、といったものではありません。

そうではなく、以下の作業をアプリケーションに行います。
  • アプリケーション・ロールとして、管理者、コントリビュータ、リーダーを登録する。
  • アプリケーション定義にACCESS_CONTROL_SCOPEを登録し、ACL_ONLYを設定する。
  • 認可スキームとして管理権限(アプリケーション・ロールの管理者を持っている)、コントリビューター権限(アプリケーション・ロールの管理者かコントリビュータを持っている)、リーダー権限(アプリケーション定義がALL_USERSであるか、または、何かひとつでもアプリケーション・ロールを持っている)の3つを登録する。
  • 管理権限を持ったユーザーによって、アプリケーション定義ACCESS_CONTROL_SCOPEの変更と、ユーザーへのアプリケーション・ロールの割当てを可能とする画面を、アプリケーションに登録する。

アプリケーションを開発する側としては、自力で同様の機能をアプリケーションに組み込むこともできますが、提供されている機能が開発するアプリケーションの要件を満足するのであれば、わざわざ開発する必要はなく、そのまま利用することで開発工数の削減になります。アプリケーション自体に組み込まれた設定であるため、組み込まれた後の認可スキームやページは自由に改変可能です。

ウィザードのよって組み込まれるアクセス制御の機能は、そのアプリケーションに閉じた作業です。複数のアプリケーションに跨ったアプリケーション・ロールの登録やユーザーへのロールの割り当てといった機能は含まれていません。そのような機能が必要な場合は、認可スキームを作成する必要があります。

伝統的な企業アプリケーションであれば、LDAPを認証/認可のためのサーバーとして使用していることが多いと思います。Oracle APEXではLDAPの扱いを容易にするためのAPI、APEX_LDAPを提供しています。これらのAPIを使った認可スキームの実装については、また記事を改めて行えたらと思います。

今回の認可に関するシリーズは以上になります。

完