データ・アクション・プラグインおよびデータ・アクション・フレームワークについて

データ・アクション・プラグインは、データ・アクション・フレームワークを活用して、Oracle Analyticsユーザー・インタフェースに緊密に統合されているカスタムのデータ駆動型アクションを提供します。

ユーザーがデータ・アクションを起動すると、データ・アクション・マネージャは、リクエストの処理を担当するデータ・アクション・プラグインにリクエスト・コンテキスト(修飾データ参照、メジャー値、フィルタ、メタデータなど)を渡します。Oracleでは、CanvasDataAction、URLNavigationDataAction、HTTPAPIDataActionおよびEventDataActionという4つのタイプのデータ・アクション・プラグインが提供されます。これらのデータ・アクション・プラグイン・タイプとその抽象ベース・クラスを拡張して、独自のデータ・アクションを提供できます。

トピック:

データ・アクション・カテゴリ

データ・アクション・カテゴリには、URLへのナビゲート、HTTP API、キャンバスへのナビゲート、およびイベント・アクションが含まれます:

URLへのナビゲート: 指定されたURLを新しいブラウザ・タブで開きます。
HTTP API: GET/POST/PUT/DELETE/TRACEコマンドを使用してHTTP APIをターゲット指定し、結果を新しいタブで開きません。かわりに、HTTPステータス・コードが調査され、一時的な成功または失敗メッセージが表示されます。
キャンバスへのナビゲート: 同じかまたは異なるビジュアライゼーションでユーザーがソース・キャンバスからターゲット・キャンバスにナビゲートできるようにします。ソース・キャンバス内で有効なフィルタは、すべて外部フィルタとしてターゲット・キャンバスに渡されます。ターゲット・キャンバスが開かれると、ビジュアライゼーションへの外部フィルタの適用が試行されます。外部フィルタが適用されるメカニズムは、ここでは説明しません。
イベント・アクション: Oracle Analyticsイベント・ルーターを使用してイベントを公開します。どのJavaScriptコード(サード・パーティ・プラグインなど)でもこれらのイベントにサブスクライブでき、その結果に基づいてカスタム・レスポンスを処理できます。プラグイン開発者はデータ・アクションの応答方法を選択できるため、柔軟性が最大限に高まります。たとえば、ユーザー・インタフェースを表示することも、一度に複数のサービスにデータを渡すこともできます。

URLへのナビゲートとHTTP APIのデータ・アクション・カテゴリ・タイプは、両方ともトークン構文を使用して、ビジュアライゼーションからURLおよびPOSTパラメータにデータまたはメタデータを挿入できます。

URLトークンの置換

HTTPデータ・アクションでは、URL内のトークンを、データ・アクションに渡されるコンテキストに基づいた値に置換できます。たとえば、修飾データ参照値、フィルタ値、ユーザー名、ワークブック・パスおよびキャンバス名が対象になります。

トークン	ノート	置換後の値	例	結果
`${valuesForColumn:COLUMN}`	該当なし	修飾データ参照に基づいた列の表示値。	`${valuesForColumn: "Sales"."Products"."Brand"}`	`BizTech,FunPod`
`${valuesForColumn:COLUMN, separator:"/"}`	複数の値に置換される可能性のあるトークンでは、任意のセパレータ・オプションがサポートされます。`separator`は、カンマ(,)がデフォルトですが、任意の文字列に設定できます。この文字列内で二重引用符をエスケープするには、バックスラッシュ(\)を使用します。	修飾データ参照に基づいた列の表示値。	`${valuesForColumn: "Sales"."Products"."Brand"}`	`BizTech,FunPod`
`${valuesForColumn:COLUMN, separationStyle:individual}`	`separationStyle`は、`delimited`がデフォルトですが、値ごとに個別のURLパラメータを生成する必要がある場合は`individual`に設定できます。	修飾データ参照に基づいた列の表示値。	`&myParam=${valuesForColumn: "Sales"."Products"."Brand"}`	`&myParam=BizTech&myParam=FunPod`
`${keyValuesForColumn:COLUMN}`	該当なし	修飾データ参照に基づいた列のキー値。	`${keyValuesForColumn:COLUMN}`	`10001,10002`
`${env:ENV_VAR}`	サポートされる環境変数は、`sProjectPath`、`sProjectName`、`sCanvasName`、`sUserID`および`sUserName`です。	環境変数。	`${env:'sUserID'}`	`myUserName`

データ・アクション・コンテキスト

ユーザーがデータ・アクションを起動したときに渡されるコンテキストを定義できます。

データ・アクションの作成時に、そのデータ・アクションに渡されるコンテキストの分量を定義します。

修飾データ参照

データ・アクションが起動されると、LogicalFilterTreeオブジェクトの配列を使用して、マークされたデータ・ポイントごとに修飾データ参照が生成されます。LogicalFilterTreeは、ツリー構造に編成された複数のLogicalFilterNodeオブジェクトで構成されます。このオブジェクトには次のものが含まれます。

データ・レイアウトの行エッジまたは列エッジの属性。
マークされた各セルに対応するメジャー・エッジの特定のメジャー。
マークされた各セルの特定のメジャー値。
キー値と表示値。

環境変数

一部のデータ・アクションでは、マークされた各データ・ポイントを説明するデータおよびメタデータに加え、データ・アクションが起動される環境を説明するより詳細なコンテキストが必要になることがあります。このような環境変数には次のものが含まれます:

プロジェクト・パス
プロジェクト名
キャンバス名
ユーザーID
ユーザー名

データ・アクション・コード設計

APIクラスを使用してデータ・アクションを作成します。

AbstractDataActionクラスから継承されるデータ・アクションの4つの具象クラスは次のとおりです:
- CanvasDataAction
- URLNavigationDataAction
- HTTPAPIDataAction
- EventDataAction
データ・アクション・プラグインAPIを使用して、新しいタイプのデータ・アクションを作成できます。Data Visualization SDKリファレンスを参照してください。
データ・アクション・タイプの登録は、DataActionPluginHandlerによって管理されます。
データ・アクションのインスタンスの作成、読取り、編集、削除または起動を行うコードは、イベントを公開することでそれらを行います。
イベントは、DataActionManagerによって処理されます。

データ・アクション・モデル・クラス

データ・アクション・モデル・クラスにはいくつかの異なるタイプがあります。

AbstractDataAction

このクラスの役割は次のとおりです:

Knockoutモデルの格納(サブクラスは独自のプロパティでこれを自由に拡張できます)。
サブクラスが実装する必要のある抽象メソッドの定義:
- + invoke(oActionContext: ActionContext, oDataActionContext:DataActionContext) <<abstract>>
  渡されたコンテキストでデータ・アクションを起動します(コール元は常にDataActionManagerである必要があります)。
- + getGadgetInfos(oReport): AbstractGadgetInfo[] <<abstract>>
  このタイプのデータ・アクションを編集するためのユーザー・インタフェース・フィールドをレンダリングする役割を持つGadgetInfosを構築して返します。
- + validate() : DataActionError
  データ・アクションを検証して、有効な場合はnullを、無効な場合はDataActionErrorを返します。
データ・アクションのユーザー・インタフェース・フィールドの一般的な部分をレンダリングするために使用される次のメソッドのデフォルト実装を提供:
- + getSettings():JSON
  レポートに含める準備のためにデータ・アクションのKnockoutモデルをJSONにシリアライズします(komapping.toJS(_koModel)を使用します)。
- + createNameGadgetInfo(oReport) : AbstractGadgetInfo
  データ・アクションの「名前」フィールドをレンダリングできるGadgetInfoを構築して返します。
- + createAnchorToGadgetInfo(oReport) : AbstractGadgetInfo
  データ・アクションの「アンカー先」フィールドをレンダリングできるGadgetInfoを構築して返します。
- + createPassValuesGadgetInfo(oReport) : AbstractGadgetInfo
  データ・アクションの「値を渡す」フィールドをレンダリングできるGadgetInfoを構築して返します。

サブクラスでは、ベース・クラスによって提供されるすべてのGadgetInfoが必要とされるわけではないため、状況によってはこれらすべてのメソッドをコールする必要はありません。この方法で各フィールドのレンダリングを抽出することで、サブクラスは必要なガジェットを自由に選択できます。一部のサブクラスでは、これらの一般的なデータ・アクション・ガジェットの異なる実装を提供することも可能です。

CanvasDataAction、URLNavigationDataAction、HTTPAPIDataAction、EventDataAction

これらは、データ・アクションの基本タイプの具象クラスです。これらのクラスは、独自に動作して、これらのタイプのデータ・アクションに対して一般的なユーザー・インタフェースを提供します。また、カスタム・データ・アクション・プラグインで拡張できる有益なベース・クラスとしても動作します。

CanvasDataAction: キャンバスにナビゲートするために使用します。
URLNavigationDataAction: 新しいブラウザ・ウィンドウでWebページを開くために使用します。
HTTPAPIDataAction: HTTP APIに対するGET/POST/PUT/DELETE/TRACEリクエストを作成してHTTP Responseをプログラムで処理するために使用します。
EventDataAction: イベント・ルーターを通じてJavaScriptイベントを公開するために使用します。

各クラスの役割は次のとおりです:

ベース・クラスからの抽象メソッドの実装。
- invoke(oActionContext: ActionContext, oDataActionContext:DataActionContext)
  このメソッドは、KOModelで定義されたプロパティと指定されたDataActionContextオブジェクトを結合してデータ・アクションを起動します。
- getGadgetInfos(oReport): AbstractGadgetInfo[]
  このメソッドの操作内容は次のとおりです。
  - AbstractGadgetInfosを格納した配列を作成します。
  - 各AbstractGadgetInfoを配列に配置する個々のcreateXXXGadgetInfo()メソッドをコールします。
  - 配列を返します。
データ・アクションの特定のサブクラスに固有の個々のガジェットを作成するための追加メソッドを提供。

これらの具象クラスのサブクラスでは、カスタム・ユーザー・インタフェースのスーパークラスによって提供されるすべてのガジェットを使用する必要はありません。この方法で各ガジェットの構築を抽出することで、サブクラスは必要なガジェットを自由に選択できます。

DataActionKOModel、ValuePassingMode

DataActionKOModelクラスは、AbstractDataActionの異なるサブクラスによって共有されるベースKOModelを提供します。「DataActionKOModelクラス」を参照してください。

データ・アクション・サービス・クラス

いくつかの異なるデータ・アクション・サービス・クラスがあります。

DataActionManager

analytics-data-actions-manager-class-diagram.pngの説明が続きます

図analytics-data-actions-manager-class-diagram.pngの説明

DataActionManagerとのすべてのやり取りでは、次の操作用のイベント・ハンドラを実装しているClientEvents.DataActionManagerを使用します:

現在のワークブックに定義されたデータ・アクション・セットの管理。
データ・アクションの起動。
現在のワークブックに定義されたすべてのデータ・アクションの取得。
マークされた現在のデータ・ポイントに適用できるすべてのデータ・アクションの取得。

DataActionContext、EnvironmentContext

データ・アクションが起動されると、ターゲットに渡されるコンテキストがDataActionContextクラスに格納されます。

getColumnValueMap()
属性列名でキー設定された属性列値のマップを返します。これらは、データ・アクションの起動元となるデータ・ポイントの修飾データ参照を定義します。
getLogicalFilterTrees()
データ・アクションの起動元となる特定のデータ・ポイントの修飾データ参照を記述したLogicalFilterTreesオブジェクトを返します(詳細はInteractionServiceを参照してください)。
getEnvironmentContext()
ソース環境を記述した次のようなEnvironmentContextクラスのインスタンス:
- getProjectPath()
- getCanvasName()
- getUserID()
- getUserName()
getReport()
データ・アクションの起動元のレポートを返します。

DataActionHandler

DataActionHandlerクラスは、様々なデータ・アクション・プラグインを登録します。そのAPIは、他のプラグイン・ハンドラ(VisualizationHandlerなど)と広範囲にわたり整合性があります。

DataActionHandlerクラスは、次のパブリック・メソッドを提供しています:

getClassName(sPluginType:String) : String
指定されたデータ・アクション・タイプの完全修飾クラス名を返します。
getDisplayName(sPluginType:String) : String
指定されたデータ・アクション・タイプの翻訳された表示名を返します。
getOrder(sPluginType:String) : Number
データ・アクション・タイプのリストを優先順序にソートするために使用される数値を返します。

DataActionHandlerクラスは、次の静的メソッドを提供しています:

getDependencies(oPluginRegistry:Object) : Object.<String, Array>
登録されたすべてのデータ・アクション・タイプをカバーする依存性マップを返します。
getHandler(oPluginRegistry:Object, sExtensionPointName:String, oConfig:Object) : DataActionPluginHandler
DataActionHandlerクラスの新規インスタンスを構築して返します。

DataActionUpgradeHandler

DataActionUpgradeHandlerクラスは、レポートが開かれたときにUpgradeServiceによってコールされます。

DataActionHandlerクラスは、次の2つのメイン・メソッドを提供しています:

deferredNeedsUpgrade(sCurrentVersion, sUpgradeTopic, oDataActionJS, oActionContext) : Promise
指定されたデータ・アクションをアップグレードするか(true)、アップグレードしないか(false)を示すブールに解決されるPromiseを返します。このメソッドは、データ・アクション・インスタンスを、データ・アクションのコンストラクタと比較して、データ・アクションをアップグレードする必要があるかどうかを決定します。
performUpgrade(sCurrentVersion, sUpgradeTopic, oDataActionJS, oActionContext, oUpgradeContext) : Promise
指定されたデータ・アクションでアップグレードを実行し、Promiseを解決します。アップグレード自体は、データ・アクションのupgrade()メソッドをコールすることで実行されます(アップグレード自体の要件を満たすのは、アップグレードされるデータ・アクションの特定のサブクラスのみです)。
getOrder(sPluginType:String) : Number
データ・アクション・タイプのリストを優先順序にソートするために使用される数値を返します。

データ・アクション・コード相互作用

データ・アクションは、ユーザー・インタフェース・フィールドを作成するとき、およびユーザーがデータ・アクションを起動するときに、Oracle Analyticsコードと相互作用します。

新しいデータ・アクション・インスタンス用のフィールドの作成

この相互作用は、Oracle Analyticsがデータ・アクションのユーザー・インタフェース・フィールドをレンダリングするときに開始します。そのために、次を行います:

データ・アクションから返されるGadgetInfosの親のGadgetInfoとして動作するPanelGadgetInfoを作成します。
データ・アクションのgetGadgetInfos()をコールします。
最初のステップで作成したPanelGadgetInfoの子としてデータ・アクションのGadgetInfosを追加します。
PanelGadgetInfoをレンダリングするPanelGadgetViewを作成します。
PanelGadgetViewのコンテナであるHTMLElementを設定します。
HostedComponentツリーにすでに接続されているHostedComponentの子のHostedComponentとしてPanelGadgetViewを登録します。
これにより、getGadgetInfos()から返される配列の表示順序でパネル・ガジェット内にデータ・アクションのガジェットがレンダリングされます。

データ・アクションの起動

ユーザーが、Oracle Analyticsユーザー・インタフェースを通じて(たとえば、ビジュアライゼーションのデータ・ポイント上のコンテキスト・メニューから)データ・アクションを起動すると、この相互作用が開始します。

ユーザー相互作用に応答して、コードにより次の操作が行われます:

データ・アクションのID、データ・アクションの起動元であるDataVisualization、およびTransientVizContextオブジェクトが含まれるINVOKE_DATA_ACTIONイベントを公開します。
DataActionManagerは、次の操作によってこのイベントを処理します:
1. データ・アクション・インスタンスをそのIDから取得します。
2. 指定されたDataVisualizationでマークされたデータ・ポイントのLogicalFilterTreesを取得します。
3. データ・アクションのターゲットに渡されるすべての情報が含まれたDataActionContextを構築します。
4. データ・アクションのinvoke(oDataActionContext)をコールします。

データ・アクションplugin.xmlファイルの例

ここでは、CanvasDataActionデータ・アクションのplugin.xmlファイルの例を示します。

plugin.xmlの例

<?xml version="1.0" encoding="UTF-8"?>
<tns:obiplugin xmlns:tns="http://plugin.frameworks.tech.bi.oracle"
               xmlns:viz="http://plugin.frameworks.tech.bi.oracle/extension-points/visualization"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               id="obitech-currencyconversion"
               name="Oracle BI Currency Conversion"
               version="0.1.0.@qualifier@"
               optimizable="true"
               optimized="false">
 
 
   <tns:resources>
      <tns:resource id="currencyconversion" path="scripts/currencyconversion.js" type="script" optimizedGroup="base"/>
      <tns:resource-folder id="nls" path="resources/nls" optimizable="true">
         <tns:extensions>
            <tns:extension name="js" resource-type="script"/>
         </tns:extensions>
      </tns:resource-folder>
   </tns:resources>
 
 
   <tns:extensions>
      <tns:extension id="oracle.bi.tech.currencyconversiondataaction" point-id="oracle.bi.tech.plugin.dataaction" version="1.0.0">
         <tns:configuration>
         {
            "resourceBundle": "obitech-currencyconversion/nls/messages",
            "properties":
            {
               "className": "obitech-currencyconversion/currencyconversion.CurrencyConversionDataAction",
               "displayName": { "key" : "CURRENCY_CONVERSION", "default" : "Currency Conversion" },
               "order": 100
            }
         }
         </tns:configuration>
      </tns:extension>
   </tns:extensions>
 
 
</tns:obiplugin>

データ・アクション・プラグインのファイルとフォルダ

データ・アクション・プラグインの実装には次のファイルとフォルダが使用されます。

bitech/client/plugins/src/

report
- obitech-report
  - scripts
    - dataaction
      - dataaction.js
      - dataactiongadgets.js
      - dataactionpanel.js
      - dataactionupgradehandler.js
obitech-reportservice
- scripts
  - dataaction
    - dataactionmanager.js
    - dataactionhandler.js