1. Oracle Analytics Serverでのデータのビジュアル化
  2. データのビジュアル化
  3. カスタム・データ・アクション・プラグインの作成

12 カスタム・データ・アクション・プラグインの作成

Oracle Analyticsで使用するカスタム・データ・アクション・プラグインを作成できます。

データ・アクション・プラグインは、Oracle Analyticsを拡張し、ユーザーがビジュアライゼーションでデータ・ポイントを選択し特定のアクションを起動できるようにします。Oracle Analyticsは、多くの一般的なユースケースを網羅するデータ・アクションのコア・セットを提供しますが、独自のデータ・アクション・プラグインを記述することで、この機能をより詳細に拡張できます。

カスタム・データ・アクション・プラグインを作成するには、次の要素に関する基本的な理解が必要です:

  • JavaScript
  • RequireJS
  • JQuery
  • KnockoutJS

トピック:

テンプレートからのデータ・アクション・プラグインの生成

一連のコマンドを使用して開発環境を生成し、カスタム・データ・アクション・プラグインを作成するために必要なフォルダとファイル付きでHTTP APIデータ・アクションを移入します。

すべてのプラグイン・ファイルは、同じ基本構造に従います。ファイルとフォルダを手動で作成することも、それらをテンプレートから生成することもできます。これを行うツールは、Oracle Analytics Desktopに付属しているOracle Analytics Desktopソフトウェア開発キット(SDK)に含まれています。Oracle Analytics Desktop SDKのリファレンスを参照してください。

次のコマンドを使用して開発環境を生成し、それにHTTP APIデータ・アクションを移入します。

  1. コマンド・プロンプトで、Oracle Analytics Desktopインストールのルート・フォルダを指定します:
    set DVDESKTOP_SDK_HOME=C:\Program Files\Oracle Analytics Desktop
  2. カスタム・プラグインを格納する場所を指定します:
    set PLUGIN_DEV_DIR=C:\temp\dv-custom-plugins
  3. 次を使用してSDKコマンドライン・ツールを追加します:
    set PATH=%DVDESKTOP_SDK_HOME%\tools\bin;%PATH%
  4. 次を使用してカスタム・プラグインの格納に使用するディレクトリのフォルダを作成します:
    mkdir %PLUGIN_DEV_DIR%
  5. ディレクトリを変更してカスタム・プラグインを格納するためのフォルダに移動します:
    cd %PLUGIN_DEV_DIR%
  6. 環境変数を作成します:
    bicreateenv
  7. 次のように、カスタムHTTP APIデータ・アクションの開発を開始するために必要なテンプレート・ファイルを作成します:
    bicreateplugin -pluginxml dataaction -id company.mydataaction -subType httpapi

    -subTypeオプションを使用して、作成元となるデータ・アクション・タイプ(httpapi、urlNavigation、canvasNavigation、eventまたはadvanced)を指定します。advancedオプションは、AbstractDataActionベース・クラスからの拡張です。

生成されたフォルダとファイル

新しく生成されたデータ・アクション開発環境には、次のフォルダとファイルが含まれます:


1    %PLUGIN_DEV_DIR%\src\customdataaction
2       company-mydataaction\
3          extensions\
4             oracle.bi.tech.plugin.dataaction\
5                company.mydataaction.json
6          nls\
7             root\
8                messages.js
9             messages.js
10          mydataaction.js
11          mydataactionstyles.css
12          plugin.xml
  • 行2: company-mydataactionフォルダは、指定したIDです。
  • 行6: nlsフォルダには、プラグインでネイティブ言語サポートを提供できるようにする外部化文字列のファイルが含まれます。
  • 行7: nls\rootフォルダ以下のファイルの文字列は、リクエストされた言語の翻訳が使用できない場合に使用されるデフォルト文字列です。
  • 行8: messages.jsファイルには、追加可能なプラグイン用の外部化文字列が含まれます。
  • 行9: messages.jsファイルには、ローカライズされた文字列を提供する追加言語ごとに追加したエントリが含まれる必要があります。翻訳を追加する各ロケールのnlsフォルダ以下に、対応するフォルダを追加する必要があります。各フォルダには、nls\rootフォルダ以下に追加されたファイルと同じファイル名で、同じファイル・セットが含まれる必要があります。
  • 行10: mydataaction.jsファイルは、カスタム・データ・アクションを開発するための開始ポイントを提供する、新しく生成されたJavaScriptモジュール・テンプレートです。
  • 行11: mydataactionstyles.cssファイルには、追加する予定があり、データ・アクションのユーザー・インタフェースで使用できる任意のCSSスタイルを含めることができます。
  • 行12: plugin.xmlファイルは、Oracle Analyticsにプラグインおよびそのファイルを登録します。

データ・アクション・ベース・クラスの拡張

拡張するデータ・アクションのサブクラスを選択し、必要なフォルダとファイルを生成したら、新しいデータ・アクションに固有のコードの記述を開始できます。

新しく生成されたデータ・アクション・コードは、%PLUGIN_DEV_DIR%\src\dataaction以下にあります。ファイルおよびフォルダ構造の説明は、「生成されたフォルダとファイル」を参照してください。編集する必要のあるメイン・ファイルは、JavaScriptファイルです。たとえば、カスタム・データ・アクションIDがcompany.MyDataactionである場合、検索するファイルは%PLUGIN_DEV_DIR%\src\dataaction\company-mydataaction\mydataaction.jsです。

データ・アクションのKnockoutモデルの拡張

格納する必要のある追加プロパティがデータ・アクションに含まれる場合、それらを監視可能プロパティとしてKnockoutモデルに追加する必要があります。データ・アクションのIDがcompany.MyDataactionである場合、Knockoutモデルはmydataaction.MyDataActionKOModelと呼ばれ、mydataaction.jsの最上位付近にあります。デフォルトで、このKnockoutモデルはデータ・アクションのスーパークラスで使用されるKnockoutモデルを拡張するように構成されるため、モデルに追加プロパティを追加するだけで済みます。

HTTPAPIDataActionベース・クラスを拡張しているデータ・アクションでは、次のようなコードを使用します: 

1 - mydataaction.MydataactionKOModel = function (sClass, sID, sName, sVersion, sScopeID, aAnchorToColumns, eValuePassingMode, sURL,
        eHTTPMethod, sPOSTParams)
2 - {   
3 - mydataaction.MydataactionKOModel.baseConstructor.call(this, sClass, sID, sName, sVersion, sScopeID, aAnchorToColumns, eValuePassingMode, sURL, eHTTPMethod, sPOSTParams);
4 - };
5 - jsx.extend(mydataaction.MydataactionKOModel, dataaction.HTTPAPIDataActionKOModel);
  • 行1: これは、Knockoutモデルのコンストラクタです。モデルが格納する必要のあるプロパティを受け入れます。
  • 行3: これは、スーパークラスのコンストラクタであり、Knockoutモデルのスーパークラスのいずれかによって処理されるすべてのプロパティに対する値の受渡し先となるbaseConstructorでもあります。
  • 行5: これは、このKnockoutモデル・クラスのスーパークラスを設定します。

次のようなコードを使用して文字列と配列を追加し、データ・アクションによって永続化されるプロパティを設定します。

1   mydataaction.MydataactionKOModel = function (sClass, sID, sName, sVersion, sScopeID, aAnchorToColumns, eValuePassingMode, sURL, eHTTPMethod, sPOSTParams)
2   {   
3   mydataaction.MydataactionKOModel.baseConstructor.call(this, sClass, sID, sName, sVersion, sScopeID, aAnchorToColumns, eValuePassingMode, sURL, eHTTPMethod, sPOSTParams);
4   
5  
6   // Set Defaults   
7   sMyString = sMyString || "My default string value";   
8   aMyArray = aMyArray || [];     
9  
10
11  // Asserts   
12  jsx.assertString(sMyString, "sMyString");   
13  jsx.assertArray(aMyArray, "aMyArray");
14 
15
16  // Add observable properties   
17  this.sMyString = ko.observable(sMyString);   
18  this.aMyArray = ko.observableArray(aMyArray);
19  };
20  jsx.extend(mydataaction.MydataactionKOModel, dataaction.HTTPAPIDataActionKOModel);

オーバーライドするデータ・アクションの継承メソッドの選択

各データ・アクションは、適切に動作するために様々なメソッドを実装する必要があるため、変更して使用できる動作を実装しているメソッドをオーバーライドすることになります。

汎用メソッド

HTTPAPIDataActionなどの具象データ・アクション・クラスのいずれかを拡張する場合、必要なメソッドのほとんどはすでに実装されており、変更して使用できる動作を実装しているメソッドをオーバーライドするだけで済みます。

この項では、様々なメソッドとその予期される動作について説明します。

すべてのタイプのデータ・アクションは、ここで説明されているメソッドを実装する必要があります。

create(sID, sName)

create()静的メソッドは、新しいデータ・アクションを作成してドロップダウン・メニューからデータ・アクション・タイプを選択したときにコールされます。このメソッドの役割は次のとおりです:

  • データ・アクションで使用するKnockoutモデル・クラスの構築。

    Knockoutモデル・クラスには、他のすべてのプロパティにとって意味のあるデフォルト値とともにcreate()メソッドに渡されるIDと名前が含まれる必要があります。たとえば、通貨換算データ・アクションでは、ドルに換算するデフォルト通貨を設定できます。Knockoutモデルは、デフォルト値を提供するための適切な場所です。

  • Knockoutモデルからのデータ・アクションのインスタンスの構築。
  • データ・アクションのインスタンスの返却。

invoke(oActionContext, oDataActionContext)

invoke()メソッドは、ビジュアライゼーションのデータ・ポイントのコンテキスト・メニューからユーザーがデータ・アクションを起動したときにコールされます。このメソッドは、選択されたデータ・ポイント、ビジュアライゼーション、フィルタ、ワークブックおよびセッションを記述したメタデータを含むDataActionContext引数を渡します。「データ・アクション・サービス・クラス」を参照してください。

validate()

validate()メソッドは、「データ・アクション」ダイアログでユーザーが「OK」をクリックしたときに各データ・アクションでコールされます。validate()メソッドは、すべてが有効であることを示す場合はnullを返し、何かが無効である場合はDataActionErrorを返します。ダイアログでいずれかのデータ・アクションにエラーが発生した場合、ダイアログは閉じられず、ユーザーにエラー・メッセージが表示されます。このメソッドは、this.validateName()メソッドを使用してデータ・アクションの名前を検証します。

getGadgetInfos(oReport)

getGadgetInfos()メソッドは、ユーザー・インタフェースでデータ・アクション・プロパティ・フィールドを表示できるようにするためにコールされます。このメソッドは、ユーザーが希望するユーザー・インタフェースへの表示順序でGadgetInfosの配列を返します。ガジェットは、最も一般的なタイプのすべてのフィールドに対して提供されますが(たとえば、テキスト、ドロップダウン、パスワード、複数選択、ラジオ・ボタン、チェック・ボックスなど)、より複雑なフィールドが必要な場合はカスタム・ガジェットを作成できます(たとえば、複数のガジェットをまとめてグループ化する場合や、ユーザーの選択したオプションに応じて異なるガジェット・フィールドを表示する場合など)。配列で必要な各GadgetInfoを構築するメソッドを作成する方が、後でサブクラスがその提供されたGadgetInfoから選択しやすくなるため、ベスト・プラクティスです。このベスト・プラクティスに従う場合、ユーザー・インタフェースで使用されるフィールドごとにGadgetInfoを返すことができる各種データ・アクション・ベース・クラスによって実装された様々なメソッドがすでに用意されています。また、これらのGadgetInfoのいずれかが必要な場合、対応するcreate****GadgetInfo()メソッドをコールして、その戻り値をガジェットの配列に配置します。

isAllowedHere(oReport)

isAllowedHere()メソッドは、ユーザーがビジュアライゼーションのデータ・ポイントを右クリックし、ユーザー・インタフェースがコンテキスト・メニューの生成を開始したときにコールされます。選択されたデータ・ポイントに関連するデータ・アクションが存在する場合、メソッドはtrueを返し、そのデータ・アクションがコンテキスト・メニューに表示されます。メソッドがfalseを返した場合、データ・アクションはコンテキスト・メニューに表示されません。スーパークラスから継承したデフォルト動作を受け入れることを検討してください。

upgrade(oOldDataActionJS)

最初のデータ・アクションを作成する場合、upgrade(oOldDataActionJS)メソッドを使用しないでください。このメソッドは、最初のKnockoutモデルの作成後に、第2バージョンのKnockoutモデルのプロパティを大幅に変更する場合にのみ使用してください。たとえば、最初のバージョンのデータ・アクションではそのKnockoutモデルにURLを格納するが、次のバージョンでは別個のプロパティにURLコンポーネント部分を格納する予定の場合です(たとえば、protocol、hostname、port、path、queryString、bookmarkなど)。

第2バージョンのKnockoutモデル・コードは、問題が発生する可能性のある最初のバージョンのKnockoutモデル・コードに保存されているデータ・アクションを開こうとする場合があります。この問題を解決するため、システムでは、現在のデータ・アクション・コードのバージョンが、開かれようとしているデータ・アクションのバージョンより新しいことを認識すると、新しいデータ・アクション・クラスのupgrade()メソッドをコールして、古いデータ・アクションのKnockoutモデル(JSONオブジェクトにシリアライズ済)を渡します。その後、古いJSONオブジェクトを使用して新しいKnockoutモデルに移入し、JSONオブジェクトのアップグレード・バージョンを返すことができます。これにより、データ・アクション・コードを改善しても、古いデータ・アクション・メタデータは動作し続けることが保証されます。

HTTPAPIDataActionメソッド

HTTPAPIDataActionクラスを拡張する場合、オーバーライドできる次の追加メソッドが用意されています:

getAJAXOptions(oDataActionContext)

getAJAXOptions()メソッドは、データ・アクションのinvoke()メソッドによってコールされます。getAJAXOptions()メソッドは、データ・アクションで作成されるHTTPリクエストを記述したAJAX Optionsオブジェクトを作成します。getAJAXOptions()メソッドには、選択されたデータ・ポイント、ビジュアライゼーション、フィルタ、ワークブックおよびセッションを記述したメタデータを含むoDataActionContextオブジェクトが渡されます。統合しようとしているHTTP APIの要件どおりにAJAX Optionsを設定し、HTTPRequestが成功するかエラーで終了した場合にコールする関数を指定します。jQuery.ajaxオブジェクトとそのプロパティの説明は、JQueryのWebサイトを参照してください。

次の実装は、HTTPAPIDataActionクラスから継承されています。継承メソッドをリライトして要件を指定する必要があります。たとえば、HTTPリクエストと、HTTPレスポンスを処理するコードを構成します。この実装は、getAJAXOptions()関数に渡されるパラメータ、返されることが予期されるオブジェクト、およびメソッド内でコードを構成する方法の明確な例を示しているため、役に立ちます。 

1 /**
2  * This method returns an object containing the AJAX settings used when the data action is invoked. 
3  * Subclasses may wish to override this method to provide their own behavior. 
4  * @param {module:obitech-reportservices/dataactionmanager.DataActionContext} oDataActionContext The context metadata describing where the data action was invoked from.  
5  * @returns {?object} A JQuery AJAX settings object (see http://api.jquery.com/jQuery.ajax/ for details) - returns null if there is a problem. 
6  */
7 dataaction.HTTPAPIDataAction.prototype.getAJAXOptions = function (oDataActionContext)
8 {
9    jsx.assertInstanceOfModule(oDataActionContext, "oDataActionContext", "obitech-reportservices/dataactionmanager", "DataActionContext");
10   
11   var oAJAXOptions = null;   
12   var oKOViewModel = this.getKOViewModel();
13   var sURL = oKOViewModel.sURL();
14   if (sURL)
15   {
16      // Parse the URL
17      var sResultURL = this._parseURL(sURL, oDataActionContext);
18      if (sResultURL)
19      {
20         // Parse the POST parameters (if required)
21         var eHTTPMethod = oKOViewModel.eHTTPMethod()[0];
22         var sData = null;
23         if (eHTTPMethod === dataaction.HTTPDataActionKOModel.HTTPMethod.POST)
24         {
25            var sPOSTParams = oKOViewModel.sPOSTParams();
26            sData = sPOSTParams.replace(dataaction.AbstractHTTPDataAction.RegularExpressions.LINE_END, "&");
27            sData = this._parseURL(sData, oDataActionContext, false);
28         }
29         oAJAXOptions = {
30            type: eHTTPMethod,
31            url: sResultURL,
32            async: true,
33            cache: false,
34            success: function (/*oData, sTextStatus, oJQXHR*/)
35            {
36               oDataActionContext.getReport().displaySuccessMessage(messages.HTTP_API_DATA_ACTION_INVOCATION_SUCCESSFUL.format(oKOViewModel.sName()));
37            },
38            error: function (oJQXHR/*, sTextStatus, sError*/)
39            {
40               oDataActionContext.getReport().displayErrorMessage(messages.HTTP_API_DATA_ACTION_INVOCATION_FAILED.format(oKOViewModel.sName(), oJQXHR.statusText, oJQXHR.status));
41            }
42         };
43         if (sData)
44         {
45            oAJAXOptions.data = sData;
46         }
47      }
48   }
49   return oAJAXOptions;
50 };

データ・アクションのテスト、パッケージ化およびインストール

Oracle Analytics Desktopを使用して、データ・アクションをインストールする前にそのソースの場所でテストします。

  1. Oracle Analytics Desktopが現在実行中である場合は、閉じます。
  2. プロキシの裏で作業している場合、プロキシ設定を%PLUGIN_DEV_DIR%\gradle.propertiesで設定します。HTTPプロキシを通じたWebへのアクセスの詳細は、Gradle ユーザー・マニュアルを参照してください。
  3. 「オーバーライドするデータ・アクションの継承メソッドの選択」で起動したコマンド・プロンプトを使用して、Oracle Analytics DesktopをSDKモードで実行し、次のコマンドを入力します。
    cd %PLUGIN_DEV_DIR%
    .\gradlew run

    Oracle Analytics DesktopがSDKモードで起動します。「コンソール | 拡張機能」ページにデータ・アクション・プラグインが表示されます。

    ワークブックを作成してデータ・アクションをテストします。問題が発生した場合、ブラウザの組込み開発者ツールを使用してコードをデバッグできます。

  4. HTTP APIデータ・アクションを作成した場合:
    1. コンソールに移動して「安全ドメイン」ページを表示します。
    2. アクセスする各ドメインを追加します。
      たとえば、apilayer.comのAPIにアクセスする必要がある場合、安全なドメインのリストにapilayer.netを追加します。
    3. 選択したドメインの「接続」列のチェック・ボックスを選択します。
    4. ブラウザで「安全ドメイン」ページをリロードして変更を反映します。
  5. データ・アクション・プラグインを準備して、他のユーザーに配布する、またはOracle Analyticsでインストールする場合、次を行います。
    • %PLUGIN_DEV_DIR%\src\customdataactionフォルダとその内容を含む1つのZIPファイルにすべてのファイルをパッケージ化します。
    • データ・アクション・プラグインの作成時に指定したものと同じIDを使用してzipに名前を付けます。
  6. データ・アクション・プラグインをインストールします。「カスタム・プラグインの管理」を参照してください。

Knockoutモデル変更のためのアップグレード・ハンドラの使用

一部のKnockoutモデル変更では、アップグレード・ハンドラを使用してデータ・アクション・プラグインをアップグレードする必要があります。

Knockoutモデルを変更せずにデータ・アクション・プラグインを改善する場合、通常どおりJavaScriptまたはCSSファイルを編集し、新しいZIPファイルを作成して、既存のデータ・アクション・プラグインを新しいZIPファイルに置き換えます。ただし、データ・アクションのKnockoutモデルを変更した場合、データ・アクションのVERSIONプロパティを変更してアップグレード・ハンドラを指定する必要があります。

アップグレード・ハンドラを使用する必要があるかどうかを決定します:

アップグレード・ハンドラが必要な場合
  • Knockoutモデルのプロパティ名を変更する場合。
  • Knockoutモデルの複数のプロパティを単一のプロパティに結合する場合。
  • Knockoutモデルの単一のプロパティを複数のプロパティに分割する場合。
  • Knockoutモデルに新しいプロパティを追加する際に、その正しいデフォルト値がKnockoutモデルの他の値に依存する場合。
アップグレード・ハンドラが不要な場合
  • Knockoutモデルに新しいプロパティを追加する際に、データ・アクションのすべての既存の使用方法に対して正しいデフォルト値を指定できる場合。
  • データ・アクション・コードで使用しなくなったためにKnockoutモデルからプロパティを除去する場合。

データ・アクション・プラグインのアップグレード

データ・アクション・プラグインをアップグレードしてデータ・アクション・コードを改善するか、メタデータをアップグレードして既存のデータ・アクションで新しいデータ・アクション・コードを操作できるようにします。

データ・アクション・プラグインをアップグレードするには、アップグレード・ハンドラを使用します。
  1. データ・アクションのバージョン番号を増やします。

    たとえば、データ・アクション名がcompany.MyDataActionである場合、mydataaction.jsでmydataaction.MyDataAction.VERSIONプロパティを検索します。これが現在1.0.0に設定されている場合、1.0.1に変更します。

  2. static upgrade(oOldDataActionJS)メソッドをデータ・アクション・クラスに追加します。

    VERSIONプロパティがデータ・アクション・メタデータに格納されているsVersion値と異なる場合、データ・アクション・マネージャは、データ・アクション・クラスのstatic upgrade()メソッドをコールします。

  3. スーパークラスのupgrade()メソッドをコールすることでupgrade()メソッドを実行し、そのレスポンスを取得します。
  4. 最新のKnockoutモデルで必要とされる適切なプロパティ・セットにオブジェクトが一致するまで、スーパークラスから返される部分的にアップグレードされたデータ・アクションJSONに編集を加えることでupgrade()メソッドを実行し続けます。
  5. var oUpgradedDataAction = dataaction.AbstractDataAction.createFromJS(fDataActionClass, sFullyQualifiedDataActionClassName, oUpgradedDataActionJS)をコールして終了します。

    このコマンドは、アップグレードされたデータ・アクションJSONからデータ・アクションの新しいインスタンスを構築し、oUpgradedDataAction.getSettings()を返します。