2021年2月19日金曜日

SQLclのapexコマンドによるアプリケーションの一括エクスポート

 以前にOracle APEXのアプリケーションのエスクポート・ファイルをコマンドラインから実行する(つまりアプリケーションとしてインポートする)方法について記事を書きました。

インポートする元となるアプリケーションのエクスポートを行う方法ですが、以下3つがあるでしょう。

  • アプリケーション・ビルダーの画面から行う。
  • APIのAPEX_EXPORT.GET_APPLICATIONを呼び出す。
  • SQLclのapex exportコマンドを使用する。

本記事ではSQLclのapex exportを実行して、ワークスペース内にあるすべてのアプリケーションを一度にエクスポートする方法を紹介します。

最初にSQLclを準備します。以下のURLにアクセスし、ダウンロードします。

https://www.oracle.com/database/technologies/appdev/sqlcl.html

SQLclはJavaで作られているので、実行するコンピューターにJavaをインストールしておく必要があります。

Javaが入っていれば、ダウンロードしたzipファイルを展開しbin/sql(またはsql.exe)を実行するとSQLclが使えるようになります。

$ ./sql


SQLcl: 金 2 19 14:47:10 2021のリリース20.4 Production


Copyright (c) 1982, 2021, Oracle.  All rights reserved.


ユーザー名 (''?) system

パスワード (**********?) ******

Last Successful login time: 金 2月  19 2021 14:47:18 +09:00


接続先:

Oracle Database 18c Express Edition Release 18.0.0.0.0 - Production

Version 18.4.0.0.0



SQL> alter session set container = xepdb1;


Sessionが変更されました。


SQL> 

コマンドライン・ツールとしては、sqlplusと大差ない(より高機能)です。

そしてSQLclには、apexのためのコマンドが含まれています。? apexまたはhelp apexで利用可能なコマンドが一覧されます。

SQL> ? apex

使用可能なオプション:

list:        データベースにインストールされているアプリケーションをリストします。

log:         APEX_WORKSPACE_LOG_SUMMARYからAPEXアプリケーションの使用状況をレポートします。

export:      APEXアプリケーションまたはワークスペース(あるいはその両方)をエクスポートします。

SQL> 

apex listによって作成されているアプリケーションがリストされます。

SQL> apex list

       WORKSPACE_ID                     WORKSPACE    APPLICATION_ID                                    APPLICATION_NAME       BUILD_STATUS          LAST_UPDATED_ON 

___________________ _____________________________ _________________ ___________________________________________________ __________________ ________________________ 

10                  INTERNAL                      4411              Oracle APEX  System Messages and Native Types       Run and Develop    09-OCT-20                

10                  INTERNAL                      4155              Scheme Authentication Login                         Run and Develop    09-OCT-20                

12                  COM.ORACLE.CUST.REPOSITORY    8842              Universal Theme Sample Application                  Run and Develop    24-SEP-20                

10                  INTERNAL                      4000              Oracle APEX AppBuilder                              Run and Develop    19-JAN-21                

10                  INTERNAL                      4020              Oracle APEX - Create App Wizard                     Run and Develop    22-OCT-20                

10                  INTERNAL                      4350              Oracle APEX Workspace Administration                Run and Develop    19-JAN-21                

10                  INTERNAL                      4050              Oracle APEX Internal Administration                 Run and Develop    19-JAN-21                

10                  INTERNAL                      4550              Oracle APEX Login                                   Run and Develop    22-OCT-20                

10                  INTERNAL                      4600              Oracle APEX Issues                                  Run and Develop    22-OCT-20                

10                  INTERNAL                      4650              Oracle APEX Feedback                                Run and Develop    22-OCT-20                

10                  INTERNAL                      4700              Oracle APEX New Service Signup                      Run and Develop    09-OCT-20                

10                  INTERNAL                      4750              Oracle APEX Productivity and Sample Applications    Run and Develop    22-OCT-20                

10                  INTERNAL                      4500              Oracle APEX SQL Workshop                            Run and Develop    22-OCT-20                

10                  INTERNAL                      4300              Oracle APEX Data Workshop                           Run and Develop    22-OCT-20                

10                  INTERNAL                      4400              Oracle APEX Application Migration                   Run and Develop    19-JAN-21                

10                  INTERNAL                      4900              Oracle APEX Websheets                               Run and Develop    09-OCT-20                

10                  INTERNAL                      4850              Oracle APEX RESTful Services                        Run and Develop    22-OCT-20                

2728471333018836    APEXDEV                       101               Employees                                           Run and Develop    09-FEB-21                

2728471333018836    APEXDEV                       104               Sample Trees                                        Run and Develop    09-FEB-21                

2728471333018836    APEXDEV                       103               Tasks                                               Run and Develop    09-FEB-21                

2728471333018836    APEXDEV                       102               Material APEX - Demo                                Run and Develop    27-SEP-18                

2728471333018836    APEXDEV                       100               PL/SQL Gateway                                      Run and Develop    09-FEB-21                


SQL> 

こうして見ると、普段、アプリケーションを開発するときに使用しているアプリケーション・ビルダーやその他の機能自体がAPEXで作られたアプリケーションであることがよくわかります。

一番左にワークスペースIDが表示されています。apex exportコマンドに-instanceオプションと-workspaceid ワークスペースIDをつけて実行することで、指定したワークスペースに含まれるすべてのアプリケーションがSQLファイルとしてエクスポートされます。

SQL> apex export -instance -workspaceid 2728471333018836

Exporting Application 100:'PL/SQL Gateway' 

Exporting Application 101:'Employees' 

Exporting Application 102:'Material APEX - Demo' 

Exporting Application 103:'Tasks' 

Exporting Application 104:'Sample Trees' 

Exporting Application 8842:'Universal Theme Sample Application' 

SQL> 

実際に作成されたファイルを確認します。

SQL> !

$ ls *.sql

f100.sql  f101.sql  f102.sql  f103.sql  f104.sql  f8842.sql

$ 

apex exportのみで実行すると、使用可能なオプションが一覧されます。画面から設定できる内容は一通り指定可能です。

SQL> apex export

使用可能なオプション:

-applicationid:        エクスポートされるアプリケーションのID

-workspaceid:          エクスポートされるすべてのアプリケーションまたはエクスポートされるワークスペースのワークスペースID

-instance:             すべてのアプリケーションをエクスポートします

-expWorkspace:         -workspaceidで識別されるワークスペース、または-workspaceidが指定されていない場合はすべてのワークスペースをエクスポートします

-expMinimal:           ワークスペース定義、ユーザーおよびグループのみをエクスポートします

-expFiles:             -workspaceidで識別されるすべてのワークスペース・ファイルをエクスポートします

-skipExportDate:       アプリケーション・エクスポート・ファイルからエクスポート日付を除外します

-expPubReports:        ユーザーが保存したすべてのパブリック対話型レポートをエクスポートします

-expSavedReports:      ユーザーが保存したすべての対話型レポートをエクスポートします

-expIRNotif:           すべての対話型レポート通知をエクスポートします

-expTranslations:      変換リポジトリから、変換マッピングとすべてのテキストをエクスポートします

-expFeedback:          すべてのワークスペースのチーム開発フィードバック、または-workspaceidで識別されるチーム開発フィードバックをエクスポートします

-expTeamdevdata:       すべてのワークスペースのチーム開発データ、または-workspaceidで識別されるチーム開発データをエクスポートします

-deploymentSystem:     エクスポートされるフィードバックのデプロイメント・システム

-expFeedbackSince:     YYYYMMDDという書式の日付以降のチーム開発フィードバックをエクスポートします

-expOriginalIds:       アプリケーションのインポート時のIDが、エクスポートにそのまま表示されます

-expNoSubscriptions:   サブスクライブされたコンポーネントへの参照はエクスポートされません

-expComments:          開発者コメントをエクスポートします

-expSupportingObjects: はい(Y)、いいえ(N)またはインストール(I)を渡して、デフォルトをオーバーライドします

-expACLAssignments:    ACLユーザー・ロール割当てをエクスポートします

-dir:                  指定されたディレクトリ(-dir some/sub/directoryなど)にあるすべてのファイルを保存します

-list:                 アプリケーションのワークスペースまたはコンポーネントにある変更されたすべてのアプリケーションをリストします

-changesSince:         日付パラメータ(yyyy-mm-dd)が必要です。-listの値を指定された日付以降の変更に制限します

-changesBy:            文字列パラメータが必要です。-listの値を指定されたユーザーによる変更に制限します

-expComponents:        アプリケーション・コンポーネントをエクスポートします。残りのパラメータはすべて、TYPE:IDという形式にする必要があります

-debug:                デバッグ出力を印刷します

-nochecksum:            コンテンツが変更されていない場合でも、既存のファイルを上書きします

-split:                アプリケーションを複数のファイルに分割します


その他にもアプリケーションを指定して、指定した日付以降に変更されたコンポーネントの一覧を表示したり、

SQL> apex export -applicationid 100 -list -changesSince 2021-02-09

2021-02-09 10:11 BREADCRUMB:2833396906901945             Breadcrumb

2021-02-09 10:11 BREADCRUMB_ENTRY:3130962713923428       Breadcrumb: 動的コンテンツ (2)

2021-02-09 10:11 LIST:2833809654901965                   デスクトップ・ナビゲーション・メニュー

2021-02-09 10:16 PAGE:2                                  2. 動的コンテンツ

Date             ID                                      Name

---------------- --------------------------------------- -----------------------

SQL> 


特定のコンポーネントのみエクスポートすることもできます。

SQL> apex export -applicationid 100 -expComponents SHORTCUT:2976483336902675

Exporting Application 100

SQL> 


以上、SQLclのapex関連コマンドの紹介でした。

完

ページの読取り専用の働きについて

 Oracle APEXのアプリケーションを読取り専用にしたい、との質問があって「何かスイッチがあって、ポンとONにしたらできる、というものはないだろう。」と思っていたら、ページのプロパティの読取り専用を設定すればよい、と伺いました。

初めて聞いたので確認してみました。

結論としては、ページの読取り専用の設定は、ページ・アイテムを一括で読取り専用にする設定であり、プロセスの実行を妨げる(行の自動処理 - 表への挿入/更新/削除)ものではありませんでした。

以下、確認のために行った作業を記録します。

サンプルでよく使われるEMP/DEPT表の、EMP表を編集するフォームのページを読取り専用にします。

読取り専用のプロパティを常時にしていますが、色々な条件に基づいて読取り専用にすることができます。

アプリケーションを実行して、効果を確認します。従業員を選んで、フォームを開きます。

開かれたフォームのページが読取り専用になっています。入力フィールドの変更ができなくなっていることが確認できます。削除のボタンをクリックしてみます。


OKをクリックします。


部下を持っている従業員であれば、整合性制約のエラー(0RA-2292)が発生することもありますが、従業員は削除されます。

スクリーンショットでは従業員ADAMSを削除しました。以下の画面からADAMSは削除されています。作成をクリックします。


ページ・アイテムは読取り専用なので、すべて入力できません。何も入力せず、作成をクリックします。


空白行が追加されています。


ページ・アイテムの変更はできませんが、変更の適用をクリックしたときも、同じ値で表のアップデートは実行されるでしょう。表に監査列が追加されていて、トリガーによって更新をしている場合は、監査列の情報が更新されるはずです。

以上です。

Oracle APEXのアプリケーション開発の一助になれば幸いです。

完

2021年2月18日木曜日

動的アクションのクライアント側の条件を定義する

 動的アクションのクライアント側の条件が動かない、との相談を受けました。少々確認が必要だったので、その作業を記録します。

クライアント側の条件のタイプとしてアイテム = 値を指定したときに、アイテムが選択リスト(LOV)だった場合、値としては画面に表示される値を指定するのか、ページ・アイテムとして保存される値を指定するのか?という点を確認しました。

結果としては、ページ・アイテムとして保存される値です。LOVの設定としては表示値ではなく戻り値の方です。

確認のためにアプリケーションを作りました。

空のアプリケーション(名前をDA Client Side Conditionとしました)を作成し、ホーム・ページに静的コンテンツのリージョン(名前をCountry and Statesとしました)を追加します。

国を選択するページ・アイテムをP1_COUNTRYとして作成し、タイプを選択リストにします。ラベルにはCountryを設定します。

LOVのタイプを静的値、追加値の表示はOFF、NULL表示値は- Choose Country -を指定します。

LOVの静的値として以下の3つを設定しました。

  • 表示値: United States、戻り値: US
  • 表示値: Japan、戻り値: JP
  • 表示値: Romania、戻り値: RO

一般的には、国情報はISO 3166に基づいたLOVを、共有コンポーネントにしている場合が多いと思います。

次に、州を入力するページ・アイテムP1_STATESを作成します。これは動的アクションにて表示、非表示にするためだけに使用するので、州の一覧を選択リストにするといった凝ったことは行いません。ラベルはStatesと設定します。

国としてUnited Statesが選択されたときにページ・アイテムP1_STATESを表示し、そうで無い時は表示しない動的アクションを定義します。

名前をActivate Statesとし、タイミングはイベントが変更、選択タイプはアイテム、アイテムはP1_COUNTRYとします(P1_COUNTRYにたいして動的アクションの作成を行うと、デフォルトでこのタイミングになるはずです)。

クライアント側の条件はタイプがアイテム = 値、アイテムがP1_COUNTRY、値はUSとします。

Trueアクションとして、識別のアクションが表示、影響を受ける要素として、選択タイプをアイテム、アイテムをP1_STATESとして、アクションを作成します。

作成したTrueアクションにたいして、反対のアクションの作成を実行すると、ページ・アイテムP1_STATESを非表示にするFalseアクションが作成されます。

以上で動作を確認するためのアプリケーションが作成できました。アプリケーションを実行すると、最初のGIF動画の動作が確認できると思います。

作成したアプリケーションのエクスポートを以下に置きました。

https://github.com/ujnak/apexapps/blob/master/exports/daclientsidecondition.sql

Oracle APEXのアプリケーション開発の一助になれば幸いです。

完

2021年2月17日水曜日

管理サービスと開発者ログインの禁止

 Autonomous DatabaseはRestrictions and Limitations for Oracle Application Express with Autonomous Databaseに記載のあるように

  • Oracle Application Express is only available as a Full Development environment. Converting into a Runtime environment is not supported.

ということで、実行環境のみの構成はできず、必ず管理サービスと、ワークスーペースにサインインしてアプリケーションの開発を行う機能が含まれます。もちろん便利なのですが、アカウントの有無にかかわらず、誰でもサインイン画面を開くことができる、というのは、やはり心配です。

たまたま、APEX_INSTANCE_ADMINパッケージのSET_PARAMETERプロシージャにて使用可能なパラメータの一覧を見ていたら、

  • DISABLE_ADMIN_LOGIN
  • DISABLE_WORKSPACE_LOGIN

というパラメータが目に止まりました。それぞれ、

  • Yに設定すると、管理サービスは無効化されます。デフォルトのNに設定すると、無効化されません。
  • Yに設定すると、ワークスペース・ログインは無効化されます。デフォルトのNに設定すると、ログインは無効化されません。

とのことです。Autonomous Databaseでも管理サービスと開発者ログインを禁止できそうです。

確認してみました。

SQL Developer WebにADMINでサインインし、管理サービスを禁止しました。

begin
    apex_instance_admin.set_parameter('DISABLE_ADMIN_LOGIN','Y');
    commit;
end;

管理サービスにアクセスすると、不当なアクセスです。と表示されるようになりました。サインインの画面さえ表示されません。

同様に開発者ログインを禁止しました。
begin
    apex_instance_admin.set_parameter('DISABLE_WORKSPACE_LOGIN','Y');
    commit;
end;
ワークスペースにアクセスすると、不当なアクセスです。と表示されるようになりました。サインインの画面さえ表示されません。

セキュリティ上の懸念がある場合は両方とも禁止すべきか、少なくても、開発をしていないときは一時的にでも禁止しておくべきなので、積極的に使用したい機能です。

完

自律トランザクションを使ってデータベース操作のログを取得する

 Oracle APEXのアプリケーションで、操作のログはどのように残すのですか?と質問を受けました。

アプリケーションに依存したもので無ければ、Oracle APEXのアプリケーションへのアクセスは、ワークスペース・ユーティリティのApplication Expressビューとして提供されているAPEX_WORKSPACE_ACTIVITY_LOGから参照できます。

ログの保持期間はデフォルトで28日(ログを保存する2つの表が14日毎に切り替わるため)で、パフォーマンスに影響が出るため延長は推奨されていません。とはいえ、変更方法ですが、オンプレのインストールの場合はOracle APEXの管理アプリケーションにサインインし、インスタンスの管理を開きます。

ログとファイルの管理よりログ間隔の管理を開きます。

ログ情報を保持する最小日数の指定ができます。

対応する画面がない環境では、APIの呼び出しによって変更が可能です。APEX_INSTANCE_ADMINパッケージに含まれるSET_LOG_SWITCH_INTERVALプロシージャを使用します。

アプリケーションで発生したエラーも標準でログに記録されていて、アクティビティのモニターからアプリケーション・エラーを開くことで参照できます。

いつ、誰が、どのページで、どのコンポーネントで、どのようなエラーが発生したのか、などを確認することができます。

標準のログについては以上です。

本記事の本題である、カスタムのログ取得について紹介します。

確認のためにクイックSQLの以下のモデルにて、表TTX_ACTIVITY_LOGとTTX_OPERATIONSを作成します。

# prefix: ttx
# semantics: default
activity_log
operation vc400
operation_date date /default sysdate

operations
name vc20
value vc20

アプリケーション・ビルダーより、空のアプリケーションを作成します。名前はサンプルログ記録としました。

アプリケーションが作成できたら、ホーム・ページをページ・デザイナで開き、3つのリージョンをContent Bodyに追加します。

最初にタイトルをDB操作、タイプを静的コンテンツとしてリージョンを作成します。


リージョン内に3つのページ・アイテムを作成します。名前をそれぞれP1_TX1、P1_TX2、P1_TX3とし、ラベルもそれぞれTX1、TX2、TX3とします。P1_TX1での設定は以下になります。


ページ・アイテムを送信するためのボタンを作成します。ボタン名をB_SUBMITとし、ラベルを送信にします。


静的コンテンツのリージョンについては以上で作成完了です。

続いて対話モード・レポートのリージョンを作成します。タイトルとしてOPERATIONSを設定し、タイプは対話モード・レポート、表名としてTTX_OPERATIONSを選択します。


同様にタイトルがACTIVITY_LOG、タイプが対話モード・レポート、表名がTTX_ACTIVITY_LOGのリージョンを作成します。


画面の開発は以上で完了です。ページを実行すると以下の画面が表示されます。

ページ・デザイナに戻り、プロセスを3つ追加します。以下のコードを実行します。名前はProcess TX1とし、タイプはコードを実行を選びます。TX2、TX3については、それぞれTX1の部分をTX2、TX3に変更します。

declare
l_log varchar2(400);
begin
l_log := :REQUEST || 'が押されたのでTX1の値' || :P1_TX1 || 'を保存します。';
insert into ttx_activity_log(operation) values(l_log);
insert into ttx_operations(name, value) values('TX1', :P1_TX1);
end;


ページ・アイテムP1_TX1、P1_TX2、P1_TX3の値を受け取って、表TTX_OPERATIONSにデータを挿入し、同時に操作を表TTX_ACTIVITY_LOGに書き込むようになりました。

この状態で実行します。TX1、TX2、TX3に値を指定し、送信ボタンをクリックします。


以下のようにレポートが表示されます。データが保存され、操作も記録されています。きちんと動いているように見えます。


今度はTX3に20バイトを超えるデータを指定します。想定どおりエラーORA-12899: 列"APEXDEV"."TTX_OPERATIONS"."VALUE"の値が大きすぎます(実際: 180、最大: 20)が発生し、データベースへの書き込みは行われません。


表の内容をみるとページ・アイテムP1_TX1、P1_TX2、P1_TX3の値が保存されていないのは想定どおりなのですが、操作も記録されていません。操作の記録はエラーの発生によらず、記録されている必要があります。


そのため、ログを保存する操作は自律トランザクションとして、本体とは異なるトランザクションを開始する必要があります。

次のプロシージャを作成します。pragma autonomous_transaction句を含めることで、独立したトランザクションが開始されます。プロシージャの終了前にcommitすることで、このプロシージャを呼び出したトランザクションがrollbackしても、この書き込みは永続化されます。

create or replace procedure ttx_log_operation
(
p_operation in varchar2
)
as
pragma autonomous_transaction;
begin
insert into ttx_activity_log(operation) values(p_operation);
commit;
end ttx_log_operation;

プロセスに記述したコードを以下に変更します。表TTX_ACTIVITY_LOGへのINSERT文をプロシージャTTX_LOG_OPERATIONの呼び出しに変更します。TX2、TX3についても同様の変更を行います。

declare
l_log varchar2(400);
begin
l_log := :REQUEST || 'が押されたのでTX1の値' || :P1_TX1 || 'を保存します。';
ttx_log_operation(l_log);
insert into ttx_operations(name, value) values('TX1', :P1_TX1);
end;

先ほど失敗したエラーになった操作を再実行すると、レポートの表示は以下に変わります。

データが保存されていないのは同様ですが、Operationには、プロセス自体が呼び出されていることが分かる操作ログを確認できます。

以上で、自律トランザクションを使ったデータベースへのログ書き込み方法の紹介は終了です。

 確認に使用したアプリケーションのエクスポートを以下に置きました。

https://github.com/ujnak/apexapps/blob/master/exports/samplelogging.sql

Oracle APEXのアプリケーション開発の一助になれば幸いです。

完