GitHubにAPEXアプリをエクスポートする(3) - アプリケーションの作成

 APEXアプリケーションをGitHubにエクスポートするアプリケーションを作成します。

最初にアプリケーション作成ウィザードを起動し、空のアプリケーションを作成します。

名前はアプリケーション・エクスポートとしました。

ページの作成

作成されたアプリケーションのホーム・ページに、ページ・アイテムを５つ、ボタンをひとつ作成します。

エクスポート対象のアプリケーションは、ポップアップLOVで選択します。選択したアプリケーションの別名をページ・アイテムP1_ALIASに設定するため、LOVは共有コンポーネントとして作成します。

LOVの名前はLOV_APPLICATIONとします。ソースとしてSQL問合せを選択し、SQL問合せとして以下を記述します。戻り値はAPPLICATION_ID、表示値はAPPLICATION_NAMEです。

select application_id, application_name, lower(alias) alias from apex_applications

追加表示列として、列ALIASを追加します。この通りでなくても構いませんが、表示可能はYes、検索可能はNoとしています。

エクスポートするアプリケーションを選択するページ・アイテムP1_APPLICATION_IDとして、タイプにポップアップLOV、設定の追加出力としてALIAS:P1_ALIASを指定します。ポップアップLOVで値を選択すると、列APPLICATION_IDの値がページ・アイテムP1_APPLICATION_IDの値になり、列ALIASの値がページ・アイテムP1_ALIASの値になります。

LOVのタイプとして共有コンポーネントを選択し、LOVにLOV_APPLICATIONを選びます。追加値の表示はOFF、NULL値の表示はON、NULL表示値として-- アプリケーションの選択 --を入力します。

ページ・アイテムP1_ALIASの値は、アプリケーションを選択すると自動的に設定されます。値の設定後に変更ができるよう、タイプはテキスト・フィールドにします。ページ・アイテムP1_APPLICATION_IDの右隣に配置されるよう、レイアウトの新規行の開始はOFFにします。

上書き許可のページ・アイテムP1_ALLOW_OVERWRITEのタイプに切替え（英語はSwitch）を選択します。このページ・アイテムの値はそのまま、PL/SQLのboolean値として扱うことができます。

こちらもレイアウトの新規行の開始はOFFにします。

コミットのメッセージを保持するページ・アイテムP1_COMMIT_MESSAGEのタイプとしてテキスト領域を選択します。

コミッターを保持するページ・アイテムP1_COMMIT_AUTHOR_NAMEのタイプはテキスト・フィールドです。

最後に送信ボタンB_EXPORTを作成します。動作のアクションはページの送信です。

以上でページは完成です。

置換文字列の設定

プロシージャEXPORT_APEX_APP_TO_GITHUBを呼び出す際に、APEX側で決定する固定値をアプリケーション定義の置換文字列として設定します。

アプリケーション定義を開き、置換のセクションを選択します。以下の置換文字列を設定します。

G_REPO_NAE = GitHubのリポジトリ名

G_CREDENTIAL = DBMS_CLOUD.CREATE_CREDENTIALで作成したクリデンシャル名 - 今回の例通りに作成しているとGITHUB_CRED

G_OWNER = GitHubのアカウント名

G_DIRECTORY = リポジトリのディレクトリ名。指定されたディレクトリ以下にAPEXアプリケーションをエクスポートする。

プロセスの作成

左ペインでプロセス・ビューを開き、プロセスの作成を実行します。

識別の名前をアプリケーションのエクスポートとします。タイプとしてAPEX 22.2より追加されたAPIの呼び出しを選択します。

設定のタイプとしてPL/SQL Procedure or Functionを選択します。今回はサンプルなのでプロシージャとして機能を実装していますが、製品レベルでの実装ではパッケージとして実装する（その場合はPL/SQL Packageを選択する）ことをお勧めします。

所有者はParsing Schema、プロシージャまたはファンクションとしてEXPORT_APEX_APP_TO_GITHUBを選択します。プロシージャが選択されると、そのパラメータがノードパラメータに一覧されます。

成功メッセージとしてアプリケーションがエクスポートされました。エラー・メッセージとしてアプリケーションのエクスポートに失敗しました。を設定します。エラーメッセージはプログラムからも設定できるので、もっと凝ったメッセージを出力することもできます。

プロシージャのパラメータに与える値を設定します。

p_repo_nameを選択します。パラメータの方向、データ型、デフォルトありはプロシージャ定義から決まります。APEXでサポートしているデータ型であれば、設定の変更が必要なケースは少ないでしょう。

値のタイプにアイテム、アイテムとしてG_REPO_NAMEを指定します。G_REPO_NAMEは実際は置換文字列なので、アイテムとして選ぶことはできません。直接、キーボードから入力します。

以上で置換文字列G_REPO_NAMEとして設定した値が、引数p_repo_nameに渡されます。

同様に、パラメータp_credential_nameにはG_CREDENTIAL、p_ownerにはG_OWNER、p_directoryにはG_DIRECTORY、p_allow_overwriteにはP1_ALLOW_OVERWRITE、p_application_idにはP1_APPLICATION_ID、p_aliasにはP1_ALIASを設定します。

パラメータのデータ型がBOOLEAN（今回はp_allow_overwrite）の際に、真偽値として使用する文字がデフォルトであると、True値とFalse値の指定を省略できます。

p_branch_nameを選択します。値のタイプとしてAPIデフォルトを選択します。プロシージャの引数に設定されているデフォルト値がp_branch_nameの値になります。

p_commit_detailsを除いて、他のパラメータはすべてAPIデフォルトを選択します。引数にデフォルト値が定義されていると、値のタイプのデフォルトはAPIデフォルトになります。

p_commit_detailsはDBMS_CLOUD_REPO.PUT_FILE等の引数p_commit_detailsとして与えられる値ですが、これはJSON文字列です。そのためページ・アイテムP1_COMMIT_MESSAGEとP1_COMMIT_AUTHOR_NAMEよりJSON文字列を作成し、その値をp_comitt_detailsに与えます。

p_commit_detailsの値のタイプとしてファンクション本体を選択し、言語はPL/SQLを選びます。PL/SQLファンクション本体として以下を記述します。

	declare
	l_commit_details_in_json clob;
	l_author_in_json varchar2(4000);
	begin
	-- メッセージがなければ、デフォルトのメッセージを使用する。
	if :P1_COMMIT_MESSAGE is null then
	return null;
	end if;
	-- コミッターにデフォルトはAPEXの開発者アカウントとする。
	l_author_in_json := json_object(
	key 'name'
	value
	case
	when :P1_COMMIT_AUTHOR_NAME is not null then
	:P1_COMMIT_AUTHOR_NAME
	else
	:APP_USER
	end
	);
	l_commit_details_in_json := json_object(
	key 'message' value :P1_COMMIT_MESSAGE,
	key 'author' value l_author_in_json format json
	);
	return l_commit_details_in_json;
	end;

view raw p_commit_details.sql hosted with ❤ by GitHub

以上でAPI呼び出しを行うプロセスの設定は完了です。

プロセスの実行後、ホーム・ページを再表示するためにブランチを作成します。タイプはページまたはURL(リダイレクト）、ターゲットとしてページ１を選択します。

以上でアプリケーションは完成です。

YAMLのGitHubへの保存が遅いのが気にはなります。とはいえYAMLファイルは非圧縮であるためファイル・サイズが大きい、またファイル数がそれなりにあることが原因で、APEX側で対応できないように思います。

プロシージャEXPORT_APEX_APP_TO_GITHUBの引数としてb_branch_nameがあり、コミットするブランチを指定できます。ただし、今回作成したAPEXアプリケーションでは常にmainを指定しています。

今のところAPEXではYAML形式のファイルをインポートすることはできません（p_typeの指定はREADABLE_YAMLです）。そのため、ブランチごとの変更をマージするのは、アプリケーション・デザイナーおよびページ・デザイナを使用して手動で行う必要があります。とはいえ、YAMLファイルを比較することでアプリケーションの違いを確認することはできます。アプリケーションがインストールされているインスタンスが異なるという場合など、YAMLファイルで差分を確認できると便利なことも多いでしょう。

今回の記事は以上になります。

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

完