Oracle AnalyticsをOracle Application Express(APEX)に組み込むためのガイド (2022/10/29)

Oracle AnalyticsをOracle Application Express(APEX)に組み込むためのガイド (2022/10/29)

https://medium.com/oracledevs/a-guide-to-embedding-oracle-analytics-into-oracle-application-express-apex-1799f6ba4626

投稿者:Mike Durran

Oracle Application Express(APEX)


Oracle Application Express(APEX)は、独自のアプリケーションを簡単に作成できるローコード開発環境です。先日のイベント「Oracle Cloud World」('22)では、APEXを使って世界的なパンデミックに対応するアプリケーションを迅速に作成し、基調講演の1つで紹介されました。


このページにたどり着いた方は、すでにAPEXについてご存じだと思いますが、なぜOracle Analytics Cloud(OAC)をAPEXに組み込もうと思ったのか、疑問に思われるかもしれませんね。実は、2019年のあるカンファレンスで、私はまさにその質問を受けました。APEXにはすでに豊富なレポート機能と可視化機能があり、それらの可視化の多くはOracle JET(両製品とも)をベースにしているからです。


私の回答は?APEXとOACは補完関係にある製品で、利用できる可視化の種類に重複がありますが、もう一方の製品にも追加機能を提供しており、結果としてデータエンジニアとビジネスエンドユーザーの両方にとってより包括的なユーザーエクスペリエンスとなります。


以下にいくつかの例を挙げますので、後で詳しく説明します。


  •     APEX アプリケーションに OAC 自然言語生成またはタグクラウドを追加。
  •     APEXのファセット検索を使用して、組み込まれたOACキャンバスにフィルターを定義する機能。
  •     OACのセルフサービスデータ準備、エンリッチメント、ML統合は、APEXで構築されたアプリケーションの分析能力を強化することができます。


他にも挙げればきりがありませんが、全体として、これら2つの製品を一緒に使うことは検討する価値があると思います。このブログでは、この組み合わせから最高のものを得る方法について詳細を説明します。



製品バージョンが重要な理由


このブログの冒頭でOracle JETについて触れました。これはAPEXとOACを連携させる上で重要なポイントです。ここでは、各製品が使用しているJETのバージョンを確認する方法を紹介します。


APEXの場合、通常、製品ドキュメントに記載されています。このブログを作成するために使用しているバージョンは 21.2 (JET 11) と 22.1 (JET 12)である。APEX のドキュメントには、JET の使用方法も記載されており、バージョン 22.1 では「チャート」リージョンタイプだけでなく「オートコンプリート付きテキストフィールド」アイテムタイプも記載されています。これは、APEX に OAC コンテンツを埋め込む方法に影響を与えます。なぜなら、同じアプリケー ションページに異なるバージョンの JET を混在させると、予期せぬ結果を招く可能性があるからです。


Oracle Analytics で使用されている JET のバージョンを調べるには、Analytics にログインした状態で、ブラウザの開発者ツールコンソールを開き、以下を実行します。


requirejs('ojs/ojcore').version


このブログを書いている間は、Oracle Analytics Cloudの22年9月版と22年11月版を使用しており、使用したJETのバージョンは11.1.0です。



Oracle Analyticsの埋め込みスクリプト


OACの「Developer」オプションを有効にした後(Profile | Advanced menu optionsで設定します)、OACの「Embed」セクションを含む開発者エリアを表示することができます。

Oracle Analytics Developer Embedセクション


embedding.js のリンク先には、Oracle JET を使用しないアプリケーションに埋め込む場合に使用する /standalone/ と、Oracle JET を使用するアプリケーションに使用する /jet/ の2つのオプションが用意されています。APEX のドキュメントで見てきたように、APEX のある部分は JET を使い、ある部分は使いません。後ほど、APEX アプリケーションを開発する際にこれがどのように考慮され、OAC Canvases をどのように組み込むかについて見ていきます。



認証


APEXは、Oracle APEX Accounts のデフォルトで、アプリケーションを保護するために認証スキームを使用します。Oracle Analytics Cloudでは、Oracle Identity Cloud Service (IDCS) 認証を使用します。


この段階では、エンドユーザーが APEX アプリケーションにログインし、埋め込まれた分析コンテンツにもログインすることを要求するようにするか (APEX アプリケーション内で埋め込まれた分析へのアクセスを制限したい場合はそうします)、APEX アプリケーションにログインしたユーザーが分析コンテンツにも認証されるようなシームレスな認証体験を求める可能性が高くなります。これは、APEX 内でアナリティクスと同じ Oracle IDCS を使用する 'Web Credentials' と 'Authentication Scheme' を作成することで実現できます。以下に、IDCS認証のためのAPEXの設定方法を説明した記事へのリンク(1)(2)(3)を示します。


アナリティクスを埋め込んだリージョンで、まだログインプロンプトが表示され、<oracle-dv> HTML 埋め込み方法を使用している場合、embedding.js へのリンクに以下を追加する必要があるかもしれません。


<script src=""https://<instance>.analytics.ocp.oraclecloud.com/public/dv/v1/embedding/standalone/embedding.js?IDCS_OAUTH3LEGGED=true" type="application/javascript">
</script>


Oracle AnalyticsワークブックへのURLリンクの埋め込み


APEXアプリケーションにOracle Analyticsのコンテンツを追加する最も簡単な方法は、次のようにワークブックのURLを参照することです。


  •     OACで、埋め込みたいキャンバスを開いたまま、URLをコピーします。
  •     APEXで、新しい静的コンテンツリージョンを作成し、タイプにURLを選択し、「属性」をクリックして、「インクルードモード」に「iFrame」を選択します。
  •     OAC からコピーした URL を 'URL' フィールドに貼り付け、オプションで iFrame の属性(例:幅と高さ)を設定します。


APEX で表示されるキャンバスのビューは、お客様の要件に合わせて調整可能な多くの要因に依存します。


  •     IDCS 認証を使用するように APEX を設定し、OAC Author アプリケーション ロールを持つユーザーとして APEX アプリにログインした場合、APEX に埋め込まれた完全なオーサリング UI が表示される場合があります。埋め込み OAC の URL に以下を追加することで変更可能です。


&viewermode=true


  •     OACビューアーのアプリケーションロールを持つユーザーとしてAPEXにログインすると、ビューアーエクスペリエンスが表示されます。


9月22日および11月22日にリリースされたOACでは、この体験をさらにカスタマイズできる設定があります。


  •     OACプロファイル設定の詳細メニューにある「ワークブックをビューアーとして開く」トグル。デフォルトでは、これは有効になっており、もしあなたがDV著者ロールを持っているならば、APEXで「ビューア」モードのコンテンツが表示されます。これにより、埋め込みコンテンツに対してより良いユーザーエクスペリエンスを提供します。
  •     OAC UIの'Present'セクションで定義されたストーリーページがあるかどうか。
  •     ストーリーページがある場合、インタラクティブ設定、コンテキストメニューアクション、ヘッダーバーの表示/非表示を変更できます。


ヘッダーバーを表示せず、ビューアのユーザービューを表示することで、最もシームレスなエンベッディングエクスペリエンスを提供します。


Oracle Analytics JavaScriptエンベッディングの使用


Oracle Analytics JavaScript 埋め込みフレームワークを使用すると、APEX アプリケーションの分析コンテンツに対してより統合されたユーザーエクスペリエンスを提供することができます。ここで、APEX と OAC で使用されている Oracle JET のバージョンが重要になります。さらに、JET を使用する APEX コンポーネント(例:APEX チャート)がアプリケーションページにあるかどうかは、予想外の動作(例:一部の OAC 視覚化が完全に表示されないか、特に /standalone/ パスを使用している場合は CSS 衝突が生じる可能性があります)を引き起こす可能性があります。



OAC と APEX が同じ JET バージョンで動作している場合


このシナリオでは、APEX のページレベルの 'JavaScript' フィールドに以下を設定します。embedding.js への /jet/ パスの使用に加えて [require jet] に注意してください。



通常の requirejs の依存関係と knockout の適用バインディングは、埋め込まれた分析を見るために必要ないかもしれないことに注意してください。


次に、APEX の静的コンテンツリージョンの 'Source' フィールドに <oracle-dv> タグを追加します。



embedding.jsのパスを/standalone/とした場合、JavaScriptセクションの[require jet]は必要ありません。



異なる JET バージョンにおける OAC と APEX


異なる JET バージョンが存在する場合、OAC コンテンツを埋め込みたいページと同じ アプリケーションページ上に他のどの APEX アイテムが存在するかに依存します。アプリケーションページ上の APEX アイテムが JET を使用していない場合、/jet/ パスを使用することができますが、それでもすべての OAC 視覚化タイプがレンダリングされないことがあるかもしれません。


一般的に、異なる JET バージョンが存在する可能性を考慮すると、分析を埋め込むための最も信頼できる方法は、iFrame を使用することです。この方法については、セレクタやファセット検索などのAPEX UIコントロールからウィンドウズメッセージを使ってiFrameにパラメータを渡す方法など、このブログで書きましたので、OACとAPEXを一緒に使うことの本当の利点が実感できるところです。



データソース


OACとAPEXは同じデータソースを使用するのが理想的である。OACとAPEXの両方にデータを取り込むのは簡単で、APEXの場合はDBのテーブルにアップロードしたXLSファイルを使用するか、アップロードしたXLSからOACでデータソースを作成するか、DBへの接続を作成してから適切なデータソースを作成します。


同じデータソースを使用する場合、APEX がアプリケーションデータを格納するために使用するスキーマに OAC から接続する必要がある場合がほとんどです。私の例では、このライブラボからニューヨークの学校のデータを使用して構築されたAPEXアプリケーションを使用します。


ライブ ラボに従ってデータがアップロードされ、APEX アプリケーションが作成されていることを前提に説明します。また、APEX がアプリケーションに使用するスキーマへの接続とデータソースを OAC で作成しておく必要があります。これは、APEX の SQL ワークショップを使用して発見することができます。APEXで使用するDBのコネクションウォレットを取得できない場合は、NYC SchoolsのデータをOACに直接アップロードすることができます。


重要な要件は、OACとAPEXの両方が同じデータセットにアクセスできることで、それが同じ場所に保存されているかどうかに関係なく、アクセスできることです。



付加価値を生むユーザー体験の創造


このセクションでは、OAC と APEX を組み合わせることで、どのようにユーザー体験に付加価値を与えることができるかを説明します。私は「価値」を、OACがAPEXでそのままでは利用できないようなこと(例えば、自然言語のナラティブを追加する)、またはその逆(例えば、APEXのファセット検索に分析を組み込んで利用する)であると定義しました。



APEXアプリにOAC TAGクラウドとNLGを追加


このアニメーションは、iFrameを使った場合とiFrameを使わない場合の、これから構築するユーザーエクスペリエンスを示しています。



前提条件として、APEXアプリケーションと同じデータを使用しているデータソースをOACで作成し、タグクラウドと自然言語生成(NLG)ビジュアライゼーションを表示するワークブックをOACで作成したものと仮定します。ライブ ラボ APEX アプリからアプリケーション ページ「NYC Highschools Report」をコピーしたので、そのページに OAC タグ クラウドと NLG ビジュアライゼーションを追加していきます。



iFrameを使用しない埋め込み


アプリケーションページにセレクトリストアイテムを追加します。これはSQL文から値のリストを取得し、選択項目はP7_SELECT_BOROUGHに格納されます(別の項目名でもかまいません)。


select distinct BOROUGH d, BOROUGH r
from NYC_HIGHSCHOOLS
order by 1


  •     選択リストの設定で、'Page Action on Selection' は 'Submit Page' を選択します。
  •     アプリケーションページに静的リージョンを追加し、埋め込まれたOACコンテンツをホストします。



この静的領域内で次のHTMLコードを使用してください。active-tab-idの番号は、埋め込みに使用している私のワークブックのOAC開発者|埋め込みメニューから取得したものであることに注意してください。の中の項目はobservableと呼ばれ、アプリケーション・ページ・レベルで定義されるコードを使って入力されます。


<div style='width:1024px; height:800px' ><oracle-dv id='Filter'
project-path='{{projectPath}}'
active-page='canvas'
active-tab-id='2'
project-options='{"bDisableMobileLayout":true, "bShowFilterBar":false}'
filters='{{filters}}'>
</oracle-dv>


アプリケーションページレベルで、次のようなコードを追加します(インスタンスとデータセットを所有するOACユーザーに適切なもの('sColFormula'のパス内))。



File URLs には、OAC インスタンスの embedding.js へのリンク (/jet/) と、パラメータ [require jet] を指定します。この例では、3本足のauthパラメータを使用していますが、APEXインスタンスがIDCS認証を使用するように設定することについては、このブログの前のほうを参照してください。


[require jet]
https://<OAC-instance>-ia.analytics.ocp.oraclecloud.com/public/dv/v1/embedding/jet/embedding.js?IDCS_OAUTH3LEGGED=true


「関数とグローバル変数の宣言」に、先ほど定義したP7_SELECT_BOROUGHの値をJavaScriptの変数に代入するコードがあります。


let vBoroughName = apex.item("P7_SELECT_BOROUGH").getValue();


'Execute When Page Loads' セクションでは、<oracle-dv> タグと、埋め込まれた OAC キャンバスで使われるフィルタ JSON に対して observables が定義されています。'sColFormula'は、OACワークブック開発者|JSONメニューオプションから取得することができます。


requirejs(['jquery', 'knockout', 'obitech-application/application', 'ojs/ojcore', 'ojs/ojknockout', 'ojs/ojcomposite',  'jet-composites/oracle-dv/loader'],
function($, ko, application) {
function model() {
var self = this;
self.projectPath = ko.observable('/@Catalog/shared/Embed/APEX/APEX NYC Schools');
self.filters = ko.observableArray([{
'sColFormula': "XSA('<data-set-owner>'.'APEX NYC HIGHSCHOOLS').\"NYC_HIGHSCHOOLS\".\"BOROUGH\"",
'sColName': 'BOROUGH',
'sOperator': 'in',
'isNumericCol': false,
'isDateCol': false,
'bIsDoubleColumn': false,
'aCodeValues': [],
'aDisplayValues': [vBoroughName]}]);
}
application.setSecurityConfig("oauth_3legged");
ko.applyBindings(new model());
});


これは、P7_SELECT_BOROUGH のセレクタが使用されたときに実行され('Page Submit' オプションによる)、変数 vBoroughName に値を取得し、それを埋め込み OAC キャンバス用のフィルタ JSON に渡します。'aDisplayValues' は配列を期待しているので、渡された値 (vBoroughName) は [ ] 括弧で囲む必要があります。


この時点で、アプリケーションを実行し、セレクタの値を変更することで、APEX テーブルレポートと埋め込み OAC コンテンツに表示される行政区が変わることをテストしてください。



iFrame を使った埋め込み


JET の異なるバージョンを使用している場合(前述)、OAC キャンバスを APEX アプリケーションに埋め込むために iFrame を使用する必要があることがほとんどです。以下は、このようなアプリケーションページへの展開を示しています。



iFrameを使った場合との大きな違いは、すべてのOACエンベッディングコード、つまりembedding.jsへのリンク /standalone/, <oracle-dv> tag, requirejs dependencies and knockout applybindingsがiFrame内に含まれることです。iFrameは、複数のアプリケーションページに埋め込むことができる再利用可能なブロックとして機能し、このブログで後述するように、必要に応じてマイナーチェンジすることができます。iFrameにフィルタ値を渡す仕組みは、contentWindow.postMessageです。


OAC埋め込みコンテンツを含むAPEX静的リージョンには、srcdocパラメータを使用してiFrameを定義するHTMLコードが含まれています。


<iframe  id='OACiFrameEmbed' width="1024" height="800" srcdoc="
<!DOCTYPE HTML>
<html dir='ltr'>
<head>
<meta http-equiv='Content-Type' content='text/html; charset=utf-8'>
<script src='https://<OAC-INSTANCE>-ia.analytics.ocp.oraclecloud.com/public/dv/v1/embedding/standalone/embedding.js' type='application/javascript'>
</script></head>
<body>
<div style='width:1024px; height:800px' >
<oracle-dv id='Filter'
project-path='<PATH-TO-EMBEDDED-WORKBOOK'
active-page='canvas'
active-tab-id='1'
project-options='{&quot;bDisableMobileLayout&quot;:true, &quot;bShowFilterBar&quot;:false}'
filters='{{filters}}'>
</oracle-dv>
</div>
<script>
requirejs(['jquery','knockout','ojs/ojcore', 'ojs/ojknockout', 'ojs/ojcomposite', 'obitech-application/application', 'jet-composites/oracle-dv/loader'],
function($, ko, application) {
function model() {
var self = this;
self.filters = ko.observableArray([{
'sColFormula': &quot;XSA('<OAC-USER-ID>'.'APEX NYC HIGHSCHOOLS').\&quot;NYC_HIGHSCHOOLS\&quot;.\&quot;BOROUGH\&quot;&quot;,
'sColName': 'BOROUGH',
'sOperator': 'in',
'isNumericCol': false,
'isDateCol': false,
'bIsDoubleColumn': false,
'aCodeValues': [],
'aDisplayValues': ['Select Borough']
}]);
window.addEventListener('message', (event) => {
if ((typeof event.data === 'string' || event.data instanceof String) && event.origin == 'https://<APEX-DOMAIN>') {
self.filters([{'sColFormula': &quot;XSA('<OAC-USER-ID>'.'APEX NYC HIGHSCHOOLS').\&quot;NYC_HIGHSCHOOLS\&quot;.\&quot;BOROUGH\&quot;&quot;,
'sColName': 'BOROUGH',
'sOperator': 'in',
'isNumericCol': false,
'isDateCol': false,
'bIsDoubleColumn': false,
'aCodeValues': [],
'aDisplayValues': [event.data]}
]);
}}, false);
}
ko.applyBindings(new model);
});
</script></body></html>">
</iframe>

srcdocのパラメータ値は二重引用符で囲まれているので、srcdocのコード内で使用されている二重引用符はすべて&quotにエスケープする必要があります。


これは、project-optionsとsColFormulaに必要です。また、iFrameにメッセージを渡す際には、iFrameのリスナーだけでなく、メッセージを渡すドメインを指定する必要があります。これらの例では、そのドメインはAPEXインスタンスです。


APEXのセレクタは、'Page Action on Selection'として、'Submit Page'を持っています。選択された値をiFrameに渡すために、「Execute when Page Loads」ページレベルプロパティに、以下のようなコードを設定します。setTimeoutは、発生しうるレースコンディションを回避するためのものです。


vBoroughName = apex.item("P9_SELECT_BOROUGH").getValue();
setTimeout(() => { document.getElementById(‘OACiFrameEmbed’).contentWindow.postMessage(vBoroughName, ‘https://<APEX-INSTANCE>.adb.us-ashburn-1.oraclecloudapps.com’); }, 2500);


マルチセレクトを可能にするために必要な変更点



ユーザーが複数の行政区を選択できるようにしたい場合、以下のように変更する必要があります。


セレクタ P9_SELECT_BOROUGH を変更し、「選択時のページ操作」が「なし」になるようにします。


ページにボタンを追加します。私は、アプリケーション・ページのセレクタ・アイテムの下にボタンを配置しました。


  •     このボタンに「Apply」という名前とラベルをつけます。
  •     「動作」を「ページの送信」に設定します。




複数選択を扱う場合の重要な違いの1つは、組み込まれたOracle Analyticsキャンバスに渡されるのが配列オブジェクトになったことです。そのため、単一選択の使用例と比較して、iFrameのコードにいくつかの変更が必要です。


  •     iFrameには、単一の値ではなく、選択された値の配列が渡されるようになったためです。そのため、event.dataが配列であるかどうかをチェックするために、'if'ステートメントを変更する必要があります。
  •     event.data が配列であるため、[ ]は 'aDisplayValues' に渡される値には不要になりました(単一選択の場合との比較)。


if ((Array.isArray(event.data)) && event.origin == 'https://<APEX-INSTANCE>.adb.us-ashburn-1.oraclecloudapps.com') {
self.filters([{'sColFormula': &quot;XSA('<USER>'.'APEX NYC HIGHSCHOOLS').\&quot;NYC_HIGHSCHOOLS\&quot;.\&quot;BOROUGH\&quot;&quot;,
'sColName': 'BOROUGH',
'sOperator': 'in',
'isNumericCol': false,
'isDateCol': false,
'bIsDoubleColumn': false,
'aCodeValues': [],
'aDisplayValues': event.data}
]);
}
}, false);


APEXファセット検索を使用した埋め込み解析のフィルタリング



ファセット検索を含むAPEXページに(iFrameで)埋め込み分析を追加するのは、これまでの埋め込みシナリオと非常によく似ています。


  •     アプリケーションページに静的リージョンを追加します。
  •     静的リージョンに使用する iFrame のコードは、ファセット化された検索が配列も渡すので、複数選択のユースケースと同じです。
  •     検索項目の「属性」を「ファセット一括変更」を「オン」に変更します。これにより、ファセット選択を行う際に、ユーザーに「適用」ボタンが提供されるようになります。
  •     APEXページの「Search」項目に「Dynamic Action」を追加し、Eventを「Facets Change [Faceted Search]」に設定します。
  •     「True」の場合は、「Action」を「Execute JavaScript Code」に設定し、このサンプルを自分のユースケースに合わせて修正して使用します。このサンプルでは、ファセット検索でP8_BOROUGHを取得し、<ITEM>:<ITEM>:<ITEM>などの形式で出力しているので、出力を配列に分割するコードを1行記述しています。この配列は、'postMessage'を使ってiFrameに渡されます。


vBoroughName = apex.item("P8_BOROUGH").getValue();
aBoroughArray = vBoroughName.split(":");
setTimeout(() => { 
document.getElementById('OACiFrameEmbed').contentWindow.postMessage(aBoroughArray, 'https://<APEX-INSTANCE>.adb.us-ashburn-1.oraclecloudapps.com'); 
}, 2000);


まとめ


Oracle Analytics(OAC)をAPEXで使用することで、アプリケーションに付加価値を与えることができます。このブログでは、JET版の重要性を説明し、APEXがOACと同じOracle Identity Cloud Serviceを使用してシームレスな体験を提供するための設定方法についての説明へのリンクを提供しました。


iFrame(特に「srcdoc」パラメータ)を使用して分析コンテンツを埋め込むことで、分析コンテンツをサンドボックス化し、異なるJETバージョンが存在する可能性に対処する方法を提供します。


また、'postMessage'メソッドを使用して埋め込みiFrameにパラメータを渡すことは可能です。一般的なアプローチは、iFrameが自己完結型の分析埋め込みコードを含んでいることです - 埋め込みフレームワークへのリンク、<oracle-dv>埋め込みタグのHTML、requirejsの依存性管理、observableの定義などです。


埋め込みコンテンツに適用されるフィルタの定義は、観測可能な配列として定義され、ユースケースが単一の選択(event.data の周りに [ ] 括弧を追加)または複数選択/ファセット検索(event.data が配列なので [ ] 括弧は不要)であるかによって違いが必要とされます。


このタイプの埋め込みの他の重要な側面は、パラメータ値がエンドユーザによって選択されたとき、APEX ページレベルの 'Execute when Page Loads' パラメータを使用するか、ファセット化された検索値が変更されたときに呼び出される Dynamic Action を使用して、iFrame にこれらの値を送信する方法が必要であることです。



謝辞


お読みいただきありがとうございます。このブログがお役に立ち、ご自身のプロジェクトにOracle Analyticsを組み込む方法について、いくつかのアイデアを提供できたなら幸いです。Arun、Matt、Lior、Jackie、そしてRoelには、APEXに関する協力と支援をしてもらったことに感謝したい。


もしあなたがOracle Developersの自然な生息地での出来事に興味があるなら、私たちの公開Slackチャネルに参加してください。私たちはあなたの魚鉢になることを気にしません 🐠。


コメント

このブログの人気の投稿

Oracle RACによるメンテナンスのためのドレインとアプリケーション・コンティニュイティの仕組み (2023/11/01)

Oracle Cloud Infrastructure Secure Desktopsを発表: デスクトップ仮想化のためのOracleのクラウドネイティブ・サービス (2023/06/28)

Oracle Cloudのデータベースをオブジェクト・ストレージにバックアップする3つの方法 (2021/12/13)