Looker 22.16 のドキュメントを表示しています。最新のドキュメントはこちらをご覧ください。

Embed SDK の概要

Looker の Embed SDK は、ブラウザベースのウェブアプリケーションのコードに追加できる関数のライブラリです。ウェブアプリの埋め込みダッシュボード、Look、Explore を管理できます。Embed SDK では、次の方法で埋め込みを簡単に行うことができます。

HTML 要素を手動で作成しなくても、埋め込みコンテンツをカプセル化できます。
フレーム間通信が行われないようにポイントツーポイント通信を提供する。Embed SDK では、専用のメッセージチャネルを使用して、ホストウェブページと埋め込み Looker コンテンツの間でクロスドメインメッセージを渡します。

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

なお、Looker Embed SDK は、Looker API および Looker API SDK とは異なります。

Looker Embed SDK はウェブアプリケーションのクライアント側コードにあり、Looker 埋め込みのコンテキストとコンテンツを管理します。（Embed SDK では Looker API へのアクセスは提供されません）。
Looker API は、Looker インスタンスとともにサーバー上で動作し、Looker サーバーでコマンドを実行します。
Looker API クライアント SDK は、ブラウザ以外のアプリケーションのコードに含まれており、Looker API 関数に簡単にアクセスできます。

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

簡単な例

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

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

const setupDashboard = (dashboard) => {
  document.querySelector('#run').addEventListener('click', () => {
    dashboard.send('dashboard:run')
  })
}

LookerEmbedSDK.createDashboardWithId(11)
  .appendTo('#dashboard')
  .on('dashboard:run:start',
      () => updateState('#dashboard-state', 'Running')
  )
  .on('dashboard:run:complete',
      () => updateState('#dashboard-state', 'Done')
  )
  .build()
  .connect()
  .then(setupDashboard)
  .catch((error: Error) => {
    console.error('An unexpected error occurred', error)
  })

より詳細な例については、Embed SDK のデモに関するドキュメントページをご覧ください。

Looker Embed SDK の設定

Looker Embed SDK では、滑らかなインターフェースパターンが使用されます。Embed SDK をインストールしたら、埋め込みコンテンツを作成し、埋め込みコンテンツに接続します。

Embed SDK のインストール

Looker の Embed SDK ライブラリは、https://www.npmjs.com/package/@looker/embed-sdk の Node Package Manager（NPM）から入手できます。ただし、サンプルコードまたはデモを確認する場合は、代わりに Looker Embed SDK リポジトリを使用してください。

Looker Embed SDK リポジトリを使用して Looker Embed SDK をインストールするには:

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

npm install
npm start

埋め込みコンテンツの構築

まず、ウェブサーバーのアドレスと、必要に応じて認証を行うサーバー上のエンドポイントで、SDK を初期化します。これらはすべての埋め込みコンテンツで使用されます。

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

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

次に、一連のステップを使用して埋め込みコンテンツを作成し、パラメータを定義します。これらのパラメータには省略可能なものと、必須なものがあります。

このプロセスは、ダッシュボードの id、またはダッシュボードを参照する url（シングルサインオン（SSO）埋め込みドキュメントプロセスで作成される）を使用してビルダーを作成します。

LookerEmbedSDK.createDashboardWithId(id)

または

LookerEmbedSDK.createDashboardWithUrl(url)

その後、ビルダーに属性を追加して設定を完了します。たとえば、Looker 埋め込み UI を挿入するウェブページの場所を指定できます。次の呼び出しは、ID 値が dashboard の HTML 要素内に Looker 埋め込み UI を配置します。

.appendTo('#dashboard')

イベントハンドラは次の方法で追加できます。

.on('dashboard:run:start',
  () => updateState('#dashboard-state', 'Running')
)
.on('dashboard:run:complete',
  () => updateState('#dashboard-state', 'Done')
)

最後に、埋め込み要素を作成します。

.build()

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

埋め込まれた要素との間でメッセージを送受信する場合は、connect() を呼び出す必要があります。これは、指定された要素の通信インターフェースに解決される Promise を返します。

.connect()
.then(setupDashboard)
.catch(console.error)

SDK の URL の作成

Looker SSO 埋め込み URL に関する主要なドキュメントは、シングルサインオン（SSO）埋め込みのドキュメントページにあります。SDK の URL を作成する際の唯一の違いは、フィルタや embed_domain パラメータなどの他のパラメータとともに、埋め込み URL に sdk=2 パラメータを追加する必要があることです。このパラメータにより、Looker は SDK が存在すると判断し、SDK によって提供される追加機能を利用します。例:

/embed/looks/4?embed_domain=https://mywebsite.com&sdk=2
                                                 ^^^^^^

このパラメーターは署名付きSSO URLの一部であることから、SDK自体がこのパラメーターを追加することはできません。

Auth エンドポイント

埋め込みシークレットは慎重に保護する必要があるため、埋め込み SSO URL はブラウザで作成できません。このプロセスをより簡単かつ安全にするには、代わりに次の手順を行います。

ウェブサーバーに URL 署名関数を実装します。サーバーは、Looker Embed SSO の例にある GitHub リポジトリに記載されているプロセスのいずれかを使用して、署名付き URL を返す必要があります。
Embed SSO の URL を Embed SDK でその署名エンドポイントに渡します。エンドポイントの場所は、LookerEmbedSDK.init() の authUrl パラメータで指定されます。

指定すると、ID のみを使用して埋め込み要素が作成されるたびに、要素の型、指定された Looker ホスト、指定パラメータを使用して埋め込み URL が生成されます。例:

LookerEmbedSDK.init('looker.example.com', '/looker_auth')
LookerEmbedSDK.createcreateDashboardWithId(11)
  .build()

これにより /looker_auth エンドポイントが呼び出され、埋め込みコンテンツの作成に使用できる署名付き SSO URL が返されます。

src=https://looker.example.com/embed/dashboards/11?sdk=2&embed_host=https://yourhost.example.com

高度な認証の構成

カスタムのエンドポイントで CORS もサポートされるように Auth エンドポイントをさらに構成することもできます。これを行うには、オプションオブジェクトを init メソッドに渡します。


LookerEmbedSDK.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
  })

ノードヘルパー

署名ヘルパーメソッド createSignedUrl() が server_utils/auth_utils.ts に用意されています。使い方は次のとおりです。

import { createSignedUrl } from './auth_utils'

app.get('/looker_auth', function(req, res) {
  // TO DO: Add your code here to authenticate that the request is from a valid user
  const src = req.query.src;
  const host = 'https://looker.example.com'
  const secret = YOUR_EMBED_SECRET
  const user = authenticatedUser
  const url = createSignedUrl(src, user, host, secret);
  res.json({ url });
});

ユーザーデータの構造は次のとおりです。

interface LookerEmbedUser {
  external_user_id: string
  first_name?: string
  last_name?: string
  session_length: number
  force_logout_login?: boolean,
  permissions: LookerUserPermission[]
  models: string[]
  group_ids?: number[]
  external_group_id?: string
  user_attributes?: {[key: string]: any}
  access_filters: {}
}

access_filters パラメータは Looker 3.10 で削除されましたが、埋め込み URL の空のプレースホルダでは必須です。

トラブルシューティング

ロギング

Embed SDK はチャット機能の上に構築されています。Chatty はロギングに debug を使用します。ブラウザコンソールでロギングを有効にするには、次のコマンドを使用します。

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 = ''