表示されているのは Looker のドキュメントです。Looker Studio のドキュメントについては、https://support.google.com/looker-studio をご覧ください。

Embedded SDK の概要

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

HTML 要素を手動で作成しなくても、埋め込みコンテンツをカプセル化できます。
ポイントツーポイント通信を行うことで、クロスフレーム通信を発生させない。Embedded 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 の埋め込みコンテキストとコンテンツを管理します。（Embedded 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)
  })

詳細な例については、埋め込み 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 をインストールするには:

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 Embedded SSO の例の GitHub リポジトリに記載されているプロセスのいずれかを使用して、署名付き URL を返す必要があります。
Embedded SSO URL を Embedded 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: {}
}

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

トラブルシューティング

ロギング

埋め込み 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 = ''