概要とサンプル
この章では、DeepSee 用の JavaScript API と REST API を紹介します。これらの API を使用すると、MDX クエリを実行して、DeepSee モデル要素に関する情報を取得できます。この章は、以下のセクションで構成されます。
Web アプリケーションの作成
どのようなシナリオでも (JavaScript API を使用するのか REST サービスを直接使用するのかにかかわらず)、Caché Web アプリケーションは要求を処理する必要があります。システム定義の Web アプリケーション (/api/deepsee) を使用することも、それとは別の Web アプリケーションを作成して使用することもできます。この Web アプリケーションの要件は以下のとおりです。
-
クライアントのファイルは、この Web アプリケーションによって提供されるディレクトリ構造内に配置する必要があります。"Caché Server Pages (CSP) の使用法" の “CSP アプリケーションの設定” を参照してください。
-
[ディスパッチ・クラス] オプションを指定する必要があります。このオプションでは、この Web アプリケーションが REST 要求を処理する方法を指定します。DeepSee の REST 要求については、以下のいずれかを使用します。
-
%Api.DeepSeeOpens in a new tab — 目的のクライアント・アプリケーションが異なるネームスペースに接続できる必要がある場合は、このクラスを使用します。この場合は、Caché サーバに接続する際に、使用するネームスペースを指定する必要があります。
システム定義の Web アプリケーション (/api/deepsee) は、このディスパッチ・クラスを使用します。
-
%DeepSee.REST.v1Opens in a new tab — REST 要求が特定のネームスペース (この Web アプリケーションのネームスペース) に結び付けられる必要がある場合は、このクラスを使用します。
-
DeepSee JavaScript API の概要
DeepSee JavaScript API は、install-dir/CSP/broker ディレクトリにある DeepSee.js ファイルによって提供されます。この JavaScript ライブラリを使用すると、JavaScript ベースのクライアントから DeepSee を操作できます。このライブラリ内の関数は、DeepSee 用の REST ベース API のラッパです。(この章で後述する REST API を直接使用することもできます。)
このライブラリを使用する手順は以下のとおりです。
-
Web アプリケーションを作成します (前のセクションを参照)。
または、Caché のインストール内容に含まれている /api/deepsee という Web アプリケーションを使用します。
-
JavaScript クライアント・コード内で、以下の手順を実行します。
-
DeepSee.js ファイルと zenCSLM.js ファイルをインクルードします(後者は Zen で使用されるライブラリであり、同じディレクトリにあります)。
-
DeepSee 接続オブジェクトを作成します。これには、Caché サーバに接続するために必要な情報が含まれています。
-
この接続オブジェクトを使用する DeepSee データ・コントローラ・オブジェクトを作成します。
このデータ・コントローラ・オブジェクトを使用すると、DeepSee データ・ソースを操作できます。DeepSee データ・ソースは、MDX クエリまたはピボット・テーブル名を通じて指定します。
-
データ・コントローラの runQuery() メソッドを使用します。データ・ソースが MDX クエリである場合は、DeepSee はそのクエリを実行します。データ・ソースがピボット・テーブルである場合は、DeepSee はそのピボット・テーブルで定義されたクエリを実行します。
-
データ・コントローラ・オブジェクトの他のメソッドを実行して、クエリ結果を調べたり、ドリル・ダウンやドリル・スルーなどを実行します。
次のサブセクションで詳細を説明します。
-
DeepSee.js ライブラリは、DeepSee のモデル要素に関する情報を提供するユーティリティ関数も提供します。これらを使用して、使用可能なキューブのリストや、キューブ内の使用可能なメジャーのリストなどを取得します。
DeepSee 接続の作成
DeepSee 接続オブジェクトを作成するには、次のようなコードを使用します。
connection = new DeepSeeConnection(username,password,host,application,namespace);
以下はその説明です。
-
username は、指定されたホストにアクセスできる Caché ユーザ名です。
-
password は、関連付けられたパスワードです。
-
host は、Caché が実行されているマシンのサーバ名です。
-
application は、Caché Web アプリケーションの名前です。
-
namespace は、アクセスするネームスペースの名前です (この情報が必要な場合)。Web アプリケーションがネームスペースに結び付けられている場合は、この引数は不要です。
DeepSee データ・コントローラの作成および使用
データ・コントローラ・オブジェクトを使用すると、DeepSee データ・ソースを操作できます。主な操作内容は以下のとおりです。
-
ページ・ロジックの適切な部分で (ページの読み込み時やボタンの押下時など)、DeepSee データ・コントローラを作成して、クエリを実行します。
データ・コントローラを作成する際は、データが得られたときに実行される 1 つまたは 2 つのコールバック関数を指定します。finalCallback は必須ですが、pendingCallback はオプションです。
-
保留中の結果が得られる場合は、DeepSee は pendingCallback で指定されたメソッドを呼び出します (指定されている場合)。
このメソッドは、ユーザによって記述され、データ・コントローラ・オブジェクトに含まれている結果を使用します。このメソッドは通常、ページ・コンテンツを描画します。
-
クエリが完了したら、DeepSee は finalCallback で指定されたメソッドを呼び出します。
このメソッドは、ユーザによって記述され、データ・コントローラ・オブジェクトに含まれている結果を使用します。このメソッドは通常、ページ・コンテンツを描画します。
クエリを実行するメソッドはすべて、上記の仕組みを使用します。詳細と例については、サブセクションを参照してください。他のメソッドは同期的にデータを返します。
DeepSee データ・コントローラの作成とクエリの実行
クライアント・コードの適切な部分で (ページ初期化ロジック内など)、以下の手順を実行します。
-
以下のプロパティを持つ構成オブジェクトを作成します。
-
connection — DeepSee データ・コネクタ・オブジェクトの名前を指定します。前のセクションを参照してください。
-
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 つのオブジェクトである結果セット・オブジェクトを返します。このオブジェクトは、クエリの結果を調べるためのメソッドを提供します。上記の例では、これらのメソッドのいくつかを示しています。
DeepSee REST API の概要
内部的には、この章で前述した JavaScript API は DeepSee REST API を使用します。ユーザは DeepSee REST API を直接使用することもできます。DeepSee REST API を使用する手順は以下のとおりです。
-
Web アプリケーションを作成します (本章の前述箇所を参照)。
または、Caché のインストール内容に含まれている /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 名でのスラッシュの使用
DeepSee キューブなどのアイテムの論理名では、スラッシュ (/) が比較的よく使用されます。スラッシュ文字は、フォルダ名と短いアイテム名を区切るための記号であるからです。例えば、キューブの論理名として RelatedCubes/Patients が考えられます。
URL パラメータ (および要求の本文) では、これらの論理名を変更せずに直接使用できます。該当する DeepSee REST サービスでは、スラッシュが含まれた論理名が考慮に入れられます。ただし、ロジックでは名前付け規約 (使用する予定の REST サービスに応じて異なります) に従うことが要求されます。具体的には、別の論理名で使用されているフォルダ名と同じ論理名を持つアイテムは避けてください。例えば、mycubes/test/test1 という名前のアイテムがある場合は、mycubes/test という名前のアイテムを避ける必要があります。
この制約の理由は、論理名の後ろに別の引数を使用している REST サービスを使用する際に、その名前の最初の部分が既存のアイテム名と一致する場合は、その名前の一部は別の引数として解釈されるからです。例えば、次の REST 呼び出しを考えてみてください。
http://localhost:57772/api/deepsee/v1/Info/FilterMembers/:mycubename/:filterspec
ここで、mycubename はキューブの論理名であり、filterspec はそのキューブによって提供されるフィルタの仕様です。次に、mycubes/test/test1 をキューブ名として指定した次の REST 呼び出しを考えてみてください。
http://localhost:57772/api/deepsee/v1/Info/FilterMembers/:mycubes/test/test1/:filterspec
スラッシュ文字を解釈するために、DeepSee はまず mycubes という名前のキューブを探してから、mycubes/test という名前のキューブを探すというように、順番にキューブを探していきます。DeepSee がこの見かけ上の名前に一致する最初のアイテムを見つけると、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 では、JavaScript ライブラリと REST API のサンプルが用意されています。
DeepSee.js を使用するサンプル
DeepSee JavaScript ライブラリ (DeepSee.js) を使用するサンプルについては、install-dir/CSP/samples ディレクトリを参照してください。サンプル HTML ページ testDataController.html では、JavaScript API のほとんどのメソッドがデモ実行されます。このサンプルを使用するには、ブラウザで次の形式の URL を開きます。
http://localhost:57772/CSP/samples/testDataController.html
ここで、localhost:57772 は Caché が実行されているサーバとポートです。
サンプル HTML ページ test3rdPartyCharts.html では、この API をサードパーティのグラフ作成ライブラリと組み合わせて使用する方法がデモンストレーションされます。このサンプルを使用するには、次の形式の URL を開きます。
http://localhost:57772/CSP/samples/test3rdPartyCharts.html
REST API を使用するサンプル
REST API を使用するサンプルの場合、ブラウザで次の形式の URL を開きます。
http://localhost:57772/CSP/samples/DeepSee.RESTClient.cls
ここで、localhost:57772 は Caché が実行されているサーバとポートです。
これで、Web ページ DeepSee.RESTClientOpens in a new tab が表示されます。これは SAMPLES ネームスペース内のクラスです。このクラスは、Caché Web アプリケーションのコンテキスト内で各 REST 呼び出しを実行することを可能にするテスト・ページです。このページは以下の 2 つの方法で使用できます。
-
[アプリケーション] には /api/deepsee を指定でき、[ネームスペース] にはネームスペースを指定できます。要求は指定されたネームスペースに転送されます。(SAMPLES ネームスペースは複数の DeepSee モデルを含んでいるため便利です。)
-
本章の前述箇所に従ってカスタム Web アプリケーションを作成する場合は、[アプリケーション] にそのアプリケーション名を指定します。
この場合は、[ネームスペース] フィールドには何も入力しないでください。
これらのオプションの下のページに、すべての DeepSee REST 呼び出しをリストしたテーブルがあります。REST 呼び出しを試行するには、次のようにします。
-
呼び出しに対応する列を選択します。
ページの左下の領域にその呼び出しの詳細が表示されます。
-
必要に応じて、ラベルの付いた入力フィールド ([:キューブ] など) に値を入力します。これらの入力フィールドは、URL の一部として必要な値を表します。
-
必要に応じて、要求の本文を大きめのボックスに入力します。または、[参照...] を選択して、要求の本文が含まれるファイルをアップロードします。
-
[実行] を押します。
-
ユーザ名とパスワードを入力するように求められた場合は、それらを入力して、[ログイン] を押します。
そうすると、ページの右下の領域に応答の本文が表示されます。この応答の上部に、使用された実際の URL が表示されます。
ブラウザ内で開発者ツールにアクセスして、それらのツールを使用して要求と応答を表示することも役に立ちます。