Looker 24.0 以降では、拡張機能を開発してダッシュボードのタイルで実行できるようになりました。タイルまたは可視化としての実行をサポートする拡張機能は、ダッシュボードが編集モードの間に追加するか、Explore から可視化としてダッシュボードに保存できます。拡張機能は、LookML ダッシュボードでタイルとして構成することもできます。
ダッシュボード タイルとして使用できる拡張機能の例は、次のとおりです。
- タイル可視化拡張機能は、拡張フレームワークを使用してカスタム可視化を作成する方法を示しています。
- タイル SDK 拡張機能には、タイル拡張機能に固有の API メソッドが表示されます。
タイル拡張を使用する Looker Extension SDK の使用
タイル拡張機能でダッシュボードにタイルとして拡張機能を読み込むには、LookML のプロジェクト マニフェスト ファイルで mount_points
パラメータを定義する必要があります。タイル拡張に関連する mount_points
には次の 2 種類があります。
mount_points: {
dashboard_vis: yes
dashboard_tile: yes
standalone: yes
}
dashboard_vis
- 有効にすると、拡張機能は Explore の可視化オプションに表示されます。表示オプションは可視化として選択し、ダッシュボード タイルとして保存できます。ダッシュボードが実行されると、ダッシュボードはタイルに関連付けられたクエリを実行し、そのデータを拡張機能で使用できるようにします。これはカスタムの可視化の仕組みに似ています。カスタムの可視化と、dashboard_vis
が有効になっているダッシュボード タイルで実行される拡張機能の主な違いは、拡張機能は Looker API 呼び出しを行えることです。dashboard_tile
— 有効にすると、ユーザーがダッシュボードを編集しているときに、[追加]ボタンをクリックした後、拡張機能パネルに拡張機能が表示され、拡張機能オプションが選択されます。このタイプのクエリは、タイルクエリが拡張機能にデータを自動的に提供するのではなく、独自のデータを取得します。
追加のマウント ポイント standalone
を使用すると、Looker メインメニューの [アプリケーション] セクションにこの拡張機能が表示されます。拡張機能には複数のマウント ポイントを定義できます。実行時に、拡張機能のマウント方法が通知され、それに応じて動作が調整されます。たとえば、standalone
拡張機能では自身の高さを設定する必要がありますが、タイル拡張では設定する必要はありません。
タイル拡張の追加 API
タイル拡張には、実行時に追加の API とデータが提供されます。これらは拡張コンテキストから取得されます。
const {
tileSDK,
tileHostData,
visualizationData,
visualizationSDK,
} = useContext(ExtensionContext40)
tileSDK
- 拡張機能が Looker ダッシュボード ホストとやり取りできるように、タイル固有の関数を提供します。たとえば、拡張機能によるエラー メッセージの表示と消去を許可します。tileHostData
- 拡張子にタイルデータを提供します。データは、ホスティング ダッシュボードの操作に基づいて自動的に更新されます。たとえば、isDashboardEditing
インジケーターなどです。visualizationSDK
- 拡張機能が Looker ダッシュボード ホストと対話できるようにする可視化固有の機能を提供します。たとえば、updateRowLimit
関数です。visualizationData
- 拡張子に可視化データを提供します。データは、ホスティング ダッシュボードの操作に基づいて自動的に更新されます。このデータは、カスタム ビジュアリゼーションに提供されるデータと類似しています。
リアクティブ拡張機能の構築
親の Looker ホスト ウィンドウのサイズを変更すると、拡張機能が実行される iframe のサイズが自動的に変更されます。これは iframe のコンテンツ ウィンドウに自動的に反映されます。iframe コンポーネントにはパディングやマージンがないので、Looker アプリケーションとの整合性が保たれるように、独自のパディングとマージンを指定するように拡張機能で決めます。スタンドアロンの広告表示オプションの場合は、広告表示オプションの高さをコントロールできます。ダッシュボード タイルまたはデータ探索の可視化で実行される拡張機能の場合、iframe コンテンツ ウィンドウは iframe で使用できる高さに自動的に設定されます。
レンダリングに関する考慮事項
タイル拡張は、ダッシュボードが PDF または画像としてダウンロードされるとレンダリングされることに注意してください。レンダラは、レンダリングの完了時にタイルが通知することを想定しています。そのようにしない場合、レンダラは応答しなくなります。タイルがレンダリングされたことをレンダラに通知する方法の例を次に示します。
const { extensionSDK } = useContext(ExtensionContext40)
useEffect(() => {
extensionSDK.rendered()
}, [])
レンダリング時にアニメーションも無効にする必要があります。レンダリング時にアニメーション構成が無効になっている例を次に示します。
const { lookerHostData} = useContext(ExtensionContext40)
const isRendering = lookerHostData?.isRendering
const config = isRendering
? {
...visConfig,
valueCountUp: false,
waveAnimateTime: 0,
waveRiseTime: 0,
waveAnimate: false,
waveRise: false,
}
: visConfig
if (mountPoint === MountPoint.dashboardVisualization) {
return <VisualizationTile config={config} />
}
タイル SDK の関数とプロパティ
タイル SDK には、タイル拡張機能がホスティング ダッシュボードと対話できる関数が用意されています。
利用可能な関数とプロパティを次の表に示します。
関数またはプロパティ | 説明 |
---|---|
tileHostData (プロパティ) |
タイル拡張子に固有のデータをホストする。詳細については、タイル SDK データのセクションをご覧ください。 |
addError |
ダッシュボードまたは Explore が呼び出されると、可視化の下にエラー メッセージが表示されます。 |
clearError |
ダッシュボードまたは Explore が呼び出されると、可視化の下にあるエラー メッセージが非表示になります。 |
openDrillMenu |
可視化拡張機能の場合、この呼び出しではドリルメニューが開きます。拡張子がタイル表示でない場合、この呼び出しは無視されます。 |
runDashboard |
現在のダッシュボードを実行します。この呼び出しは、Explore で実行されているタイル可視化拡張機能によって無視されます。 |
stopDashboard |
実行中のダッシュボードを停止します。 この呼び出しは、Explore で実行されているタイル可視化拡張機能によって無視されます。 |
updateFilters |
現在のダッシュボードまたはデータ探索のフィルタを更新します。 |
openScheduleDialog |
スケジュール ダイアログが開きます。Explore で実行している場合、この呼び出しは無視されます。 |
toggleCrossFilter |
クロスフィルタを切り替えます。Explore で実行している場合、この呼び出しは無視されます。 |
タイル SDK データ
利用可能なタイル SDK のデータ プロパティを次の表に示します。
プロパティ | 説明 |
---|---|
isExploring |
true の場合、タイルが Explore 内の可視化として構成されていることを示します。 |
dashboardId |
レンダリングされているタイルのダッシュボード ID。タイルが Explore として構成されている場合、このプロパティは設定されません。 |
elementId |
レンダリングされているタイルの要素 ID。タイルが Explore として構成されている場合、このプロパティは設定されません。 |
queryId |
可視化に関連付けられている、レンダリングされるタイルのクエリ ID。タイルが Explore として構成されている場合、このプロパティは設定されません。queryId は、Looker Explore に可視化が組み込まれている場合に作成されるクエリの ID です。ダッシュボードに適用するフィルタやクロス フィルタリングは含まれていません。QueryResponse に示されたデータを反映するには、フィルタとクロスフィルタを適用して、新しいクエリを生成する必要があります。このため、queryId よりも便利なプロパティが存在する場合があります。フィルタが適用されたクエリ オブジェクトについては、filteredQuery をご覧ください。 |
querySlug |
ビジュアリゼーションに関連付けられている場合は、レンダリングされるタイルのクエリスラッグ。タイルが Explore として構成されている場合、このプロパティは設定されません。querySlug は、Looker Explore に可視化が組み込まれている場合に作成されるクエリのスラッグです。ダッシュボードに適用されているフィルタやクロス フィルタリングは含まれていません。QueryResponse に示されたデータを反映するには、フィルタとクロスフィルタを適用して、新しいクエリを生成する必要があります。このため、querySlug よりも便利なプロパティが存在する場合があります。フィルタが適用されたクエリ オブジェクトについては、filteredQuery をご覧ください。 |
dashboardFilters |
ダッシュボードに適用されているフィルタ。タイルが Explore として構成されている場合、このプロパティは設定されません。 |
dashboardRunState |
ダッシュボードが実行中かどうかを示します。タイルが Explore として構成されている場合、状態は UNKNOWN になります。ダッシュボードのパフォーマンス上の理由から、実行状態が実行中と表示されない場合があります。通常は、拡張機能が関連付けられているタイルを含む、他のタイルがクエリに関連付けられていない場合に発生します。ダッシュボードが実行されたことを確認する拡張機能が必要な場合、lastRunStartTime の違いを検出するための確実な方法です。 |
isDashboardEditing |
true の場合、ダッシュボードが編集されています。タイルが Explore として構成されている場合、このプロパティは設定されません。 |
isDashboardCrossFilteringEnabled |
true の場合、ダッシュボードでクロス フィルタリングが有効になっています。タイルが Explore として構成されている場合、このプロパティは設定されません。 |
filteredQuery |
ダッシュボード レベルで行われたダッシュボード フィルタやタイムゾーンの変更を適用する、基盤となるダッシュボード要素に関連付けられているクエリ ID に一致するクエリ オブジェクト。 |
lastRunSourceElementId |
最後のダッシュボードの実行をトリガーしたタイル拡張要素の ID。ダッシュボードが実行ボタンまたは自動更新ダッシュボードによってトリガーされた場合、または、埋め込み SDK を使用して実行がトリガーされた場合、ID は定義されません。タイルが Explore として構成されている場合、このプロパティは設定されません。lastRunSourceElementId は、現在の拡張インスタンスの要素 ID と同じにできます。たとえば、拡張機能によってダッシュボードの実行がトリガーされた場合、ダッシュボードの実行の開始と終了時に通知されます。 |
lastRunStartTime |
最後のダッシュボードの実行開始時間を示します。タイルが Explore として構成されている場合、このプロパティは設定されません。レポートされた開始時間と終了時間は、パフォーマンス指標のキャプチャには使用されません。 |
lastRunEndTime |
ダッシュボードの最後の実行時刻を示します。タイルが Explore として構成されている場合、このプロパティは設定されません。タイルが動作している場合、このプロパティには値は入力されません。レポートされた開始時間と終了時間は、パフォーマンス指標のキャプチャには使用されません。 |
lastRunSuccess |
最後のダッシュボード実行が成功したかどうかを示します。タイルが Explore として構成されている場合、このプロパティは設定されません。タイルが動作している場合、このプロパティには値は入力されません。 |
可視化 SDK の関数とプロパティ
次の表に、利用可能な可視化 SDK の関数とプロパティを示します。
関数またはプロパティ | 説明 |
---|---|
visualizationData (プロパティ) |
可視化(visConfig データと queryResponse データの組み合わせ)。 |
visConfig (プロパティ) |
可視化構成データ:
|
queryResponse (プロパティ) |
クエリからのレスポンス データ |
configureVisualization |
拡張機能の可視化のデフォルト構成を設定します。構成は Explore 可視化エディタ内でレンダリングされます。これは 1 回だけ呼び出す必要があります。 |
setVisConfig |
可視化構成を更新します。 |
updateRowLimit |
クエリの行数の上限を更新します。 |
可視化 SDK のデータ
可視化 SDK は次の要素で構成されます。
- 可視化の構成データ
- レスポンス データのクエリ
可視化の構成データ
プロパティ | 説明 |
---|---|
queryFieldMeasures |
測定情報 |
queryFieldDimensions |
ディメンションの情報 |
queryFieldTableCalculations |
表計算情報 |
queryFieldPivots |
ピボット情報 |
visConfig |
ビジュアル構成データ。これをデフォルトの構成と統合して、拡張機能によってレンダリングされる可視化に適用する必要があります。 |
export interface VisualizationConfig {
queryFieldMeasures: Measure[]
queryFieldDimensions: Dimension[]
queryFieldTableCalculations: TableCalculation[]
queryFieldPivots: PivotConfig[]
visConfig: RawVisConfig
}
レスポンス データのクエリ
プロパティ | 説明 |
---|---|
data |
行データの配列 |
fieldMeasures |
フィールド測定情報。 |
fieldDimensions |
フィールドのディメンション情報。 |
fieldTableCalculations |
フィールド テーブルの計算情報。 |
fieldPivots |
フィールド ピボット情報。 |
fieldMeasureLike |
フィールド測定値情報と、メジャーのように動作するテーブル計算の連結された配列。 |
fieldDimensionLike |
フィールドのディメンション情報と、ディメンションのように動作するテーブル計算の連結された配列。 |