タイル拡張機能の作成

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 スケジュール ダイアログが開きます。この呼び出しは、Explore で実行されている場合は無視されます。
toggleCrossFilter クロスフィルタを切り替えます。この呼び出しは、Explore で実行されている場合は無視されます。

Tile 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 になります。

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

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

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

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

可視化 SDK の関数とプロパティ

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

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

  • メジャー構成
  • ディメンション構成
  • 表計算
  • ピボット構成
  • 可視化構成

Explore の可視化の見た目をカスタマイズするために使用します。
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 フィールドのディメンション情報と、ディメンションのように動作する表計算の連結配列。