JS API コンポーネント

Yellowfin JavaScript API とは何か？

JavaScript API (JS API) は、外部の開発者がYellowfinのコンテンツを埋め込み、操作できるようにするツールです。一般的に、JS APIを参照する場合は、埋め込み機能を参照します。

Yellowfin 9でダッシュボードを導入した際に実施したJavaScriptのバンドル化の変更により、内部および外部のJavaScript オブジェクトに対して、同じコードをより簡単に使用する手段を作成することができました。

JS APIは数多くの部分で構成されています。JS APIを語る上で、オブジェクトが分類されるAPIのタイプが大きく分けて2つあり、それはロード APIとコンテンツ APIです。

ロード API

これらのAPIを使用することで、レポート、ダッシュボード、ストーリーなどのコンテンツをロードできます。これは、要求したオブジェクトのコンテンツ APIをロードする以外には、あまり多くの機能を提供しません。

yellowfin.reports.loadReport({ reportUUID : ‘auuid’ })

v9.6の時点では、ロード APIは外部JS APIを通してのみほぼ独占的に利用可能です。これらは、ダッシュボード、ストーリー、レポートのロード APIです。これらはすべて、単一のloadContent (loadReport、loadDashboardおよびloadStory) 関数を提供します。

これらの関数はすべて非同期に実行され、ロードされたコンテンツ APIでコンテンツのロード後に解決されるpromiseを返します。

コンテンツ API

コンテンツAPIは実際のコンテンツであり、非常に幅広いタイプを網羅しています。現在のところ、ストーリー、ダッシュボード、レポートという3つの最上位コンテンツ APIがあります。しかし、これらすべてのオブジェクトには子オブジェクトが含まれているため、より複雑になります。

コンテンツにフィルターが設定されている場合、レポートおよびダッシュボード APIの両方にフィルター APIが含まれます。これにより、開発者はフィルターオブジェクトにアクセスし、コードを使用して操作したり、イベントに反応したりすることができます。

レポート API

レポート APIを使用することで、コードを介して、ユーザーがレポート上で実行できる大部分の機能にアクセスすることができます。レポート上で発生するユーザーインタラクションのほとんどすべてが、現在ではレポート APIを介して実行されるようになりました。ただし、テーブル制御 (ページおよびセクション間の移動) とドリルスルーは例外です。

つまりユーザーは、タイムスライダー値、単位選択、シリーズ選択、並べかえ、ドリルダウン、ドリルエニウェアの適用など、UIで実行できるほとんどすべてのアクションをコードを介して実行できる必要があります。また、これらすべてのインタラクションにはイベントが関連付けられているため、開発者はこれらのイベントの発生をリッスンできます。これは、イベントが発生するたびに (コードの呼び出し、またはUIインタラクションを介して) トリガーされます。

理想的には、コード機能はUIと完全に一致する必要があります。そして、Yellowfinが将来的に実装するインタラクションは、まずAPIを介して実装され、その後それを中心にUIが構築される必要があります。

レポート APIは、フィルターに適用された値の変更をフィルター APIでリッスンします。これが発生した場合、APIはレポートの再実行をトリガーします。このトリガーには、再実行前の短い遅延 (100ミリ秒) が組み込まれているため、レポートに対して複数の変更を同時に実行できます。

出力タイプ

レポート APIには、registerOutputType 機能を使用してレポートの 「出力タイプ」 を取得する機能もあります。registerOutputTypeは、 「この情報も返す」 というリクエストをレポート実行に追加し、渡されるコールバックを提供します。つまり、レポートのフィルターが変更され、新しい実行がトリガーされた場合、渡されたコールバックは新しい結果が完了したときに完了します。

これにより、開発者はレポートデータセットや、カラム (列) の一意の値を取得し、今後のリリースで他の機能を返すことができようになります。

データセット

データセット出力タイプは、レポートのデータセット全体を返します。これは特定のデータ順で、データのみを含みます。レポート APIは、データセット順ですべてのレポートフィールドを返す関数 (getFieldsInDatasetOrder () ) を提供します。これにより、配列の位置に基づきフィールドとそのデータを一致させることができます。

uniqueValues

uniqueValues出力タイプは、渡されたフィールドのすべての個別の値を返します。これは、フィルターとして適用された場合に、結果を返す特定のディメンション (次元) のすべての値を取得する必要がある開発者にとって非常に役立ちます。

表示

レポート APIには、レポートに基づいてビジュアライゼーション要素を作成する機能もあります。

report.createReportElement (options);関数は、そのレポートに表示されるすべてのグラフ、表またはキャンバスのビジュアライゼーションを作成します。これらは同時に表示されます (そのため、グラフAとグラフBを並べて表示できます) 。

ダッシュボード API

ダッシュボードは、サブタブ、レポート、フィルター、キャンバス、ウィジェットなど、様々なサブタイプに基づいて構築されています。

ダッシュボードは、サブタブの集合体です。これら各サブタブは、以下のいずれかを含みます。

• 複数のレポートおよびウィジェットを配置することのできるキャンバス
• レポート、フィルター、特定のウィジェットを備えたグリッドレイアウト

ダッシュボード APIは、現在ユーザーがどのページにいるかをトラッキングするのに役立ち、ダッシュボード上のすべてのフィルターの状態を持つフィルター APIを提供します。ダッシュボード上にロードされるすべてのレポートは、このフィルター APIをリッスンするため、フィルターがリンクされている場合、レポート APIは、ダッシュボードなしでレポートを埋め込む場合と同様に、フィルターの変更をリッスンします。

サブタブ API

サブタブ APIは、渡されたダッシュボードタブに関するメタデータを提供します。このAPIが呼び出すことのできる関数が多くありませんが、サブタブ上のすべてのレポートを検索し、キャンバスがある場合はキャンバス APIを取得できます。

フィルター API

フィルター APIは、特定のコンテンツ上のフィルターの表現を提供します。これは、フィルター値を設定または取得したり、キャッシュされたレポートに使用できる値を更新したりする機能を提供します。

APIにはFilterObjectsのセットが含まれています。これは、コンテンツで使用可能な個々のフィルターのAPIオブジェクトです。

また、フィルター一覧要素を作成する機能も提供します。これにより、Yellowfinフィルター一覧をページ上の任意の場所に配置することができ、そのフィルター一覧に表示するフィルターをカスタマイズするオプションを提供します。

フィルター APIを使用すると、フィルター API全体でフィルターの変更をリッスンできるため、コンテンツ上のあらゆるフィルターが変更されても応答することができます。

フィルターオブジェクト

このオブジェクトは、フィルター API内の個別のフィルターを表します。これは、フィルターの状態を維持し、フィルター値が変更されたときにイベントをトリガーするために使用されます。

フィルターには、次の表に示す2つの値のセットがあります。

フィルターオブジェクトには、フィルター自体の個々の表示表現を作成する機能もあります。これは、通常のYellowfin フィルターと同じスタイルを使用しますが、フィルター一覧から完全に独立しています。

Loader events

Loader Events APIを使用することで、標準的なYellowfin ロードイベントをリッスンし、それらのイベントに応答できます。

これにより、ローダーが追加されないようにしたり、検出された際に異なる要素に添付したりすることができます。例えば、多数のレポートを含むキャンバスがある場合、キャンバス上の各レポートにローダーを添付する代わりに、キャンバスオブジェクト全体にローダーを添付し、すべてのレポートのレンダリングが終了した際にローダーを削除することができます。

内部JS APIおよび外部JS API

これは何を意味するのか？

「内部JS API」という用語を使用する場合、これは以下により使用されるツールを指します。

• Web アプリケーション機能を構築するYellowfin 開発チーム
• Yellowfin コードモードまたはカスタムヘッダーを使用する外部の開発者

「外部JS API」は、開発者が外部ページにYellowfin コンテンツを埋め込むために使用するツールを指します。

このように、Yellowfin JS APIは事実上2つあります。

外部JS APIは、Yellowfinのコンテンツを外部ページに埋め込む開発者向けに提供されています。外部JS APIについての詳細は、外部wikiにて提供しています。

内部JS APIは、Yellowfin 開発チームによって使用されています。外部の開発者は、Yellowfin コードモードまたはカスタムヘッダーを介してコードにアクセスするときに、知らないうちにこのバージョンのJS APIを使用しています。

各JS APIの詳細については、以下に示します。

外部JS API

JS APIを外部で使用する場合、Yellowfin ロード APIとコンテンツ APIのすべてにアクセスできます。つまり、コンテンツのUUIDを提供すれば、任意のコンテンツをロードできます。

ほとんどの場合、レポートまたはダッシュボードのリストサービスは、Yellowfin web サービスを使用してYellowfin コンテンツオブジェクトを取得し、それらのオブジェクトから提供されるUUIDを使用してJS APIにオブジェクトをロードすることで作成できます。これにより、Yellowfin レポート、ダッシュボードおよびストーリーを使用しながら、完全にカスタマイズされたUIを構築できるため、コンテンツ構築は開発者以外でも実現できます。

考慮点

Yellowfin サーバーは、サードパーティ製アプリケーションとして扱われるため、認証に問題が生じることがあります。そのため、サイト上のサードパーティ製Cookieを拒否するブラウザ (IncognitoモードのSafariおよびChrome) は、Yellowfin JS APIを拒否します。さらに、「Same Site」フラグに関するセキュリティの変更により、必要なすべてのCookieを受け入れるようにwebサーバーを構成することが困難になりました。

もうひとつの問題は、機能の動作方法の違いです。以下の表は、動作が異なる機能、または外部JS APIでまだ有効になっていない機能の一覧を示します。

内部JS API

現在Yellowfin JS APIは、外部JS API内に存在するロード APIにアクセスすることはできません。つまり、コンテンツをロードするには、Yellowfin アクションを使用する必要があります。これは外部の開発者は、レポートやその他のコンテンツの表示方法をあまり制御できないということです。まずは、Yellowfinによりロードし、(そして、ほとんどの場合) レンダリングをしなくてはいけません。

すべてのYellowfin コンテンツとその個々の機能は、コンテンツ APIと内部でレンダリングされるコンテンツで使用できます。そのため、Yellowfinでは一般的に、まず内部で機能を構築してから、外部で動作させるようにしています。

考慮点

コンテンツ APIは、コードモードを介してのみ使用することができます。これらにロード APIはありません。

そのため、カスタマイズされたアプリケーションエクスペリエンスを構築するのは困難です。コードモードではダッシュボードを大幅にカスタマイズできますが、そのダッシュボード内から追加のダッシュボードをロードしたり、追加されていないレポートをロードしたりすることはできません。