Embedded SDK の概要

注: このページは、Embed SDK 2.0.0 のリファレンスです。2.0.0 API には Embed SDK 1.8.x との下位互換性がありますが、一部の機能の基盤となる実装が変更されています。SDK 1.8.x では、多数のクラスがエクスポートされました。SDK 2.0.0 では、これらのクラスが非推奨としてマークされたインターフェースに置き換えられています（代替インターフェースが特定されています）。アプリケーションでは、接頭辞「I」が付いたインターフェースを使用することをおすすめします（接頭辞が付いたインターフェースは、接頭辞が付いていないインターフェースと同じです）。SDK 2.0.0 にアップグレードされたアプリケーションは、以前と同じように動作します。API の改善を活用するには、リファクタリングが必要になります。Embed SDK 2.0.0 には、次の大きな変更が含まれています。

• ダッシュボード、Explore、Look の間を移動する際に、iframe を再作成する必要がなくなりました。代わりに、loadDashboard、loadLook、loadExplore、loadUrl メソッドを使用して、Looker iframe 内を移動できます。
• connect は、ダッシュボード、Look、Explore にのみ関連する接続ではなく、統合された接続を返すようになりました。統合された接続により、埋め込みアプリケーションは iframe 内を移動するユーザーを検出できます。
• Looker レポートとクエリの可視化のために、Looker の埋め込みコンテンツのサポートが追加されました。

Looker の Embed SDK は、ブラウザのウェブベースのウェブ アプリケーションのコードに追加して、ウェブアプリの埋め込みダッシュボード、Look、レポート、Explore を管理する関数のライブラリです。

注: Looker レポートは、Looker レポート機能が有効になっている場合に使用できます。レポートは、署名付き埋め込みメソッド、Cookie を使用しない埋め込みメソッド、またはプライベート埋め込みメソッドで埋め込むことができます。詳細については、Looker レポートを埋め込むをご覧ください。

Embed SDK では、次の方法で埋め込みを容易に行うことができます。

• HTML 要素を手動で作成しなくても、埋め込みコンテンツをカプセル化できます。
• ポイントツーポイント通信を行うことで、クロスフレーム通信を発生させない。Embedded SDK は、ホストのウェブページと埋め込み Looker コンテンツの間でクロスドメイン メッセージの受け渡しを処理し、専用のメッセージ チャネルを使用します。

Embed SDK を使用しない場合は、埋め込み JavaScript イベントのドキュメント ページで説明されている 埋め込み JavaScript イベントなどの JavaScript イベントを使用して、埋め込みの Looker コンテンツ内のイベントを呼び出したり、応答したりできます。dashboard:run:startpage:changedJavaScript イベントで Looker コンテンツを埋め込むデベロッパーは、埋め込みコンテンツを格納する HTML 要素を作成し、ウェブアプリと埋め込みコンテンツ間の通信にウィンドウ ブロードキャスト イベントを使用する必要があります。

Looker Embedded SDK は Looker API や Looker API SDK とは異なります。

• Looker Embed SDK はウェブ アプリケーションのクライアントサイド コードに存在し、Looker の埋め込みコンテキストとコンテンツを管理します。（Embedded SDK では Looker API にアクセスできません）。
• Looker API は Looker インスタンスとともにサーバー上に存在し、Looker サーバーでコマンドを実行します。
• Looker API クライアント SDK は、ブラウザ以外のアプリケーションのコードに含まれており、Looker API 機能にアクセスできるようにします。

Looker は、ブラウザがウェブ アプリケーションにイベントをディスパッチする順序を制御しません。つまり、ブラウザまたはプラットフォーム間でイベントの順序が保持されるわけではありません。さまざまなブラウザでのイベント処理を考慮して、JavaScript を適切に記述するようにしてください。

例

この例では、ID が 11 のダッシュボードが、ID embed_container の DOM 要素内に作成されます。dashboard:run:start イベントと dashboard:run:complete イベントは、埋め込みウィンドウの UI の状態を更新するために使用され、ID が run のボタンは dashboard:run メッセージをダッシュボードに送信するようにスクリプトされています。

getEmbedSDK().init('looker.example.com', '/auth')

const setupConnection = (connection) => {
  document.querySelector('#run').addEventListener('click', () => {
    connection.asDashboardConnection().run()
  })
}

try {
  connection = await getEmbedSDK()
    .createDashboardWithId('11')
    .appendTo('#embed_container')
    .on('dashboard:run:start', () => updateStatus('Running'))
    .on('dashboard:run:complete', () => updateStatus('Done'))
    .build()
    .connect()
  setupConnection(connection)
} catch (error) {
  console.error('An unexpected error occurred', error)
}

詳細な例については、埋め込み SDK デモ ドキュメント ページをご覧ください。

Looker Embed SDK の設定

Looker Embed SDK は流暢なインターフェース パターンを使用します。Embedded SDK を インストールしたら、埋め込みコンテンツを 作成して、その埋め込みコンテンツに 接続します。接続が確立されると、ホスト アプリケーションは埋め込みコンテンツとやり取りできます。

Embed SDK のインストール

Looker の Embedded SDK ライブラリは、https://www.npmjs.com/package/@looker/embed-sdk のノード パッケージ マネージャー（NPM）から入手できます。ただし、サンプルコードやデモが必要な場合は、Looker Embedded SDK リポジトリを使用してください。

Looker Embedded SDK リポジトリを使用して Looker Embedded SDK をインストールする手順は次のとおりです。

1. Node.js をインストールします（まだインストールしていない場合）。
2. /looker-open-source/embed-sdk リポジトリをダウンロードするかクローンを作成します。
3. ターミナル ウィンドウで /embed-sdk ディレクトリに移動して、次のコマンドを実行します。

npm install
npm start

埋め込みコンテンツの作成

まず、Looker サーバーのアドレスと、署名付き Looker 埋め込みログイン URL を作成する埋め込みアプリケーション サーバーのエンドポイントで SDK を初期化します。これらのサーバーは、すべての埋め込みコンテンツで使用されます。プライベート埋め込みの場合は、署名エンドポイントを省略します。

注: ブラウザ クライアントから Looker サーバーにアクセスする必要がある場合は、ポート番号を含めます。例: looker.example.com:443

getEmbedSDK().init('looker.example.com', '/auth')

次に、一連のステップを使用して埋め込みコンテンツを作成し、パラメータを定義します。これらのパラメータのいくつかはオプションですが、一部は必須です。

このプロセスは、ダッシュボード id を使用した、またはダッシュボード（署名付き埋め込みのドキュメント ページで説明されているプロセスで作成したもの）を参照する url を使用したビルダーの作成から始めます。

getEmbedSDK().createDashboardWithId('id')

または

getEmbedSDK().createDashboardWithUrl('url')

その後、ビルダーに属性を追加して設定を完了します。

[注]: create[ContentType]WithUrl 関数は、Embed SDK 2.0.0 以降の署名付き埋め込みと Cookie を使用しない埋め込みの両方で使用できます。Embed SDK 2.0.0 より前のバージョンでは、Cookie を使用しない埋め込みは create[ContentType]WithId のみをサポートしていました。

たとえば、Looker の埋め込み UI を挿入するウェブページ内の場所を指定できます。次の呼び出しでは、ID 値が dashboard の HTML 要素内に Looker 埋め込み UI を配置します。

.appendTo('#dashboard')

イベント ハンドラを追加します。

.on('dashboard:run:start',
  () => updateStatus('Running')
)
.on('dashboard:run:complete',
  () => updateStatus('Done')
)

build メソッドを呼び出して、埋め込みクライアントを作成します。

.build()

埋め込みコンテンツへの接続

クライアントが作成されたら、connect を呼び出して iframe を作成します。接続プロセスでは、実際の iframe に使用される src 属性が作成されます。src 値の生成方法は、Embed SDK の初期化方法によって異なります。

1. 署名付き: init 呼び出しの 2 番目の引数で指定されたエンドポイントが呼び出されます。エンドポイントは、署名付き埋め込みログイン URL を返すことが想定されています。
2. Cookie を使用しない: initCookieless 呼び出しの 2 番目の引数で指定されたエンドポイントまたは関数が呼び出されます。エンドポイントまたは関数は、Cookie を使用しないトークン（特に認証トークンとナビゲーション トークン）を返すことが想定されています。トークンは埋め込みログイン URL に追加されます。
3. プライベート: init 呼び出しの 2 番目の引数が指定されていない場合、埋め込み接続はプライベートになります。この場合、URL はビルダーから派生し、Looker 埋め込みに必要なパラメータが付与されます。プライベート埋め込みの場合、ユーザーがすでに Looker にログインしているか、埋め込み URL に allow_login_screen=true パラメータが含まれていることが想定されます。

connect は、埋め込み iframe の接続インターフェースに解決される Promise を返します。

  .connect()
  .then((connection) => {
    // Save the connection
  })
  .catch(console.error)

インタラクティブ機能

Embed SDK 2.0.0 は、すべての Looker コンテンツ タイプとのインタラクションをサポートする統合接続を返します。埋め込みアプリケーションは、表示されているコンテンツの種類を判別し、それに応じて操作できます。

if (connection.getPageType() === 'dashboards') {
  connection.asDashboardConnection().run()
} else (connection.getPageType() === 'looks') {
  connection.asLookConnection().run()
} else (connection.getPageType() === 'explore') {
  connection.asExploreConnection().run()
}

別のコンテンツを読み込む必要がある場合、iframe を再作成する必要はありません。代わりに、接続メソッド loadDashboard、loadLook、loadExplore、loadUrl を使用できます。loadDashboard、loadLook、loadExplore メソッドは id を受け取ります。loadUrl メソッドは埋め込み URL を受け取ります。このメソッドを使用して、追加のパラメータ（フィルタなど）を指定できます。

connection.loadDashboard('42')
// OR
connection.loadUrl('/embed/dashboards/42?state=california')

新しい iframe を作成する必要がある場合、Embed SDK は署名エンドポイントまたはセッション取得エンドポイントを再度呼び出しません。代わりに、iframe src をビルダーから直接作成します。新しい埋め込みセッションを作成する必要がある場合は、次のように Embed SDK を再初期化する必要があります。

getEmbedSDK(new LookerEmbedExSDK()).init('looker.example.com', '/auth')

署名付き URL 認証エンドポイント

このセクションは、Cookie を使用しない埋め込みには適用されません。詳細については、Cookie を使用しない埋め込みをご覧ください。

Embed SDK を使用するには、埋め込み URL の署名を処理するバックエンド サービスを提供する必要があります。このサービスは、リクエスト元のユーザーに固有の署名付き URL を生成するために Embed SDK によって呼び出されます。バックエンド プロセスは、埋め込みシークレットを使用して署名付き埋め込み URL を生成するか、Looker Create Signed Embed URL API を呼び出して URL を生成できます。URL を手動で生成して署名すると、Looker API の呼び出しが回避され、レイテンシが短縮されます。Looker API を呼び出すと、必要なコードが少なくなり、メンテナンスが容易になります。

署名付き URL を生成するヘルパー メソッド createSignedUrl() の JavaScript の例は、server/utils/auth_utils.ts にあります。次のように使用します。

import { createSignedUrl } from './utils/auth_utils'

app.get('/looker_auth', function (req, res) {
  // It is assumed that the request is authorized
  const src = req.query.src
  const host = 'looker.example.com'
  const secret = ... // Embed secret from Looker Server Embed Admin page
  const user = ... // Embedded user definition
  const url = createSignedUrl(src, user, host, secret)
  res.json({ url })
})

リポジトリのPython の例をご覧ください。

署名付き URL の高度な認証構成

このセクションは、Cookie を使用しない埋め込みには適用されません。詳細については、Cookie を使用しない埋め込みをご覧ください。

options オブジェクトを init メソッドに渡すことで、カスタム リクエスト ヘッダーと CORS サポートを許可するように認証エンドポイントを構成できます。

getEmbedSDK().init('looker.example.com', {
  url: 'https://api.acme.com/looker/auth',
  headers: [{ name: 'Foo Header', value: 'Foo' }],
  params: [{ name: 'foo', value: 'bar' }],
  withCredentials: true, // Needed for CORS requests to Auth endpoint include Http Only cookie headers
})

トラブルシューティング

埋め込み SDK は chatty 上に構築されています。Chatty は、ロギングにデバッグを使用します。ブラウザ コンソールでロギングを有効にするには、次のコマンドを使用します。

localStorage.debug = 'looker:chatty:*'
```none

Note that both the parent window and the embedded content have separate local storage, so you can enable logging on one, the other, or both. You can disable logging with this command:

```javascript
localStorage.debug = ''