嵌入 SDK 簡介

Looker 的嵌入 SDK 是可新增至瀏覽器式網頁應用程式程式碼的函式程式庫，可用於管理網頁應用程式中的嵌入式資訊主頁、Look、報表和探索。

Embed SDK 可透過以下方式協助您進行嵌入：

  • 提供嵌入內容的封裝，不必手動建立 HTML 元素。
  • 提供點對點通訊，以免發生跨影格通訊。Embed SDK 會使用專屬訊息管道，處理主機網頁和嵌入 Looker 內容之間的跨網域訊息傳遞作業。

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

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

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

請注意，Looker 不會控制瀏覽器將事件調度至網頁應用程式的順序。也就是說，我們無法保證事件在瀏覽器或平台之間的順序。請務必妥善編寫 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 Embed SDK 採用流暢介面模式。安裝嵌入 SDK 後，您就可以建構嵌入內容，並連結至嵌入內容。連線建立後，代管應用程式可能會與嵌入內容互動。

安裝 Embed SDK

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

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

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

建構嵌入內容

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

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

疑難排解

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