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を選択します。ソースとして以下を記述します。
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| select 'application/json' | |
| , json_object(key 'customApps' value | |
| json_arrayagg( | |
| json_object( | |
| key 'internalName' value a.internal_name | |
| , key 'author' value a.author | |
| , key 'version' value a.version | |
| , key 'icon' value a.icon | |
| , key 'url' value a.url | |
| , key 'source' value a.source | |
| , key 'zip' value a.zip | |
| , key 'license' value a.license | |
| , key 'i18n' value l.i18n | |
| ) | |
| ) | |
| format json) as "manifest" | |
| from gallery_custom_apps a join | |
| ( | |
| select | |
| custom_app_id | |
| , json_objectagg( | |
| key language | |
| value json_object( | |
| key 'name' value name | |
| , key 'description' value description | |
| ) | |
| ) as i18n | |
| from gallery_custom_apps_lang group by custom_app_id | |
| ) l on a.id = l.custom_app_id |
以上を設定して、ハンドラの作成をクリックします。
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の対応ができていれば、どこでも配置できるようです。
完
