タイル拡張機能の作成

Looker 24.0 以降では、ダッシュボードのタイルで実行される拡張機能を開発できます。タイルまたは可視化として実行できる拡張機能は、ダッシュボードの編集モード中に追加するか、Explore から可視化としてダッシュボードに保存できます。拡張機能は、LookML ダッシュボードのタイルとして構成することもできます。

ダッシュボード タイルとして使用できる拡張機能の例は次のとおりです。

• タイル可視化拡張機能では、拡張フレームワークを使用してカスタム可視化を作成する方法が示されます。
• タイル SDK 拡張機能では、タイル拡張機能に固有の使用可能な API メソッドが表示されます。

注意: 埋め込み Looker コンテンツ（レポート、ダッシュボード、Look、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} />
  }

タイル 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 になります。 ダッシュボードのパフォーマンス上の理由から、実行状態が実行中と表示されないことがあります。これは通常、拡張機能が関連付けられているタイルを含め、クエリに関連付けられている他のタイルがない場合に発生します。拡張機能でダッシュボードが実行されたことを確実に知る必要がある場合は、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	フィールドのディメンション情報と、ディメンションのように動作する表計算の連結配列。

Embed SDK の使用

次の理由から、タイル拡張機能で Embed SDK を使用することはおすすめしません。

• 拡張機能がタイルとして表示されるダッシュボードを拡張機能がレンダリングする可能性があります。拡張機能フレームワークではこれを検出できないため、ブラウザがクラッシュする可能性があります。
• タイル拡張機能内の埋め込みコンテンツの PDF レンダリングが機能しない。