Base API - 高度なAPI

概要

このAPIは、ページに「JsAPI/v3」JSファイルが含まれているページでのみ使用できます。以下の例を参照してください。

高度なAPIには、Yellowfin APIを独自のウェブページにロードするのに役立つ多くの関数が含まれています。レポートおよびダッシュボードローダーAPIをロードする関数があり、ダッシュボードおよびレポートをロードできます。

セッション管理を支援する関数もあります。

init()

リターン

Promise

説明

Base APIを初期化します。これは、APIがページに含まれている時に呼び出されます。ロードが終了した時点で、APIの使用がこのPromiseが解決するまで待機することを示すPromiseを返します。

例

Yellowfin レポートAPIをページに含め、init() promiseが解決した後でレポートをロードします。

logoff()

リターン

なし

説明

現在のユーザーセッションを終了します。

yellowfin.newSession(token, org);（Yellowfin新規セッション）

リターン

Promise

説明

この関数は、現在のユーザーをログアウトし、渡されたwebサービスのセッショントークンを使用して、新規ユーザーをログインさせるためのリクエストをYellowfin JS APIに送信します。この関数は、セッショントークンとともに、オプションでクライアント組織IDも受け取ることで、ユーザーが特定のクライアント組織にログインできるようにします。

ログインアクションが正常に完了すると、関数はPromiseを返し、ページ上のすべてのレポートまたはダッシュボードが再実行されます。

loadReport(reportOptions)（レポートのロード）

リターン

Promise

説明

init() promiseがロードするの待ち、渡されたオプションでレポートをロードします。レポートがロードされると、渡されたelement（要素）が追加され、レポートの実行が開始されます。

promiseが解決されると、レポートオブジェクトは.then()関数に渡されます。promiseは、レポートの実行が開始される直前に解決されます。

オプションオブジェクトの一部として受け入れられるオプションがいくつかあります。

reportId（レポートID） - 必須

型：String

ロードするレポートのレポートUUIDです。これは、レポートヘッダーテーブルの公開UUIDです。

element（要素） - 必須

型：DOM Element、Selector String

レポートに描画するelement（要素）です。DOM element、またはページからelementを選択するために使用されるselectorのどちらかになります。

幅や高さが渡されない場合、レポートはelementの寸法に合わせて展開されます。

width（幅）

型：Number

レポートをピクセル単位で描画する幅です。

height（高さ）

型：Number

レポートをピクセル単位で描画する高さです。

filterValues（フィルター値）

型：Array[Object]

初期フィルター値を適用するために使用されるオブジェクトの配列です。

フィルター値についての詳細は、フィルター APIを参照してください。

オブジェクトには、次の情報が含まれます。

• filterId - 設定するフィルターのUUID、または名前です。
• valueOne - フィルターの最初の値です。
• valueTwo - フィルターの二番目の値です。Between（の間）、またはNot Between（の間ではない）フィルタータイプにのみ影響します。
• valueList - フィルター一覧に適用する値の配列です。

instanceName（インスタンス名）

型：String

レポートのインスタンスの識別子です。このプロパティが定義されない場合は、ランダムなIDが生成されます。つまり、インスタンス名を定義することなく同じレポートを複数回含めた場合、そのレポートは常に別のインスタンスになります。

これを設定すると、同じインスタンスのレポートの複数のビューをロードできるようになります。

showToolbar（ツールバーの表示）

型：Boolean

レポートツールバーを表示するかどうかを定義します。

または、showToolbarプロパティをfalseに設定します。

showTitle（タイトルの表示）

型：Boolean

レポートのツールバーにレポートタイトルを表示するかどうかを定義します。デフォルト：true

showTitle オプションをfalseに設定した場合：

showInfo（詳細の表示）

型：Boolean

レポートのツールバーに詳細オプションを表示するかどうかを定義します。デフォルト：true

このオプションをfalseに設定した場合：

showFilter（フィルターの表示）

型：Boolean

レポートのツールバーにフィルターオプションを表示するかどうかを定義します。デフォルト：true

このオプションをfalseに設定した場合：

showExport（エクスポートの表示）

型：Boolean

レポートのツールバーにエクスポートオプションを表示するかどうかを定義します。エクスポートオプションを使用することで、レポートをcsv、xls、pdf、txt、docなどの外部ファイル形式にエクスポートすることができます。

showExport パラメーターをfalseに設定する場合、ツールバー内のエクスポートアイコンは削除されます。

showShare（共有の表示）

型：Boolean

レポートのツールバーに共有オプションを表示するかどうかを定義します。デフォルトはtrueに設定されています。

showDisplayToggle（表示トグルの表示）

型：Boolean

レポートのツールバーにレポートのグラフ/表オプションを表示するかどうかを定義します。デフォルトはtrueに設定されています。

このオプションをfalseに設定した場合

例

レポートをロードして、その名前を出力します。

インタラクション

インタラクションオブジェクトは、特定のレポートのビジュアライゼーションでどのインタラクションを利用可能にするかを定義します。これにより、Yellowfin レンダラーに対して、そのビジュアライゼーション内でユーザーが使用できる機能を指定できます。

同じレポートを表す複数のelement（要素）があり、インタラクションを無効にしたい場合、表示しているすべてのelement（要素）でこれを無効にする必要があります。例えば、最初のelement（要素）のドリルダウンを無効にしてから、二番目のelement（要素）のドリルダウンを無効にしなかった場合、ユーザーは依然として二番目のelement（要素）のドリルダウンを実行できます。

デフォルトでは、明示的にfalseに設定されていないインタラクションはすべて有効と見なされ、レポートで許可されている場合は表示されます。

drillDown

ドリルダウン機能を無効にできます。

drillAnywhere

ドリルエニウェア機能を無効にできます。

drillThrough

ドリルスルー機能を無効にできます。

unitSelection

単位選択機能を無効にできます。

brushing

ブラッシング機能を無効にできます。

timeSlider

タイムスライダー機能を無効にできます。

drillBreadcrumbs

パンくずリスト機能を無効にできます。

seriesSelection

シリーズ選択機能を無効にできます。

annotations

注釈機能を無効にできます。

例

loadReportの使用時にレポート上のすべてのユーザーインタラクションを無効にするには、以下を参照してください。

loadDashboard(dashboardOptions)

リターン

Promise

説明

init()promiseがロードされるのを待ち、渡されたオプションでダッシュボードをロードします。ダッシュボードがロードされると、渡されたelement（要素）に追加され、ダッシュボード上のコンテンツの実行が開始されます。

dashboardOptionsオブジェクトには、いくつかのパラメーターを含めることができます。

dashboardUUI（ダッシュボードUUID） - 必須

型：String

ロードするダッシュボードの公開UUIDです。

element（要素） - 必須

型：DOM Element、Selector String

ダッシュボードに描画するelement（要素）です。DOM element、またはページからselectorの最初のインスタンスを選択するために使用されるselectorのどちらかになります。

幅や高さが渡されない場合、ダッシュボードはelement（要素）の寸法に合わせて表示されます。

filterValues（フィルター値）

型：Array[Object]

ダッシュボードの初期フィルター値を適用するために使用されるオブジェクトの配列です。

フィルター値についての詳細は、フィルター APIを参照してください。

オブジェクトには、次の情報が含まれます。

• filterId - 設定するフィルターのUUID、または名前です。
• valueOne - フィルターの最初の値です。
• valueTwo - フィルターの二番目の値です。Between（の間）、またはNot Between（の間ではない）フィルタータイプにのみ影響します。
• valueList - フィルター一覧に適用する値の配列です。

showToolbar（ツールバーの表示）

型：Boolean

ダッシュボードのツールバーを表示するかどうかを定義します。デフォルトではtrueに設定されています。

以下は、ツールバーが表示されたダッシュボードです。

しかし、showToolbar プロパティをfalseに設定した場合：

showInfo（詳細の表示）

型：Boolean

ダッシュボードのツールバーに詳細オプションを表示するかどうかを定義します。デフォルト：true

このオプションをfalseに設定した場合：

showShare（共有の表示）

型：Boolean

ダッシュボードのツールバーに共有オプションを表示するかどうかを定義します。デフォルトはtrueに設定されています。

このオプションをfalseに設定した場合：

showFilters（フィルターの表示）

型：Boolean

ダッシュボードのツールバーにフィルターオプションを表示するかどうかを定義します。デフォルトはtrueに設定されています。

このオプションをfalseに設定した場合：

scaleCanvasTabs（キャンバスタブのスケール）

型：Boolean

キャンバスタブをスケールするかどうかを定義します。デフォルトはtrueに設定されています。

これをfalseに設定した場合、キャンバスタブは作成された通りのサイズで表示されます。この設定は、キャンバスタブを含まないサブタブでは無効です。

showGlobalContentContainer（グローバルコンテンツコンテナーの表示）

ダッシュボードの描画時にグローバルコンテンツコンテナーを表示するかどうかを定義します。

高度なAPIを使用したストーリーの組み込み

Yellowfin 9.4から、ストーリーの公開UUIDを使用して、ストーリーを組み込むことができるようになりました（より詳細な情報は、Yellowfin コンテンツの組み込みでのJS APIページを参照してください）。

高度なAPIツールセットを使用することで、ストーリー組み込み時に利用できるオプションを拡張するため、ニーズに合わせてストーリーのルックアンドフィールを調整することができます。共同編集者を非表示にしたり、組み込まれたストーリーの幅を制限したりすることができますが、これは高度なAPIを使用することで実現できます。

高度なAPI

新しいオブジェクトであるストーリーが、Yellowfin オブジェクトに追加されます。次のコードは、高度なAPIを使用して、ストーリーを読み込む一般的な方法の例です。

<script src="http://yellowfinServer/JsAPI/v3"></script>
<div id="myStoryDiv"></div>
<script>
    yellowfin.stories.loadStory({
         storyUUID: 'a-story-uuid', //This should be the story's publish uuid
         element: document.querySelector('#myStoryDiv') //The div to render the story into
    });
</script>

yellowfin.stories

現在、yellowfin.storiesは、上記のようにストーリーを読み込むひとつの関数（loadStory）しか含めることができません。しかし、loadStory関数には複数のオプションがあります。その関数およびオプションの概要を以下に示します。

loadStory(options);（ストーリーの読み込み）

詳細

リターン：Promise

Promise パラメーター：storyAPI

説明

この関数は、渡されたoptions.storyUUIDに関連するストーリーを読み込み、完了すると解決されたPromiseを返します。

解決されたPromiseは、storyAPI オブジェクトを渡します。

オプションオブジェクトに追加できる値は、以下の通りです。

storyUUID（ストーリーUUID）

詳細

埋め込みリンクオプション：?StoryUUID=uuid（これは組み込むストーリーの公開UUIDです。これがクエリー文字列の後ろの方に表示される場合は、忘れずに?を&に変更してください）

説明

このオプションは必須です。これが渡されない場合は、loadStoryの呼び出しは失敗します。

element（要素）

この関数の埋め込みリンクオプションはありません。

これは、ストーリーをレンダリングする要素です。

showToolbar（ツールバーの表示）

詳細

埋め込みリンクパラメーター：&showToolbar=ture（または、これが文字列で最初の要素の場合、他の文字列のように、接頭辞を&から?に変更します）

デフォルト値：true

説明

このオプションは、組み込みストーリーでJS API ツールバーを表示するかどうかを決定します。

showInfo（詳細の表示）

詳細

埋め込みリンクパラメーター：&showInfo=true（または、これが文字列で最初の要素の場合、他の文字列のように、接頭辞を&から?に変更します）

デフォルト値：true

説明

このオプションは、組み込みストーリーの詳細ドロップダウンを表示するかどうかを決定します。

showExport（エクスポートの表示）

詳細

埋め込みリンクパラメーター：&showExport=true（または、これが文字列で最初の要素の場合、他の文字列のように、接頭辞を&から?に変更します）

デフォルト値：true

説明

このオプションは、ストーリーの閲覧者に、組み込みストーリーのPDFエクスポートオプションを表示するかどうかを決定します。

showBannerImage（バナーイメージの表示）

詳細

埋め込みリンクパラメーター：&showBannerImage=true（または、これが文字列で最初の要素の場合、他の文字列のように、接頭辞を&から?に変更します）

デフォルト値：true

説明

このオプションは、組み込みストーリーのバナーイメージを表示するかどうかを決定します。

showHeader（ヘッダーの表示）

詳細

埋め込みリンクパラメーター：&showHeader=true（または、これが文字列で最初の要素の場合、他の文字列のように、接頭辞を&から?に変更します）

デフォルト値：true

説明

このオプションは、組み込みストーリーのヘッダーを表示するかどうかを決定します。

ストーリーのヘッダーには、記事を書いた人とその公開日、記事を読んだ人と拍手の数が表示されます。これらを表示するには、このshowHeaderオプションを含め、trueに設定しなくてはいけません。こちらのオプションをtrueに設定し、含めることのできる4つの要素をオフにすると、空白のバナーが表示されます。

showAuthor（記事を書いた人の表示）

詳細

埋め込みリンクパラメーター：&showAuthor=true（または、これが文字列で最初の要素の場合、他の文字列のように、接頭辞を&から?に変更します）

デフォルト値：true

説明

このオプションは、組み込みストーリーに、その記事を書いた人を表示するかどうかを決定します。こちらがtrueに設定されていたとしても、showHeaderオプションもtrueに設定されている場合のみ、記事を書いた人が表示されます。

showDateContainer（日付コンテナの表示）

詳細

埋め込みリンクパラメーター：&showDateContainer=true（または、これが文字列で最初の要素の場合、他の文字列のように、接頭辞を&から?に変更します）

デフォルト値：true

説明

このオプションは、組み込みストーリーの公開日を表示するかどうかを決定します。こちらがtrueに設定されていたとしても、showHeaderオプションもtrueに設定されている場合のみ、公開日が表示されます。

showLikeButton（拍手ボタンの表示）

詳細

埋め込みリンクパラメーター：&showLikeButton=true（または、これが文字列で最初の要素の場合、他の文字列のように、接頭辞を&から?に変更します）

デフォルト値：true

説明

このオプションは、ストーリーに拍手ボタンを表示するかどうかを決定します。こちらがtrueに設定されていたとしても、showHeaderオプションもtrueに設定されている場合のみ、拍手ボタンが表示されます。認証されていないゲストは、このボタンを使用できません。

showReadBy（ストーリーを読んだ人の表示）

詳細

埋め込みリンクパラメーター：&showReadBy=true（または、これが文字列で最初の要素の場合、他の文字列のように、接頭辞を&から?に変更します）

デフォルト値：true

説明

このオプションは、組み込みストーリーを読んだ人の一覧を表示するかどうかを決定します。こちらがtrueに設定されていたとしても、showHeaderオプションもtrueに設定されている場合のみ、ストーリーを読んだ人の一覧が表示されます。

showStoryTitle（ストーリータイトルの表示）

詳細

埋め込みリンクパラメーター：&showStoryTitle=true（または、これが文字列で最初の要素の場合、他の文字列のように、接頭辞を&から?に変更します）

デフォルト値：true

説明

このオプションは、組み込みストーリーのタイトルを表示するかどうかを決定します。

showFooter（フッターの表示）

詳細

埋め込みリンクパラメーター：&showFooter=true（または、これが文字列で最初の要素の場合、他の文字列のように、接頭辞を&から?に変更します）

デフォルト値：true

説明

このオプションは、組み込みストーリーのフッターを表示するかどうかを決定します。

ストーリーのフッターには、共同編集者が表示されます。共同編集者の一覧を表示するには、showFooterオプションを含めて、trueに設定しなくてはいけません。

showContributors（共同編集者の表示）

詳細

埋め込みリンクパラメーター：&showContributors=true（または、これが文字列で最初の要素の場合、他の文字列のように、接頭辞を&から?に変更します）

デフォルト値：true

説明

このオプションは、ストーリーの組み込み時に、共同編集者の一覧を表示するかどうかを決定します。こちらがtrueに設定されていたとしても、showFooterオプションもtrueに設定されている場合のみ、共同編集者の一覧が表示されます。

width（幅）

詳細

埋め込みリンクパラメーター：&width=xxx（xxxには数字が入ります。これが文字列で最初の要素の場合、他の文字列のように、接頭辞を&から?に変更します）

デフォルト値：element（要素）の幅

説明

このオプションは、組み込みストーリー全体の幅を設定します。

storyWidth（ストーリーの幅）

詳細

埋め込みリンクパラメーター：&storyWidth=xxx（xxxには数字が入ります。これが文字列で最初の要素の場合、他の文字列のように、接頭辞を&から?に変更します）

デフォルト値：width（幅）の4分の3

説明

このオプションは、組み込みストーリー本文の幅を設定します（バナーは含みません）。ストーリーの大部分のコンテンツの幅は、最大幅（例：ワイドモードのイメージ）で表示するように設定されていない限り、200pxより小さくなります。

bannerImageHeight（バナーイメージの高さ）

詳細

埋め込みリンクパラメーター：&bannerImageHeight=xxx（xxxには数字が入ります。これが文字列で最初の要素の場合、他の文字列のように、接頭辞を&から?に変更します）

デフォルト値：300px

説明

このオプションは、バナーイメージコンテナに適用されるカスタマイズされた高さを設定します。最適な結果を得るために、この設定を使用する場合は、バナーの幅を設定することも推奨します。

bannerImageWidth（バナーイメージの幅）

詳細

埋め込みリンクパラメーター：&bannerImageWidth=xxx（xxxには数字が入ります。これが文字列で最初の要素の場合、他の文字列のように、接頭辞を&から?に変更します）

デフォルト値：width（幅）の値

説明

このオプションは、バナーイメージに適用されるカスタマイズされた幅を設定します。最適な結果を得るために、この設定を使用する場合は、バナーの高さを設定することも推奨します。

loadStoryAPI()（ストーリーAPIの読み込み）

ストーリーを読み込むことができるように、StoryAPIを読み込み、API読み込み時に解決されるPromiseを返します。

loadStory(options)（ストーリーの読み込み（オプション））

**これは、yellowfin.stories.loadReportに対する単なるパススルーオプションです。渡されるオプションは同じである必要があり、ストーリーの読み込みを試行する前に、ストーリーオブジェクトが読み込まれることを保証するだけです。

StoryAPIで利用できる関数

• likeStory()
• unlikeStory()
• toggleLike(shouldLike:boolean => デフォルト値は現在の値の逆数
• getCurrentLikeStatus(successFunction: 現在のステータスを受信した時に呼び出す関数）=> サーバからステータスを取得
• storyContributors()
• storyReaders()

例：

src="<%=YF URL%>/JsAPI/v3?StoryUUID=<%=Story Publish UUID%>&showHeader=false&bannerImageWidth=500"></script>

高度なAPIの例：

HTML：

<script src="<%=YF URL%>/JsAPI/v3"></script>
 
<div id="storyContainer"></div>

JavaScript：

window.yellowfin.loadStoryAPI().then(() => {
    window.yellowfin.stories.loadStory(
{         storyUUID: '<%=Story Publish UUID%>',          element: 'div#storyContainer'     }
).then((storyAPI) =>
{         console.log(storyAPI);         window.storyAPI = storyAPI;     }
);
});

高度なAPIによるガイド付きNLQの設定

JS APIには、ガイド付きNLQを設定するために2つの方法があります。

• 高度なAPI経由
• 組み込みリンク経由

高度なAPI

高度なAPIは、多くの複雑なオブジェクトが導入されており、さまざまなガイド付きNLQビューを設定方法ができます。

シンプルなアプローチは：

yellowfin.loadNLQ();

これにより、ガイド付きNLQライトボックスが組み込みページに読み込まれ、アプリケーション内でネイティブに機能するのと同じように機能するようになります。

このアプローチは、下記の設定がデフォルトとして使用されます。

contentIntegrationOptions: {
    controls: ['SAVE']
}
 When you called yellowfin.loadNLQ(); you are essentially calling:
yellowfin.loadNLQ({
   contentIntegrationOptions: {
      controls: ['SAVE']
   } 
});

高度なAPIを使用しているガイド付きNLQを読み込む際に、下記のオプションを定義することができます。

element

詳細

タイプ：DOM Element Or String

説明

このオプションを使って、ガイド付きNLQUIがレンダリングされているelementを定義します。文字列を渡した場合、JS APIはdocument.querySelector(stringValue)を使用して、ページからelementを取得しようとします。

yellowfin.loadNLQ({
    element: document.querySelector(‘#myElement’)
});

ガイド付きNLQのアイテムがelementに読み込まれます。

文字列またやDOM elementが渡されない場合、ガイド付きNLQ UIはライトボックスに読み込まれます。

注意：この方法でelementを定義した場合、NLQ UIでは「閉じる」ボタンが非表示になります。

contentIntegration

詳細

タイプ：Object

説明

ユーザーが利用てきるコンテンツ統合オプションを定義します。

このオブジェクトは、定義されるいくつかのサブオブジェクトがあります（詳細およびデフォルトについては以下を参照してください）。これにより、統合コントロールの配列を定義することができます。下記の例のように、SAVEとADD_TOのコントロールが配列に含まれています。

controls

タイプ: String[]

yellowfin.loadNLQ({
    contentIntegrationOptions: {
        controls: [‘SAVE’, ‘ADD_TO’]
    }
});

この配列で渡せる値は、

SAVE control

このSave controlは、このクエリか完了した後に「保存」ボタンを表示します。ユーザーがレポートを作成する権限を持っていない場合は、SAVEが定義されていてもこのオプションは表示されません。

yellowfin.loadNLQ({
    contentIntegrationOptions: {
        controls: [‘SAVE’]
    }
})

ADD_TO control

このADD＿TOは、権限を持ったユーザーがガイド付きNLQで得た回答をストーリー、ダッシュボード、プレゼンテーションに追加する「追加」ボタンを表示します。

yellowfin.loadNLQ({
contentIntegrationOptions: {
controls: [‘SAVE’, ‘ADD_TO’]
}
});