Oracle APEX 21.1よりサンプル・アプリケーションはGitHubでホストされるようになり、ギャラリから直接インストールすることができなくなりました。Oracle APEX 22.1では、この状況が改善され、サンプル・アプリケーションはギャラリから直接インストールできるようになっています。
サンプル・アプリケーションは変わらずGitHubにあるため、実際にはAPEXの画面から、GitHub上にあるエクスポートされたAPEXアプリケーションのダウンロードとインストールを行なっています。
この新機能に関連して、ユーザーが作成したアプリケーションをカスタム・アプリケーションとしてギャラリに登録できるようになっています。カスタム・アプリケーションも標準のサンプル・アプリケーションと同様に、ギャラリから直接インストールすることができます。
Oracle APEX 22.1の新しいギャラリについて、この機能を開発したDaniel Hochleitnerさんが、AskTOM Office HourのNew in APEX 22.1 (Part 3): Ed. Improvements, REST Enabled SQL Queries , and easy App Gallery Internalsで解説しています。また、カスタム・アプリケーションの登録方法は、Oracle APEX Administration Guideの3.5.8.2.3 Install Custom Apps in the Galleryで説明されています。
Office Hourとマニュアルの両方とも、カスタム・アプリケーションを登録するにはmanifest.jsonというファイルを作成し、JSON形式で登録するアプリケーションの情報を記載する、という手順になっています。
手作業でmanifest.jsonを作成するのは手間なので、manifest.jsonを生成するアプリケーションを作成することにしました。
以下より、APEXアプリケーションとREST APIの作成手順を紹介します。アプリケーションはapex.oracle.com上に作成します。
一番最初に、カスタム・アプリケーションの情報を保持する表を作成します。
SQLワークショップのユーティリティのクイックSQLを使います。
以下のモデルを与えて、表GALLARY_CUSTOM_APPSとGALLERY_CUSTOM_APPS_LANGを作成します。
# prefix: gallery
# auditcols: true
custom_apps
internal_name vc80 /nn /unique /upper
author vc160 /nn
version vc20 /nn
icon vc400
url vc400
source vc400
zip vc400 /nn
license vc80
apex_version vc8
custom_apps_lang
custom_app_id vc80 /nn /fk custom_apps
language vc2 /nn /lower
name vc160 /nn
description vc800SQLの生成、SQLスクリプトを保存、レビューおよび実行を順次クリックします。
SQLスクリプトが実行され、表、索引、トリガーが作成されます。
アプリケーション・ビルダーからアプリケーション作成ウィザードを呼び出します。
アプリケーションの名前はカスタム・アプリケーション管理とします。ページの追加をクリックします。
ページのタイプとして、マスター・ディテールを選択します。
ページ名はカスタム・アプリケーション管理とします。表示形式には積上げを選択します。マスター表としてGALLERY_CUSTOM_APPS、ディテール表としてGALLERY_CUSTOM_APPS_LANGを選択します。
ページの追加をクリックします。
表GALLERY_CUSTOM_APPSとGALLERY_CUSTOM_APPS_LANGの双方を編集できるページが追加されました。
アプリケーションの作成を実行します。
SQLスクリプトの編集画面が開きます。ダウンロードをクリックし、SQLスクリプトをファイルに落とします。
作成をクリックします。
サンプルとして活用されるアプリケーションだと、不要になって削除されることも多いでしょう。削除スクリプトを作成しておくと、アプリケーションの削除時に表も削除することができます。
drop table gallery_custom_apps_lang;
drop table gallery_custom_apps;
fアプリケーションID.zipというファイル名で、アプリケーションがエクスポートされます。
スキーマ属性は通常デフォルトから変更する必要はありませんが、サンプル・サービスのインストールがONの場合、RESTfulサービス以外に表EMP、DEPTも作成されます。データベース・オブジェクトが作成されると困る場合は、サンプル・サービスのインストールはOFFにします。
URIテンプレートとしてappsを入力し、テンプレートの作成をクリックします。
manifest.jsonの定義に従ったJSONドキュメントが返されていることを確認します。
インスタンスの設定を開きます。
アプリケーションが作成されました。
追加したページをページ・デザイナで開き、ビルド・オプションを使って監査列をすべてコメント・アウトします。両方の表の列CREATED、CREATED_BY、UPDATED、UPDATED_BYが監査列に当たります。これらの列の値はトリガーによって設定し、画面からは操作しません。
以上でアプリケーションは完成です。
今回作成したアプリケーションをギャラリにカスタム・アプリケーションとして登録し、インストールできるようします。
ギャラリからインストールすることを考慮して、表GALLERY_CUSTOM_APPS、GALLERY_CUSTOM_APPS_LANGを、アプリケーションをインストールするときに作成するようにします。
クイックSQLを使って表を作成する際に、生成されたSQLスクリプトを保存しています。
SQLワークショップのSQLスクリプトを開き、保存したSQLスクリプトの鉛筆アイコンをクリックします。
SQLワークショップのSQLスクリプトを開き、保存したSQLスクリプトの鉛筆アイコンをクリックします。
アプリケーションのサポートするオブジェクトを開きます。
ダウンロードしたファイルをインストール・スクリプトとして登録します。
インストール・スクリプトを開きます。
スクリプトの作成方法を選択します。ダウンロードしたファイルを使うのでファイルから作成を選択し、次に進みます。
名前を入力します。今回はgalleryとしています。順序はデフォルトのままにしておきます。インストール・スクリプトはDDLに限らず、データベースで実行できるスクリプトであれば登録できます。データのローディングなども実行可能です。
複数のインストール・スクリプトがある場合は、順序の指定に従って実行されます。
次へ進みます。
ファイルとして先ほどダウンロードしたSQLスクリプトのファイルを選択し、スクリプトの作成をクリックします。
インストール・スクリプトが作成されました。これで、アプリケーションのインストール時に表が作成されます。
削除スクリプトを開きます。
作成をクリックします。
最初から作成を選んで、次へ進みます。
以下の２行を記述し、作成をクリックします。外部キー制約が定義されているため、表GALLERY_CUSTOM_APPS_LANGを先にドロップします。
drop table gallery_custom_apps_lang;
drop table gallery_custom_apps;
削除スクリプトが登録されました。
サポートするオブジェクトを確認します。サポートするオブジェクトのページを開きます。
インストール・スクリプトと削除スクリプトが、それぞれ１つづつ作成されていることが確認できます。
アプリケーション定義を開き、バージョンを確認します。
インストールされたアプリケーションのバージョンと、ギャラリに登録されているアプリケーションのバージョンが異なると、インストール済みのカスタム・アプリケーションがアップグレード可能と通知されます。
以上の作業を行なったのち、アプリケーションをエクスポートします。
エクスポート/インポートを開きます。
エクスポートを選択し、次へ進みます。
ギャラリからインストールできるアプリケーションのエクスポート形式はZIPのみです。そのため、複数のファイルに分割は必ずONにします。せっかくサポートするオブジェクトも定義しているので、サポートするオブジェクトの定義をエクスポートははいにします。
その他の設定を調整し、エクスポートを実行します。
このファイルをGitHubにアップロードします。アップロードしたファイルをダウンロードするためのURLを確認しておきます。今回作成したアプリケーションは、以下のURLからダウンロードできます。
https://raw.githubusercontent.com/ujnak/apexapps/master/exports/gallery-custom-apps.zip
作成したアプリケーションを実行し、カスタム・アプリケーションを登録します。
以下は、今回の入力例です。
Internal Name: GALLERY_CUSTOM_APPS (カスタム・アプリケーションで一意になる文字列を指定します。）
Author: Yuji N （作成者です。）
Version: リリース1.0 （エクスポートしたアプリケーションに定義されているバージョンです。）
Icon: 空白 （表示するアイコンを指定します。）
URL: https://apexugj.blogspot.com/2022/07/gallery-custom-apps.html（詳細情報へのリンクです。）
Source: 空白 （SQL形式のアプリケーションのエクスポートです。アプリケーションのインストールにはZIPが使われるため、どのような場合に参照されるのか不明です。）
Zip: https://raw.githubusercontent.com/ujnak/apexapps/master/exports/gallery-custom-apps.zip （エクスポートされたアプリケーションです。）
License: 空白 （参考情報です。）
Apex Version: 22.1 （APEXのバージョンです。manifest.jsonには含まれません。）
Language: ja （アプリケーション・ビルダーが日本語のときに表示されます。英語であればenです。de、es、fr、it、pt-br、zh-tw、zh-cn、koも指定できます。）
Name: ギャラリへカスタム・アプリケーションを登録する （カスタム・アプリケーションの名前です。）
Description: ギャラリへカスタム・アプリケーションを登録するアプリケーションです。REST APIの実装は含みません。 （カスタム・アプリケーションの説明文です。）
以上を入力し、保存をクリックします。
登録されたカスタム・アプリケーションの情報を、JSON形式で出力するREST APIを作成します。
SQLワークショップからRESTfulサービスを呼び出します。
ORDSにスキーマが登録されていない場合は、以下の画面が表示されます。ORDSにスキーマを登録します。
スキーマ属性の保存をクリックします。
RESTfulサービス（REST API）の作成ができるようになりました。
最初にモジュールを作成します。
左のツリーよりモジュールを選択し、モジュールの作成をクリックします。
モジュール名、ベース・パスともにgalleryと入力し、モジュールの作成をクリックします。
モジュールgalleryが作成されました。続いて、テンプレートの作成を実施します。
テンプレートの作成をクリックします。
URIテンプレートappsが作成されました。最後にハンドラを作成します。
ハンドラの作成をクリックします。
メソッドとしてGET、ソース・タイプはMedia Resourceを選択します。ソースとして以下を記述します。
以上を設定して、ハンドラの作成をクリックします。
Oracle REST Data ServicesのREST APIで生のJSONを出力する方法については、米国オラクルのデータベース・ツール部門に所属しているPMのJeff Smithさんのブログ記事ORDS: Returning Raw {JSON}を参照しています。
作成したREST APIが返すJSONドキュメントを確認するため、完全なURLをコピーします。
ブラウザに完全なURLを入力し、レスポンスを確認します。
この情報を参照するように、APEXのインスタンス設定を変更します。
APEXの管理サービスにサインインします。
インスタンスの管理を開きます。
インスタンスの設定のアプリケーション・ギャラリのファイルURLとして、先ほどの完全なURLを追記します。
変更の適用をクリックします。
以上で、ギャラリのカスタム・アプリケーションの構成は完了です。
この記事の先頭のGIF動画で行っているように、アプリケーション・ビルダーよりギャラリにアクセスし、カスタム・アプリケーションのインストールや削除ができるようになっています。
Oracle APEXでは、サンプル・アプリケーションを提供するためにギャラリを利用していますが、企業などでの利用では、例えば会社のテーマを実装したアプリケーションや、認証スキーム、認可スキームといった共有コンポーネントが実装済みのアプリケーションを配布することにより、作成するAPEXアプリケーションの標準化を図るといった活用も考えられます。
補足
削除スクリプトの実行は、アプリケーション削除時に選択することができます。アプリケーションの削除時に、インストール時に作成された表が必ず削除されるわけではありません。
ギャラリのゴミ箱アイコンをクリックしたときは、必ず削除スクリプトが実行されます。要注意です。
アプリケーションのエクスポートは、CORSの対応ができていれば、どこでも配置できるようです。
完
