Business Intelligence の使用法

ここでは、InterSystems IRIS® Business Intelligence. 用の JavaScript API と REST API の概要を示します。これらの API を使用すると、MDX クエリを実行して、Business Intelligence モデルの要素に関する情報を取得できます。

Web アプリケーションの作成

どのようなシナリオでも (JavaScript API を使用するのか REST サービスを直接使用するのかにかかわらず)、Web アプリケーションは要求を処理する必要があります。システム定義の Web アプリケーション (/api/deepsee) を使用することも、それとは別の Web アプリケーションを作成して使用することもできます。この Web アプリケーションの要件は以下のとおりです。

クライアントのファイルは、この Web アプリケーションによって提供されるディレクトリ構造内に配置する必要があります。
[ディスパッチ・クラス] オプションを指定する必要があります。このオプションでは、この Web アプリケーションが REST 要求を処理する方法を指定します。Business Intelligence の REST 要求については、以下のいずれかを使用します。
- %Api.DeepSeeOpens in a new tab — 目的のクライアント・アプリケーションが異なるネームスペースに接続できる必要がある場合は、このクラスを使用します。この場合は、InterSystems IRIS サーバに接続する際に、使用するネームスペースを指定する必要があります。
  システム定義の Web アプリケーション (/api/deepsee) は、このディスパッチ・クラスを使用します。
- %DeepSee.REST.v1Opens in a new tab — REST 要求が特定のネームスペース (この Web アプリケーションのネームスペース) に結び付けられる必要がある場合は、このクラスを使用します。

Business Intelligence JavaScript API の概要

Business Intelligence JavaScript API は、install-dir/CSP/broker ディレクトリにある DeepSee.js ファイルによって提供されます。この JavaScript ライブラリを使用すると、JavaScript ベースのクライアントから Business Intelligence を操作できます。このライブラリ内の関数は、Business Intelligence 用の REST ベース API のラッパです (REST API を直接使用することもできます)。

このライブラリを使用する手順は以下のとおりです。

Web アプリケーションを作成します (前のセクションを参照)。
または、インストール内容に含まれている /api/deepsee という Web アプリケーションを使用します。
JavaScript クライアント・コード内で、以下の手順を実行します。
1. DeepSee.js ファイルと zenCSLM.js ファイルをインクルードします
2. Business Intelligence 接続オブジェクトを作成します。これには、InterSystems IRIS サーバに接続するために必要な情報が含まれています。
3. この接続オブジェクトを使用する Business Intelligence データ・コントローラ・オブジェクトを作成します。
  このデータ・コントローラ・オブジェクトを使用すると、Business Intelligence データ・ソースを操作できます。このデータ・ソースは、MDX クエリまたはピボット・テーブル名を通じて指定します。
4. データ・コントローラの runQuery() メソッドを使用します。データ・ソースが MDX クエリである場合、Business Intelligence はそのクエリを実行します。データ・ソースがピボット・テーブルである場合、Business Intelligence はそのピボット・テーブルで定義されたクエリを実行します。
5. データ・コントローラ・オブジェクトの他のメソッドを実行して、クエリ結果を調べたり、ドリル・ダウンやドリル・スルーなどを実行します。
次のサブセクションで詳細を説明します。

DeepSee.js ライブラリは、Business Intelligence のモデル要素に関する情報を提供するユーティリティ関数も提供します。これらを使用して、使用可能なキューブのリストや、キューブ内の使用可能なメジャーのリストなどを取得します。

Business Intelligence 接続の作成

Business Intelligence 接続オブジェクトを作成するには、次のようなコードを使用します。

connection = new DeepSeeConnection(username,password,host,application,namespace);

以下はその説明です。

username は、指定されたホストにアクセスできる InterSystems IRIS ユーザ名です。
password は、関連付けられたパスワードです。
host は、InterSystems IRIS を実行しているマシンのサーバ名です。
application は、Web アプリケーションの名前です。
namespace は、アクセスするネームスペースの名前です。Web アプリケーションがネームスペースに結び付けられている場合は、この引数は不要です。

Business Intelligence データ・コントローラの作成および使用

データ・コントローラ・オブジェクトを使用すると、Business Intelligence データ・ソースを操作できます。主な操作内容は以下のとおりです。

ページ・ロジックの適切な部分で (ページの読み込み時やボタンの押下時など)、Business Intelligence データ・コントローラを作成して、クエリを実行します。
データ・コントローラを作成する際は、データが得られたときに実行される 1 つまたは 2 つのコールバック関数を指定します。finalCallback は必須ですが、pendingCallback はオプションです。
保留中の結果が得られる場合、Business Intelligence は pendingCallback で指定されたメソッドを呼び出します (指定されている場合)。
このメソッドは、ユーザによって記述され、データ・コントローラ・オブジェクトに含まれている結果を使用します。このメソッドは通常、ページ・コンテンツを描画します。
クエリが完了したら、Business Intelligence は finalCallback で指定されたメソッドを呼び出します。
このメソッドは、ユーザによって記述され、データ・コントローラ・オブジェクトに含まれている結果を使用します。このメソッドは通常、ページ・コンテンツを描画します。

クエリを実行するメソッドはすべて、上記の仕組みを使用します。詳細と例については、サブセクションを参照してください。他のメソッドは同期的にデータを返します。

Business Intelligence データ・コントローラの作成とクエリの実行

クライアント・コードの適切な部分で (ページ初期化ロジック内など)、以下の手順を実行します。

以下のプロパティを持つ構成オブジェクトを作成します。
- connection — Business Intelligence データ・コネクタ・オブジェクトの名前を指定します。前のセクションを参照してください。
- widget — データ・コントローラを使用するページ上の HTML 要素の ID を指定します。
- type — データ・ソースのタイプとして 'MDX' または 'PIVOT' を指定します。
- initialMDX — MDX SELECT クエリを指定します (このプロパティは type が 'MDX' の場合に使用します)。
- pivotName — ピボット・テーブルの論理名を指定します (このプロパティは type が 'PIVOT' の場合に使用します)。
- showTotals — 合計を表示するかどうかを指定します。true または false を指定します。
次のようなコードを使用してデータ・コントローラ・オブジェクトを作成します。
```
var dc = new DeepSeeDataController(configuration,finalCallback,pendingCallback);
```
ここで、configuration は前の手順で作成した構成オブジェクトであり、finalCallback はこのページ上のコールバック関数の名前であり、pendingCallback はこのページ上のもう 1 つのコールバック関数の名前です。finalCallback は必須ですが、pendingCallback はオプションです。
データ・コントローラの runQuery() メソッドを呼び出します。または、クエリを実行する他のメソッド (runDrillDown() や runListing() など) を実行します。

次に例を示します。

function initializePage() {
               ...
                    configuration.connection = new DeepSeeConnection(username,password,host,application,namespace);
                    dc = new DeepSeeDataController(configuration,drawChart);
                    dc.runQuery();
            }

データ・コントローラによって返されたデータの使用

ページでは、前の手順で示したコールバック関数を実装する必要もあります。これらのコールバックは、データ・コントローラ・オブジェクトから取得されたデータを使用して、ページを必要に応じて更新します。

それぞれの場合に、データ・コントローラ・オブジェクトが引数として関数に渡されます。

以下は、部分的な例です。

function drawChart(dataController) {

    var resultSet = dataController.getCurrentData();
    ...
    var chartDataPoint;
    var chartLabel;
    var chartData = [];

    for (var i = 1; i <= resultSet.getRowCount(); ++i) {
        for (var j = 1; j <= resultSet.getColumnCount(); ++j) {
            chartDataPoint = resultSet.getOrdinalValue(i,j);
            chartLabel = resultSet.getOrdinalLabel(2,i);
            chartData[chartData.length] = { "country":chartLabel[0],"revenue":chartDataPoint};
        }
    }
    ...

データ・コントローラの getCurrentData() メソッドは、もう 1 つのオブジェクトである結果セット・オブジェクトを返します。このオブジェクトは、クエリの結果を調べるためのメソッドを提供します。上記の例では、これらのメソッドのいくつかを示しています。

Business Intelligence REST API の概要

内部的には、JavaScript API は Business Intelligence REST API を使用します。この REST API は、以下のように直接使用することもできます。

Web アプリケーションを作成します。
または、インストール内容に含まれている /api/deepsee という Web アプリケーションを使用します。
JavaScript クライアント・コード内で、HTTP 要求を作成して、目的のターゲット REST サービスに送信します。
ディスパッチ・クラス %Api.DeepSeeOpens in a new tab を使用している場合は、次の形式のターゲット URL を使用します。
```
/baseURL/api/deepsee/v1/namespace/RESTcallname
```
ここで、baseURL はサーバを指定し、namespace はターゲット・ネームスペースであり、RESTcallname は実際の REST 呼び出し (/Info/Cubes など) です。次に例を示します。
```
/mycompany/api/deepsee/v1/myapplication/Info/Cubes
```
ディスパッチ・クラス %DeepSee.REST.v1Opens in a new tab を使用している場合は、次の形式のターゲット URL を使用します。
```
/baseURL/api/deepsee/v1/RESTcallname
```
次に例を示します。
```
/mycompany/api/deepsee/v1/Info/Cubes
```
Note:

クライアントは、JSON を受け入れる必要があります。要求の Accept ヘッダは、application/json を指定するか、形式を宣言しない必要があります。
応答オブジェクトを調べて、適宜使用します。

キューブ名と KPI 名でのスラッシュの使用

キューブなどのアイテムの論理名では、スラッシュ (/) が比較的よく使用されます。スラッシュ文字は、フォルダ名と短いアイテム名を区切るための記号であるからです。例えば、キューブの論理名として RelatedCubes/Patients が考えられます。

URL パラメータ (および要求の本文) では、これらの論理名を変更せずに直接使用できます。該当する Business Intelligence REST サービスでは、スラッシュが含まれた論理名が考慮に入れられます。ただし、ロジックでは名前付け規約 (使用する予定の REST サービスに応じて異なります) に従うことが要求されます。具体的には、別の論理名で使用されているフォルダ名と同じ論理名を持つアイテムは避けてください。例えば、mycubes/test/test1 という名前のアイテムがある場合は、mycubes/test という名前のアイテムを避ける必要があります。

この制約の理由は、論理名の後ろに別の引数を使用している REST サービスを使用する際に、その名前の最初の部分が既存のアイテム名と一致する場合は、その名前の一部は別の引数として解釈されるからです。例えば、次の REST 呼び出しを考えてみてください。

http://localhost:52773/api/deepsee/v1/Info/FilterMembers/:mycubename/:filterspec

ここで、mycubename はキューブの論理名であり、filterspec はそのキューブによって提供されるフィルタの仕様です。次に、mycubes/test/test1 をキューブ名として指定した次の REST 呼び出しを考えてみてください。

http://localhost:52773/api/deepsee/v1/Info/FilterMembers/:mycubes/test/test1/:filterspec

スラッシュ文字を解釈するために、システムは、最初に mycubes という名前のキューブを探してから、mycubes/test という名前のキューブを探すというように、順番にキューブを探していきます。システムがこの見かけ上の名前に一致する最初のアイテムを見つけると、REST 呼び出しではそのアイテムが使用され、文字列の残り部分は次の引数として解釈されます。

応答オブジェクトに関する注意事項

ほとんどの REST 呼び出しについて、応答オブジェクトには Info プロパティが含まれています。このプロパティには要求と応答に関する情報が含まれています。このオブジェクトには、次のいずれかに該当する Error プロパティが含まれています。

NULL — これはエラーが発生しなかったことを意味します。
ErrorCode プロパティと ErrorMessage プロパティが含まれたオブジェクト — このオブジェクトに含まれているエラー情報に基づいて、ユーザは処理を進めるのかどうかと処理の進め方を決定できます。

エラーが発生していない場合は、応答オブジェクトには、要求された値が格納されたオブジェクトである Result プロパティも含まれています。

一般に、クライアント・コードではまず Info.Error プロパティを確認してから、処理の進め方を決定する必要があります。

例えば、以下のような応答オブジェクトが考えられます (読みやすいように空白を追加しています)。

{"Info":
            {"Error":
                {"ErrorCode":"5001","ErrorMessage":"ERROR #5001: Cannot find Subject Area: 'SampleCube'"}
            }
        }

対照的に、エラーが発生していない場合は、Info.Error プロパティは NULL であり、Result には要求した結果が含まれています。次に例を示します。

{"Info":
            {"Error":"",
            "BaseCube":"DemoMDX",
            "SkipCalculated":0},
            "Result":
            {"Measures":
                [
                    {"name":"%COUNT","caption":"%COUNT","type":"integer","hidden":0,"factName":""},
                    {"name":"Age","caption":"Age","type":"integer","hidden":0,"factName":"MxAge"}
                ...]
            }
        }

DeepSee.js