レポート API
レポート APIは、レポートの状態を制御します。これには、現在のドリルの状態、並べかえ条件、フィルター値、適用されたその他のレポートインタラクションを含む、現在のレポートの状態に関する情報が含まれます。
レポート APIは、レポートの実際の実行も制御し、レポートの実行時にすべてのインタラクションをYellowfin サーバへ送信します。また、ユーザーアクション、または事項かされた開発者アクションによりレポートに対してアクションが実行されると、APIは多数のイベントのトリガーになります。
デフォルトグラフIDおよびグラフID
レポートには複数のグラフを含めることができます。各グラフはグラフID、およびグラフUUIDを持ちます。グラフIDは、レポートが編集され、再度公開されるたびに変更されますが、グラフUUIDは常に同じです。グラフIDを必要とするすべての機能は、同様にグラフUUIDも受け付けますが、グラフIDを要求されるすべての機能で、変化することのないグラフUUIDの使用を推奨します。
また、レポートで最初に使用できる「デフォルトグラフ」があります。使用可能なグラフとは、フィールドが割り当てられているグラフのことです。グラフIDを必要とする関数にこれが渡されていない場合は、デフォルトグラフが使用されます。
グラフのプロパティを使用することで、レポート上のすべてのグラフにアクセスできます。
フィールドID
レポートには、複数のフィールドが含まれます。これらのフィールドは、レポートのコンテキストの中で、一意のIDを持ちます。このIDは、レポートが編集されて変更されることはありません。getFieldId(fieldName)という関数を使用することで、フィールド名を基に、フィールドIDを取得することができます。フィールドIDを受け付ける関数の大部分はフィールド名を受け付けることもでき、渡された名前を基にフィールド名の検索を試みます。
フィールドのプロパティを使用することで、レポート上のすべてのフイールドにアクセスできます。
ドリル
ドリルエニウェア、またはドリルダウンが適用されたフィールドのプロセスは、次の通りです。
非公開フィルターにドリル値を適用する
ドリルダウンしていたフィールドを、ドリル先のフィールドに置き換えます。
新しいフィールドとフィルターを使用してクエリーを実行します。
レポートにはカラム（列）がひとつだけとして、非常にシンプルなドリルの例を挙げます。スキーチームビュー（Yellowfinのチュートリアルコンテンツにバンドル）には、「Agency Type」というフィールドがあり、「Agency Name」にドリルする階層が設定されています。「Agency Type」フィールドにドリルダウンが適用された場合、レポートロジックは、「Agency Name」フィールドへドリルダウンすることを把握しています。
レポートを最初に実行すると、SQLは次のようになります。
「Agency」値にドリルダウンが適用されると、SQL内で「Agency Type」が置き換えられ、Agency Typeフィルターも追加されます。
ドリルエニウェアも同様に機能しますが、定義済みの「ドリル先」フィールドが無いため、ユーザー（または、APIの呼び出しを使用している場合は開発者）は、ドリル先のフィールドを定義しなくてはいけません。
プロパティのリファレンス
name（名前）
リターン
String
説明
レポートの名前を返します。これは、翻訳が有効化され、その言語の翻訳が提供されている場合、ユーザーの使用言語に翻訳されます。
reportUUID（レポートUUID）
リターン
String
説明
レポートのUUIDを返します。
entityUUID（エンティティUUID）
リターン
説明
このインスタンスのレポートに固有の識別子です。これは、レポートがダッシュボードに追加されたときに定義されます。それ以外の場合は、nullになります。
filters（フィルター）
リターン
フィルター API
説明
レポートのフィルター APIを返します。このレポートがダッシュボードに含まれている場合は、フィルター APIは、ダッシュボードのフィルター APIと同じになります。
fields（フィールド）
リターン
Array[ReportField]
説明
レポートのフィールドの順序付き配列を返します。
charts（グラフ）
リターン
Object{String, ReportChart}
説明
グラフUUIDでキー設定がされた、レポート上のすべてのレポートグラフを含むオブジェクトを返します。
reportKey（レポートキー）
リターン
String
説明
レポートオブジェクトのどのインスタンスを使用するかを正確に識別するために使用されるレポートの一意の識別子です。多くのイベントは、情報の一部としてこれを含みます。
関数のリファレンス
getFieldId(fieldName)（フィールドIDの取得）
リターン
Number
説明
渡されたフィールド名のフィールドIDを返します。一致するフィールドが見つからない場合は、nullを返します。
例
「Invoiced」フィールドのフィールドIDを取得します。
getFieldName(filedId)（フィールド名の取得）
リターン
String
説明
渡されたフィールドIDのフィールド名を返します。一致するフィールドが見つからない場合は、nullを返します。
例
特定のフィールドがドリルダウンされたことをログに記録します。
getChartId(chartId)（グラフIDの取得）
リターン
Number
説明
渡されたグラフ名、またはグラフUUIDの内部グラフIDを返します。グラフIDが渡された場合は、レポートのデフォルトグラフのIDが返されます。一致するグラフが見つからない場合は、nullが返されます。
applySeriesSelection(series, chartId)（シリーズ選択の適用）
リターン
なし
説明
渡されたグラフIDにシリーズ選択を適用します。シリーズ選択は、グラフ上のシリーズフィールドを他のフィールドで置き換えるか、複数のシリーズフィールドをグラフに追加し、同時に描画するかのいずれかの方法で機能します。
この関数をレポートに適用するには、グラフレベルで「シリーズ選択の表示」オプションを有効にしなくてはいけません。以下の画像を参照してください。
（以下に示すように）シリーズ選択のスタイルオプションが「上パネル」、または「左パネル」に設定されている場合は、グラフのシリーズ選択は単一の選択タイプになります。これはつまり、ひとつのシリーズ飲み選択できることを意味します。このオプションを有効にした場合は、グラフは渡された配列の最初の値のみを取得します。
プロパティが「シリーズ選択の表示」に設定された場合は、グラフのタイプは、すべての値を使用するかどうかを決定します。
グラフ、またはレポートに存在しないフィールドIDがapplySeriesSelection関数に渡された場合は、そのフィールドIDは無視され、グラフはデフォルトシリーズ値に戻されます。
パラメーター
Series - Array[Number]
レポートに適用するフィールドの配列です。
hartId - String, Number
シリーズ選択に適用するグラフIDです。グラフIDが渡されない場合は、デフォルトグラフのIDが使用されます。
例
複数のフィールドをデフォルトグラフのシリーズ選択に追加します。
フィールドIDを使用して適用します。
フィールド名を使用して適用します。
sortAscending(fieldId)（昇順に並べかえ）
リターン
なし
説明
渡されたフィールドに昇順の並べかえを適用します。渡されたフィー都度IDが、レポート上のフィールドと一致しない場合は、並べかえは適用されません。
パラメーター
filedId: Number, String
並べかえるフィールドのフィールドID、または名前です。
sortDescending(fieldId)（降順に並べかえ）
リターン
なし
説明
渡されたフィールドに降順の並べかえを適用します。渡されたフィー都度IDが、レポート上のフィールドと一致しない場合は、並べかえは適用されません。
パラメーター
filedId: Number, String
並べかえるフィールドのフィールドID、または名前です。
runReport()（レポートの実行）
リターン
なし
説明
レポートの現在の状態を適用してレポートを実行します。runReport関数が短期間に複数回トリガーされる場合、レポート実行リクエストは、一度だけサーバに送信されます。
例
レポートの実行が終了した後、5秒ごとにレポートを再実行します。
registerOutputType(outputOptions, callback)（出力タイプの登録）
リターン
Number
説明
レポートにレポート出力タイプを登録することで、開発者がレポートから追加情報を得ることができます。登録した出力の一意の識別子を返しますが、これはoutputTypeリクエストが不要になったときに、レポートからこれを削除するために使用されます。
出力タイプのコールバック関数は、レポートがサーバからそのデータを返すたびに呼び出されますが、reportCompleteイベントがトリガーされる前に呼び出されます。
Yellowfin 9.2以降では、レポートデータセットを出力タイプとしてリクエストできます。
データセット
レポートのデータセットを返します。
オプション
この出力タイプに定義できるオプションはありません。
コールバックパラメーター
データセット
二次元配列です。配列の各項目は、次の値を含むオブジェクトになります。
rawValue：データベースから取得する場合の値です。
formattedValue：参照コード、またはフォーマッターが適用された後の値です。
htmlFormattedValue：HTMLページに挿入する準備ができた値です。
デフォルトで参照コードとして書式設定されているフィールド「Gender」の場合、データオブジェクトは次のようになります。
formattedValueとhtmlFormattedValueの違い
多くの場合、formattedValueとhtmlFormattedValueに違いは見られません。いくつかのフォーマッターは、HTMLタグを出力するために、そこに違いが現れます。例えば次のレポートでは、「Gender As Link」フィールドは、「URLへリンク」フォーマッターを使用して書式設定されており、テーブルに挿入されるアンカータグを生成します。
上記のロウ（行）のデータセットは、次のようになります。
htmlFormattedValueは実際のアンカータグを含み、formattedValueがユーザーに表示されます。
パラメーター
outputOptions: String, Object
登録する出力タイプについての情報を含むObject、またはStringです。Stringが渡される場合、特定の出力タイプにデフォルトオプションが使用されます。
callback: Function
出力タイプが完了したときに呼び出される関数です。このコールバックに渡されたパラメーターオブジェクトは、登録された出力タイプに応じて異なります。
例
データセットの出力タイプを登録し、データセットを出力します。
または、outputInformationオブジェクトを使用してデータセットを登録しても、同様の結果を達成できます。
removeOutputType(outputKey)（出力タイプの削除）
リターン
なし
説明
渡されたoutputKeyに関連するレポート出力タイプとコールバックの登録を解除します。これにより、Yellowfinサーバは、その出力リクエストに情報を返さなくなります。
パラメーター
outputKey: Number
登録を解除するoutputKeyです。
例
データセットタイプを登録し、これが完了したあとにレポートから出力タイプを削除します。
reset()（リセット）
リターン
なし
説明
レポートからすべてのレポートインタラクション（ドリル、並べかえ、タイムスライダーなど）をクリアし、レポートを実行します。これはレポートに関連するフィルターをリセットしません。これは、フィルターオブジェクトを複数のレポートにリンクさせることが可能なため、このレポートに特化したフィルターをリセットすることで、他のレポートに意図せず影響を与えるからです。レポートを完全にリセットする場合は、filter.resetFiltersToDefault()、またはfilters.clear()を合わせて使用します。
例
レポートインタラクションをリセットするが、フィルターはリセットしないリセットボタンを追加します。
isDrillAnywhere()（ドリルエニウェア）
リターン
Boolean
説明
レポートを「ドリルエニウェア」タイプのレポートとして定義するかどうかを返します。これは、レポート作成中に「分析スタイル」オプションを「ドリルエニウェア」に設定した場合にtrueを返します。
isDrillDown()（ドリルダウン）
リターン
Boolean
説明
レポートを「ドリルダウン」タイプのレポートとして定義するかどうかを返します。これは、レポート作成中に「分析スタイル」オプションを「ドリルダウン」に設定した場合にtrueを返します。
isDrillDownApplied()（ドリルダウンの適用）
リターン
Boolean
説明
レポートがドリルダウンされたかどうかを返します。これは、レポート上のいずれかのドリルダウンフィールドがドリルダウンされた場合にtrueを返します。
例
isDrillAnywhereApplied()（ドリルエニウェアの適用）
リターン
Boolean
説明
レポートにドリルエニウェアが適用されたかどうかを返します。
drill(fieldId, value, toField)（ドリル）
リターン
なし
説明
渡された値と合わせて、渡されたフィールドIDにドリルを適用します。
「ドリルエニウェア」レポートの場合、toFieldは、fieldIdフィールドを置き換えるフィールドを決定するために使用されます。「ドリルダウン」レポートの場合は、ビューレベルで既に定義されているドリルの内部階層があるので、toFieldは無視されます。
ドリルが成功すると、「ドリルダウン」、または「ドリルエニウェア」イベントがトリガーされます。
パラメーター
filedId: Number, String
ドリル先のフィールドです。
value: Number, String
ドリル値として適用する値です。
toField: Number
ドリル先のフィールドのビューフィールドテンプレートIDです。ドリルエニウェアレポートでのみ使用されます。
例
フィールドIDを使用して、「Agency Type」フィールドの「Agency」にドリルダウンにします。
または、フィールド名をフィールドIDパラメーターに使用することができます。
drillUpLevels(fieldId, levels)（ドリルアップレベル）
リターン
なし
説明
渡されたフィールドIDのドリルアップレベルです。ドリルしているフィールドが階層の最上部である場合、特にアクションは実行されません。
例えば、「ツアー地域」＞「ツアー国」＞ツアー名」フィールドを使用します。ツアー名までドリルダウンして、report.drillUpLevels(fieldId, 1)を呼び出す場合、ツアー国レベルに戻ります。
report.drillUpLevels(fieldId, 5)を呼び出す場合は、階層の合計よりも大きいので、これはフィールド上のドリルをリセットし、ツアー地域レベルまで戻ります。
パラメーター
field: Number, String
ドリルアップする先のフィールドです。
levels: Number
ドリルアップする階層の数です。
例
field 1の単一レベルをドリルアップします。
drillUpOneLevel()（1レベル上にドリルアップ）
リターン
なし
説明
レポート内でドリル可能なすべてのフィールドを1レベル上にドリルアップします。
例
レポート全体をひとつ上のレベルにドリルアップするドリルボタンを作成します。
drillReset(fieldId)（ドリルのリセット）
リターン
なし
説明
渡されたフィールドID上のドリルをリセットします。フィールドIDが渡されない場合は、レポート全体のドリルがリセットされます。
パラメーター
fieldId: Number, String
ドリルをリセットするフィールドです。
例
レポート全体のドリルをリセットします。
名前を使用して「Agency Region」フィールドのドリルをリセットします。
フィールドIDを使用して「Agency Region」フィールドのドリルをリセットします。
timeSlider(from, to, chartId)（日付スライダー）
リターン
なし
説明
渡されたグラフの日付スライダーにfromとtoを適用します。グラフIDが渡されない場合、レポートのデフォルトグラフが使用されます。これはレポートを実行して、適用された日付スライダー値を使用してグラフを再生成します。
パラメーター
from: Number
日付スライダーの下限値をミリ秒単位で指定します。
to: Number
日付スライダーの上限値をミリ秒単位で指定します。
chartId: Number, String
日付スライダー値を適用するグラフIDです。
例
August 2014（2014年8月）からNovember 2014（2014年11月）のデータを表示するように日付スライダーを設定します。
unitSelection(unit, chartId)（単位選択）
リターン
なし
説明
渡されたグラフに時間単位選択を適用します。グラフIDが渡されない場合、代わりにレポートのデフォルトグラフが使用されます。オプションを機能させるには、グラフの単位選択表示を有効にしなくてはいけません。
パラメーター
unit: String
グラフに適用する時間粒度です。選択肢は、次の通りです。
ミリ秒
秒
分
時間
日
週
月
年
例
レポートのデフォルトグラフに「MONTH（月）」を適用します。
convertDrillDownToArray()&convertDrillAnywhereToArray()（ドリルダウンを配列に変換およびドリルエニウェアを配列に変換）
リターン
Array[Object]
説明
レポートに現在適用されるドリルの状態の配列を返します。
配列内の各オブジェクトは、次の情報を含みます。
fieldId：ドリルした階層を示す番号です。
reportId：現在のレポートのIDです。
reportKey：レポートに固有のキーです。
reportUUID：レポートの公開UUIDです。
templateId：現在いるフィールドのビューレベルテンプレートIDです。
value：ドリルのこのステージに適用される値です。
配列を繰り返し処理する場合、フィィーリド上のすべてのドリルオブジェクトが順番にドリルされます。つまり、ドリルダウン可能なフィールドが2つあり、両方ともドリルされている場合、配列内の最初のN個の値は、最初のフィールドに関連づけられます。ここでNは、そのフィールドがドリルされた距離を表します。配列の残りの部分は、二番目のフィールドのドリル値で構成されます。
次のドリル階層を持つレポートの場合
代理店地域＞代理店国
ツアー地域＞ツアー国＞ツアー名
代理店地域は、1レベルドリルダウンできます。ツアー地域は2レベルドリルダウンできます。両方とも完全にドリルダウンされている場合、配列には3つの入力が含まれます。最初は「代理店地域」に関連し、二番目は「ツアー地域」に関連し、三番目はツアー地域の子フィールドである「ツアー国」に関連します。
イベントのリファレンス
すべてのレポートイベントは、次のプロパティを含むオブジェクト使用してトリガーされます。
eventData：特定のイベントのデータです。これは、トリガーされるイベントに応じて異なります。各イベントを確認して、イベントデータオブジェクトに何が含まれているのかを確認します。
matadeta：次を含む、イベントがトリガーされるレポートについて基礎的なデータを含むオブジェクトです。
reportId：内部レポートIDです。
reportUUID：レポートのUUIDです。
reportKey：このインスタンスのレポートの固有の識別子です。
eventName：実際にトリガーされるイベントの名前です。
seriesSelection（シリーズ選択）
説明
シリーズ選択がレポートに適用されると呼び出されます。
パラメーター
イベントデータ
series：(Array[Number])このシリーズ選択イベントに適用されるフィールドIDの配列です。これには、レポート上に実際存在するフィールドのみを含める必要があります。
chartId：シリーズ選択を適用するグラフIDです。
sort（並べかえ）
説明
レポートが並べかえれると呼び出されます。
パラメーター
イベントデータ
fieldId：並べかえが適用されたフィールドです。
sortDirection：フィールドを並べかえる方向です。「ASCENDING（昇順）」、または「DESCENDING（降順）」になります。
reportStart（レポート開始）
説明
レポートが新しいデータセットを取得するために、サーバにリクエストを送信することで呼び出されます。
パラメーター
イベントデータはありません。
reportComplete（レポートの完了）
説明
レポートがサーバから返され、registerOutputType関数に登録されているすべてのコールバックが解決された後に呼び出されます。
パラメーター
イベントデータは、レポート実行からの複数の出力結果を含みます。
イベントデータの例
drilldown（ドリルダウン）
説明
レポート上の任意のフィールドにドリルダウンが適用されるたびに呼び出されます。
パラメーター
イベントデータは次を含みます。
fieldId：ドリル先のフィールドです。
added：(Array)適用された値についての情報を含むオブジェクトの配列です。
drillState：(Array)レポート上のドリル状態全体を含む配列です。convertDrillDownToArrayを参照してください。
drillanywhere
説明
レポート上の任意のフィールドに「ドリルエニウェア」が適用されるたびに呼び出されます。
パラメーター
イベントデータは次を含みます。
added：(Array)このドリルイベントに追加されたドリルオブジェクトの配列です。
drillState：(Array)レポート全体のドリルの状態です。convertDrillAnywhereToArrayを参照してください。
drillUp（ドリルアップ）
説明
レポートがドリルアップされるたびに呼び出されます。これは、「ドリルエニウェア」、および「ドリルダウン」両方のレポートをトリガーします。
パラメーター
removed：(Array)このドリルイベントから削除されるドリルオブジェクトの配列です。
drillState：(Array)レポート全体のドリルの状態です。convertDrillAnywhereToArray、またはconvertDrillDownToArrayを参照してください。
resetDrill（ドリルのリセット）
説明
フィールドのドリルの状態がリセットされるか、レポート全体のドリルの状態がリセットされると呼び出されます。これは、ドリルエニウェア、およびドリルダウン両方のレポートをトリガーします。
パラメーター
removed：(Array)ドリルイベント内から削除されるドリルオブジェクトの配列です。
drillState：(Array)レポート全体のドリルの状態です。convertDrillAnywhereToArray