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 レポート機能が有効になっている場合に利用できます。レポートは、署名付き埋め込みメソッド、クッキーを使用しない埋め込みメソッド、非公開埋め込みメソッドを使用して埋め込むことができます。詳しくは、Looker レポートを埋め込むをご覧ください。

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

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

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

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

• Looker Embedded SDK はウェブ アプリケーションのクライアント側コードに存在し、Looker の埋め込みコンテキストとコンテンツを管理します。（Embed 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 は流暢なインターフェース パターンを使用します。Embed SDK をインストールしたら、埋め込みコンテンツを作成して、その埋め込みコンテンツに接続します。接続が確立されると、ホスティング アプリケーションは埋め込みコンテンツとやり取りできます。

Embed SDK のインストール

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

Looker Embed SDK リポジトリを使用して Looker Embed 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()

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

クライアントがビルドされたら、connect を呼び出して iframe を作成します。接続プロセスでは、実際の iframe に使用される src 属性が作成されます。src 値の生成方法は、埋め込み SDK の初期化方法に基づいています。

1. 署名済み: init 呼び出しの 2 番目の引数で指定されたエンドポイントが呼び出されます。エンドポイントは、署名付き埋め込みログイン URL を返すことが想定されています。
2. Cookie なし: initCookieless 呼び出しの 2 番目の引数で指定されたエンドポイントまたは関数が呼び出されます。エンドポイントまたは関数は、クッキーレス トークン（具体的には認証トークンとナビゲーション トークン）を返すことが想定されています。トークンは埋め込みログイン 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 の署名処理を行うバックエンド サービスを指定する必要があります。このサービスは、Embed SDK によって呼び出され、リクエスト ユーザーに固有の署名付き URL を生成します。バックエンド プロセスは、埋め込みシークレットを使用して署名付き埋め込み URL を生成するか、Looker の署名付き埋め込み 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 を使用しない埋め込みをご覧ください。

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