タイル拡張の作成

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

リアクティブ拡張機能の構築

親の 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（プロパティ） 可視化構成データ：

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

これらは、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 フィールドのディメンション情報と、ディメンションのように動作するテーブル計算の連結された配列。