嵌入 SDK 簡介

Looker 的 Embed SDK 是一組函式庫，您可以將這些函式庫新增至瀏覽器型網頁應用程式的程式碼，以便在網頁應用程式中管理內嵌資訊主頁、Look、報表和探索。

Embed SDK 可透過下列方式簡化嵌入作業：

  • 提供內嵌內容的封裝，不必手動建立 HTML 元素。
  • 提供點對點通訊，因此不會有跨框架通訊。嵌入 SDK 會利用專屬訊息管道，處理主機網頁和嵌入 Looker 內容之間的跨網域訊息傳遞作業。

如果沒有 Embed SDK，您可以使用 JavaScript 事件 (例如 dashboard:run:start 或 page:changed) 叫用或回應內嵌 Looker 內容中的事件，這些事件說明請參閱「內嵌 JavaScript 事件」說明文件頁面。如果開發人員使用 JavaScript 事件嵌入 Looker 內容，就必須建立 HTML 元素來存放嵌入內容，並透過視窗廣播事件，在網頁應用程式和嵌入內容之間進行通訊。

請注意，Looker Embed SDK 與 Looker API 和 Looker API SDK 不同：

  • Looker 嵌入 SDK 位於網路應用程式的用戶端程式碼中，可管理 Looker 嵌入環境和內容。(Embed SDK 無法存取 Looker API)。
  • Looker API 位於 Looker 執行個體所在的伺服器，並在 Looker 伺服器上執行指令。
  • Looker API 用戶端 SDK 位於非瀏覽器應用程式的程式碼中，可提供 Looker API 函式的存取權。

請注意，Looker 不會控管瀏覽器將事件派送至 Web 應用程式的順序。也就是說，我們無法保證事件順序在不同瀏覽器或平台之間一致。請務必正確編寫 JavaScript，以因應不同瀏覽器的事件處理方式。

快速範例

在本例中，系統會在 ID 為 embed_container 的 DOM 元素內，建立 ID 為 11 的資訊主頁。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 嵌入 SDK

Looker 嵌入 SDK 使用流暢的介面模式。安裝 Embed SDK 後，請建構內嵌內容並連線至內嵌內容。建立連線後，主機應用程式即可與嵌入的內容互動。

安裝 Embed SDK

您可以透過節點套件管理工具 (NPM) 取得 Looker 的 Embed SDK 程式庫，網址為 https://www.npmjs.com/package/@looker/embed-sdk。不過，如要查看範例程式碼或試用版，請改用 Looker Embed SDK 存放區。

如要使用 Looker 嵌入 SDK 存放區安裝 Looker 嵌入 SDK，請按照下列步驟操作：

  1. 如果尚未安裝 Node.js，請先完成這項程序。
  2. 下載或複製 /looker-open-source/embed-sdk 存放區。
  3. 在終端機視窗中，前往 /embed-sdk 目錄並執行下列指令：
npm install
npm start

建構嵌入內容

首先，請使用 Looker 伺服器的位址，以及將建立已簽署 Looker 嵌入式登入網址的嵌入應用程式伺服器端點，初始化 SDK。所有嵌入內容都會使用這些伺服器。如果是私人嵌入，請省略簽署端點。

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

然後，系統會透過一連串步驟定義參數，建構內嵌內容。部分參數為選用，部分則為必填。

首先，請使用資訊主頁 id 或參照資訊主頁的 url 建立建構工具 (資訊主頁是透過「已簽署的嵌入」說明文件頁面所述程序建立)。

getEmbedSDK().createDashboardWithId('id')

或

getEmbedSDK().createDashboardWithUrl('url')

接著，您可以在建構工具中新增其他屬性，完成設定。

舉例來說，您可以指定要在網頁的哪個位置插入 Looker 嵌入式 UI。下列呼叫會將 Looker 嵌入式 UI 放入 ID 值為 dashboard 的 HTML 元素中：

.appendTo('#dashboard')

新增事件處理常式：

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

呼叫建構方法，建立內嵌用戶端：

.build()

連結至嵌入內容

建構用戶端後，請呼叫 connect 來建立 iframe。連結程序會建立用於實際 iframe 的 src 屬性。src 值的產生方式取決於嵌入 SDK 的初始化方式：

  1. 已簽署：系統會呼叫 init 呼叫的第二個引數所指定的端點。端點應會傳回已簽署的嵌入式登入網址。
  2. 無 Cookie：系統會呼叫 initCookieless 呼叫的第二個引數所指定的端點或函式。端點或函式應傳回不含 Cookie 的權杖，具體來說就是驗證和導覽權杖。權杖會附加至嵌入登入網址。
  3. 私人：如果未提供 init 呼叫的第二個引數，嵌入連線就是私人連線。在本例中，網址是從產生器衍生而來，並以 Looker 嵌入功能所需的參數裝飾。如果是私人嵌入，使用者應已登入 Looker 或嵌入網址包含 allow_login_screen=true 參數。

connect 會傳回 Promise，該物件會解析為內嵌 iframe 的連線介面。

  .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')

已簽署網址的驗證端點

本節不適用於無 Cookie 嵌入。詳情請參閱「無 Cookie 嵌入」一文。

如要使用 Embed SDK，您必須提供可處理嵌入網址簽署作業的後端服務。這個服務會由 Embed SDK 呼叫，產生要求使用者專屬的已簽署網址。後端程序可以使用嵌入密鑰自行產生已簽署的嵌入網址，也可以呼叫 Looker Create Signed Embed URL API 產生網址。手動產生及簽署網址可避免呼叫 Looker API，進而縮短延遲時間。呼叫 Looker API 需要的程式碼較少，也更容易維護。

如需產生已簽署網址 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 範例。

已簽署網址進階驗證設定

本節不適用於無 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
})

疑難排解

Embed SDK 是以 chatty 為基礎建構而成。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 = ''