2023年8月8日火曜日

組み込みパラメータのX01を活用する

 Oracle APEXのドキュメントApp Builder User's Guideの3.8.1.1 About Friendly URL SyntaxにAbout URL Parametersというセクションがあります。

https://docs.oracle.com/en/database/oracle/apex/23.1/htmdb/understanding-friendly-url-syntax.html

そこに以下の記載があります。

Supported parameters include:

  • session
  • request
  • clear
  • debug
  • application/page items
  • printerFriendly
  • trace
  • timezone
  • lang
  • territory
  • cs
  • dialogCs
  • x01

ある程度Oracle APEXを使用している方であれば、これらの組み込みパラメータの意味は名前から大体の予想が付きますが、x01については予想がつかない方が多いのではないかと思います。

URLの一部としてx01=値が渡されると、呼び出されたページではアイテムAPP_AJAX_X01としてx01として渡された値を参照することができます。この際にURLパラメータx01は、チェックサムの検証対象から除外されます。つまり、呼び出し元でx01の値を変更しても、チェックサムが一致しないというエラーは発生しません。

以下、この特殊なパラメータx01の活用方法について紹介します。

使い方を理解するためにAPEXアプリケーションを作成してみます。

アプリケーション作成ウィザードを起動します。アプリケーションの名前はX01 Parameterとします。ページの追加をクリックし、空白のページを追加します。ページ名はtargetとします。

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


アプリケーションが作成されます。


ページ・デザイナにてページtargetを開きます。

外部から直接このページを呼び出せるように、セキュリティのディープ・リンクを有効にします。


このページにページ・アイテムを２つ作成します。

ページ・アイテムP2_Qを作成します。タイプはテキスト・フィールド、ラベルはQとします。セキュリティのセッション・ステート保護はチェックサムが必要 - アプリケーション・レベルを選択します。


ページ・アイテムP2_Aを作成します。タイプはテキスト・フィールド、ラベルはAとします。セキュリティのセッション・ステート保護は制限なしを選択します。


それでは、このページを呼び出す直リンクを生成してみます。

ページ・デザイナにてホーム・ページを開きます。ナビゲーションのリージョンは使用しないので削除します。

ページ・アイテムP1_Qを作成します。このページ・アイテムの値をP2_Qに渡すように直リンクを生成します。


直リンクを保持するページ・アイテムP1_URLを作成します。


直リンクを生成するボタンGET_URLを作成します。動作のアクションとして動的アクションで定義を選択します。


ボタンGET_URLに動的アクションを作成します。

作成した動的アクションの識別の名前はURLを生成とします。タイミングのイベントはデフォルトのクリックです。


TRUEアクションとしてサーバー側のコードを実行を選択します。設定のPL/SQLコードとして以下を記述します。

declare
p_url varchar2(800);
begin
-- ページ・アイテムP2_AはURLの生成に含めません。
p_url := apex_page.get_url(
p_page => 2
,p_items => 'P2_Q'
,p_values => :P1_Q
);
-- 引数からsession情報を除く
p_url := regexp_replace(p_url, 'session=[0-9]+&','');
:P1_URL := apex_util.host_url || p_url;
end;
view raw generate-direct-url.sql hosted with ❤ by GitHub
送信するアイテムとしてP1_Q、戻すアイテムとしてP1_URLを指定します。


それでは、直リンクによるアクセスを確認します。

アプリケーションを実行します。

Qにtestと入力し、ボタンGet Urlをクリックします。

URLに直リンクが表示されます。末尾は以下のようになっています。

x01-parameter/target?p2_q=test&cs=1G2nHTlVsgM3WYV6oB92_nTDJTO67_eU_00haOdbdmRISVcPGDJlehpjvLLavROzKa0r2RMNyPVeH37vFcaQ9Fg

このURLを（APEXセッションを共有しない）別のブラウザで開いてみます。

ユーザー認証を求められた後、以下のようにページtargetが表示されます。P1_Qの値がP2_Aに渡されています。


ここでP2_Aの値をURLから直接指定してみます。URLパラメータとしてp2_a=yesを含めます。

x01-parameter/target?p2_q=test&p2_a=yes&cs=1G2nHTlVsgM3WYV6oB92_nTDJTO67_eU_00haOdbdmRISVcPGDJlehpjvLLavROzKa0r2RMNyPVeH37vFcaQ9Fg

結果として、以下のエラーが発生します。


ページ・アイテムP2_Aとその値yesを、APEX_PAGE.GET_URLの引数に含めるとp2_a=yesのときはエラーなくP2_Aにyesが渡りますが、この値をnoに変更すると上記と同じエラーが発生します。

ページ・プロパティのセキュリティのページ・アクセス保護を制限なしにし、ページ・アイテムP2_Qについてもセッション・ステート保護を制限なしにすると、チェックサムのエラーは発生しなくなりますが、外部から自由にパラメータP2_QとP2_Aの値を指定できるようになってしまいます。

ここでx01を使用します。p2_a=yesの代わりにx01=yesをURLに含めます。

x01-parameter/target?p2_q=test&x01=yes&cs=1G2nHTlVsgM3WYV6oB92_nTDJTO67_eU_00haOdbdmRISVcPGDJlehpjvLLavROzKa0r2RMNyPVeH37vFcaQ9Fg

Aに値が渡るわけではありませんが、チェックサムのエラーは発生しません。x01はチェックサムの計算から除外されているためです。


ここで、ページtargetのレンダリング前にプロセスを作成し、アイテムAPP_AJAX_X01（x01として渡されている値）がnullでなければ、ページ・アイテムP2_Aに代入するようにします。

識別の名前はX01をP2_Aに渡すとし、ソースのPL/SQLコードとして以下を記述します。

:P2_A := :APP_AJAX_X01;

サーバー側の条件のタイプとしてアイテムはNULLではないを選択し、アイテムとしてAPP_AJAX_X01を指定します。


以上で動作を確認してみます。

以下のようにx01=yesをURLに挿入して、別ブラウザでページtargetを呼び出してみます。

x01-parameter/target?p2_q=test&x01=yes&cs=1G2nHTlVsgM3WYV6oB92_nTDJTO67_eU_00haOdbdmRISVcPGDJlehpjvLLavROzKa0r2RMNyPVeH37vFcaQ9Fg

Aにyesが設定されています。

同様にx01=noに変更して、別ブラウザでページtargetを呼び出してみます。

x01-parameter/target?p2_q=test&x01=no&cs=1G2nHTlVsgM3WYV6oB92_nTDJTO67_eU_00haOdbdmRISVcPGDJlehpjvLLavROzKa0r2RMNyPVeH37vFcaQ9Fg

Aにnoが設定されています。


例えばワークフローなどの通知にAPEXのページへの直リンクを含む場合など、メールの本文中に回答がyesとnoの場合のそれぞれのリンクを含めるといったことを容易に実装できます。

パラメータx01の紹介は以上になります。

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

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

完
投稿者 時刻:
ラベル: