タイル拡張機能の作成

Looker 24.0 以降では、ダッシュボードのタイル内で実行するように拡張機能を開発できます。タイルまたはビジュアリゼーションとして実行できる拡張機能は、ダッシュボードの編集モード中に追加するか、Explore からビジュアリゼーションとしてダッシュボードに保存できます。拡張機能は、LookML ダッシュボードでタイルとして構成することもできます。

ダッシュボード タイルとして使用できる拡張機能の例を次に示します。

タイル拡張機能で 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 - 拡張機能に可視化データを提供します。データは、ホスティング ダッシュボードでの操作に基づいて自動的に更新されます。このデータは、カスタム ビジュアリゼーションに提供されるデータに似ています。

リアクティブ拡張機能の作成

拡張機能が実行される iframe は、親の Looker ホスト ウィンドウのサイズが変更されると自動的にサイズ変更されます。これは iframe コンテンツ ウィンドウに自動的に反映されます。iframe コンポーネントにはパディングとマージンがないため、Looker アプリケーションと見た目が一致するように、独自のパディングとマージンを拡張機能で指定する必要があります。スタンドアロン拡張機能の場合、拡張機能の高さは拡張機能によって制御されます。ダッシュボード タイルまたは Explore ビジュアリゼーションで実行される広告表示オプションの場合、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} />
  }

Tile SDK の関数とプロパティ

タイル SDK は、タイル拡張機能がホスティング ダッシュボードを操作できるようにする関数を提供します。

使用可能な関数とプロパティは次の表のとおりです。

関数またはプロパティ 説明
tileHostData（プロパティ） タイル拡張機能に固有のホストデータ。詳細については、Tile SDK データのセクションをご覧ください。
addError 呼び出されると、ダッシュボードまたは Explore のビジュアリゼーションの下にエラー メッセージが表示されます。
clearError ダッシュボードまたは Explore が呼び出されると、可視化の下に表示されているエラー メッセージは非表示になります。
openDrillMenu ビジュアリゼーション拡張機能の場合、この呼び出しによりドリルダウン メニューが開きます。拡張機能がタイル表示オプションのビジュアリゼーションでない場合、この呼び出しは無視されます。
runDashboard 現在のダッシュボードを実行します。この呼び出しは、Explore で実行されているタイル ビジュアリゼーション拡張機能では無視されます。
stopDashboard 実行中のダッシュボードを停止します。この呼び出しは、Explore で実行されているタイル ビジュアリゼーション拡張機能では無視されます。
updateFilters 現在のダッシュボードまたは Explore のフィルタを更新します。
openScheduleDialog スケジュール ダイアログが開きます。この呼び出しは、データ探索で実行されている場合は無視されます。
toggleCrossFilter クロス フィルタを切り替えます。この呼び出しは、データ探索で実行されている場合は無視されます。

Tile SDK データ

使用可能なタイル SDK データ プロパティは次の表のとおりです。

プロパティ 説明
isExploring true の場合、タイルが Explore 内のビジュアリゼーションとして構成されていることを示します。
dashboardId レンダリングされているタイルのダッシュボード ID。タイルが Explore として設定されている場合、このプロパティは入力されません。
elementId レンダリングされているタイルの要素 ID。タイルが探索として設定されている場合、このプロパティは入力されません。
queryId レンダリングされているタイルのクエリ ID（ビジュアリゼーションに関連付けられている場合）。タイルが Explore として設定されている場合、このプロパティは入力されません。

queryId は、Looker Explore にビジュアリゼーションを組み込むときに作成されるクエリの ID です。ダッシュボードに適用するフィルタやクロス フィルタは含まれていません。QueryResponse に表示されるデータを反映するには、フィルタとクロス フィルタを適用し、新しいクエリを生成する必要があります。その結果、queryId よりも有用なプロパティが存在する場合があります。フィルタが適用されたクエリ オブジェクトについては、filteredQuery をご覧ください。
querySlug レンダリングされているタイルのクエリ スラグ（ビジュアリゼーションに関連付けられている場合）。タイルが探索として設定されている場合、このプロパティは入力されません。

querySlug は、Looker Explore でビジュアリゼーションをビルドするときに作成されるクエリのスラグです。ダッシュボードに適用されているフィルタやクロス フィルタは含まれません。QueryResponse に表示されるデータを反映するには、フィルタとクロス フィルタを適用し、新しいクエリを生成する必要があります。その結果、querySlug よりも有用なプロパティが存在する場合があります。フィルタが適用されたクエリ オブジェクトについては、filteredQuery をご覧ください。
dashboardFilters ダッシュボードに適用されているフィルタ。タイルが探索として設定されている場合、このプロパティは入力されません。
dashboardRunState ダッシュボードが実行されているかどうかを示します。タイルが Explore として構成されている場合、状態は UNKNOWN になります。

ダッシュボードのパフォーマンス上の理由から、runstate が実行中として表示されないことがあります。これは通常、拡張機能が関連付けられているタイルを含め、クエリに関連付けられている他のタイルがない場合に発生します。拡張機能でダッシュボードが実行されたことを確実に把握する必要がある場合は、lastRunStartTime の差異を検出するのが信頼できる方法です。
isDashboardEditing true の場合、ダッシュボードが編集中です。タイルが Explore として設定されている場合、このプロパティは入力されません。
isDashboardCrossFilteringEnabled true の場合、ダッシュボードでクロス フィルタリングが有効になります。タイルが探索として設定されている場合、このプロパティは入力されません。
filteredQuery 基になるダッシュボード要素に関連付けられているクエリ ID と一致するクエリ オブジェクト。ダッシュボード レベルで行われたダッシュボード フィルタとタイムゾーンの変更が適用されます。
lastRunSourceElementId 前回のダッシュボード実行をトリガーしたタイル拡張機能要素の ID。ダッシュボードが実行ボタンまたは自動更新ダッシュボードによってトリガーされた場合、または、埋め込み SDK を使用して実行がトリガーされた場合、ID は定義されません。タイルが探索として設定されている場合、このプロパティは入力されません。

lastRunSourceElementId は、現在の拡張機能インスタンスの要素 ID と同じにすることができます。たとえば、拡張機能がダッシュボードの実行をトリガーすると、ダッシュボードの実行の開始と終了が通知されます。
lastRunStartTime ダッシュボードの最終実行開始時間を示します。タイルが Explore として設定されている場合、このプロパティは入力されません。

なお、レポートされる開始時間と終了時間は、パフォーマンス指標の取得には使用しないでください。
lastRunEndTime ダッシュボードの最終実行終了時刻を示します。タイルが Explore として設定されている場合、このプロパティは入力されません。タイルが実行中の場合、このプロパティは入力されません。

なお、レポートされる開始時間と終了時間は、パフォーマンス指標の取得には使用しないでください。
lastRunSuccess 最後のダッシュボードの実行が成功したかどうかを示します。タイルが探索として設定されている場合、このプロパティは入力されません。タイルが実行中の場合、このプロパティは入力されません。

Visualization SDK の関数とプロパティ

利用可能な可視化 SDK の関数とプロパティは次の表のとおりです。

関数またはプロパティ 説明
visualizationData（プロパティ） 可視化（visConfig データと queryResponse データの組み合わせ）。
visConfig（プロパティ） 可視化構成データ：

  • 測定の設定
  • ディメンションの設定
  • 表計算
  • ピボットの構成
  • 可視化の構成

データ探索ツールのビジュアリゼーションの外観をカスタマイズするために使用します。
queryResponse（プロパティ） クエリからのレスポンス データ
configureVisualization 拡張機能の可視化のデフォルト設定を設定します。構成は Explore のビジュアリゼーション エディタ内にレンダリングされます。これは 1 回だけ呼び出します。
setVisConfig 可視化の構成を更新します。
updateRowLimit クエリの行数上限を更新します。

Visualization 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 フィールドのディメンション情報と、ディメンションのように動作する表計算の連結配列。