排解 Looker 擴充功能架構問題

Looker 擴充功能架構可讓您建構自訂 JavaScript 和 TypeScript 應用程式，以及在 Looker 中執行的圖表。擴充功能會在沙箱化 iframe 中執行，並透過擴充功能 SDK 與 Looker 執行個體互動。如果自訂擴充功能發生問題，例如 iframe 內出現空白頁面或錯誤訊息、瀏覽器控制台 JavaScript 或跨源資源共享 (CORS) 錯誤、Looker API 要求失敗 (4xx 或 5xx 狀態碼)，或 manifest.lkml 設定錯誤，本文可協助您排解及解決問題。

事前準備和一般設定需求

開始疑難排解前，請確認環境、LookML 專案和使用者帳戶符合執行 Looker 擴充功能的需求：

  • 啟用擴充功能架構：Looker 管理員必須依序前往「管理」>「平台」>「擴充功能架構」，啟用「擴充功能架構」設定。
  • LookML 專案和模型設定：每個擴充功能都需要 LookML 專案，其中包含下列元件：
  • 資訊清單授權：manifest.lkml 檔案中的 application 宣告必須明確定義擴充功能所需的所有 entitlements，例如 Looker API 呼叫的 core_api_methods，或外部網域要求的 external_api_urls。擴充功能必須有 entitlements 區塊才能執行。
  • 使用者授權：使用者必須具備擴充功能權限 (例如 access_data、explore 或 develop)，才能存取包含擴充功能 LookML 模型的模型集。開發人員必須具備 LookML develop 權限，才能建構擴充功能。
  • 診斷工具和環境詳細資料：開始疑難排解前，請備妥下列詳細資料和工具：
    • Looker 執行個體網址、LookML 專案名稱，以及在 manifest.lkml 中宣告的 application 名稱。
    • 在用戶端機器上存取網路瀏覽器的開發人員工具 (「Console」和「Network」分頁)。
    • 在本機開發期間，存取執行本機開發伺服器的終端機。
    • Looker API 呼叫發生 5xx 伺服器錯誤時，存取 Looker 執行個體記錄 (客戶託管執行個體的 looker.log，或 Looker (Google Cloud Core) 執行個體的 Google Cloud 控制台 Cloud Logging 記錄檔探索工具)。

偵錯樹狀結構

請使用下列決策樹，開始排解 Looker 擴充功能架構問題：

以下各節將進一步說明樹狀圖中的情境。

檢查瀏覽器控制台和網路記錄

Looker 擴充功能會在瀏覽器的用戶端執行，因此請先檢查瀏覽器的開發人員工具，找出 JavaScript 錯誤、違反安全性政策和失敗的 HTTP 要求，開始排解問題。

檢查瀏覽器控制台是否有錯誤

如要找出導致擴充功能無法載入或執行的用戶端錯誤，請按照下列步驟操作：

  1. 在 Looker 中，開啟載入擴充功能的頁面。
  2. 在頁面任一處按一下滑鼠右鍵，然後選取「檢查」 (或在 Windows 和 Linux 上按下 Control+Shift+I 鍵，或在 macOS 上按下 Command+Option+I 鍵)。
  3. 在開發人員工具面板中，選取「Console」分頁標籤。
  4. 重新整理頁面，擷取初始載入期間發生的錯誤。
  5. 檢查控制台中的紅色錯誤訊息：

在「Network」分頁中檢查失敗的要求

如要分析擴充功能對 JavaScript 組合、資產或 API 端點發出的 HTTP 要求，請按照下列步驟操作：

  1. 在瀏覽器開發人員工具面板中，選取「Network」分頁標籤。
  2. 勾選「Disable cache」核取方塊，讓瀏覽器不會載入過時的快取資源。
  3. 重新整理載入擴充功能的頁面。
  4. 檢查網路要求清單，找出任何 4xx 或 5xx 狀態碼，然後選取失敗的要求，檢查其「標頭」、「酬載」和「回應」分頁：
    • 404 擴充功能套件 (例如 bundle.js)：確認開發伺服器正在執行，且 manifest.lkml 中的 url 或 file 參數正確無誤。
    • Looker API 要求傳回 401 或 403：請檢查驗證、權限和授權。
    • API 要求上的 400 或 422：檢查「Payload」和「Response」分頁，找出格式錯誤的 JSON 或無效的要求參數。
    • 5xx 伺服器錯誤：代表 Looker 執行個體發生伺服器端錯誤。請查看客戶託管執行個體上的 looker.log，或控制台中的 Logs Explorer，找出時間戳記相符的 Looker (Google Cloud Core) 執行個體項目。

如果「Console」或「Network」分頁中未顯示任何錯誤，或您需要驗證 Looker 載入擴充功能的方式，請前往下一節。

驗證資訊清單和專案設定

專案 manifest.lkml 檔案中的 application 宣告會控制 Looker 載入擴充功能的方式，以及擴充功能可使用的資源。manifest.lkml 設定錯誤是載入和 API 失敗的常見原因：

  • 驗證 url 或 file 參數：在 Looker IDE 中，開啟專案的 manifest.lkml 檔案，並檢查 application 宣告：
    • application 宣告必須包含 url 參數或 file 參數，但不得同時包含兩者。
    • 在本機開發期間：確認 url 參數與本機開發伺服器提供的通訊協定 (http 或 https)、主機名稱、通訊埠和路徑完全相符 (例如 https://localhost:8080/bundle.js)。
    • 在正式環境中：確認您已將 LookML 專案 (例如 file: "apps/bundle.js") 或正式環境套件網址中的 application 宣告，從本機開發 url 更新為正式環境 file 路徑。
  • 驗證 manifest.lkml 授權：查看 application 宣告中的 entitlements 區塊。除非明確宣告該權利，否則擴充功能無法使用 Looker 資源或外部網域，如下所示：
    • core_api_methods：必須列出擴充功能呼叫的所有 Looker API 方法 (例如 core_api_methods: ["me", "all_looks", "run_inline_query"])。
    • external_api_urls：必須列出擴充功能直接或透過 Proxy 要求的外部非 Looker 網域。
    • 額外授權：確認擴充功能是否需要 local_storage、navigation、new_window、new_window_external_urls、use_form_submit、use_embeds、use_downloads、use_iframes、use_clipboard、oauth2_urls、global_user_attributes 或 scoped_user_attributes。
  • 驗證、修訂及部署：編輯 manifest.lkml 後，點按「Validate LookML」，修訂變更，然後點按「Deploy to Production」，讓更新後的設定生效。

排解本機開發伺服器和環境問題

在本機開發擴充功能時，如果使用 manifest.lkml 中的 url 參數，本機開發伺服器必須處於執行中狀態，且可透過瀏覽器存取：

  • 確認開發伺服器正在執行：檢查您啟動開發伺服器的終端機視窗 (例如使用 yarn develop 或 npm start)：
    • 確認建構作業已編譯完成，且未發生任何錯誤，並顯示監聽訊息 (例如 webpack compiled successfully 或 listening on localhost:8080)。
    • 如果伺服器未執行，請使用 yarn develop 或 npm start 啟動。
    • 如果伺服器因語法錯誤或缺少依附元件錯誤而結束，請解決程式碼錯誤，或執行 yarn install (或 npm install) 安裝缺少的套件。
    • 如果伺服器因通訊埠衝突 (EADDRINUSE) 而失敗，請停止使用該通訊埠的其他程序，或設定開發伺服器和 manifest.lkml url 參數，改用其他通訊埠。
  • 直接在瀏覽器中開啟擴充功能網址：複製 manifest.lkml 中的 url 值 (例如 https://localhost:8080/bundle.js)，然後在新的瀏覽器分頁中開啟：
    • 不受信任的自行簽署 SSL 憑證：本機開發伺服器經常使用自行簽署的 SSL 憑證。如果瀏覽器顯示憑證安全性警告，請選取「Advanced」(進階)，然後前往 localhost，信任瀏覽器工作階段的憑證。在憑證獲得信任之前，瀏覽器會禁止在 Looker iframe 中載入套件。
    • 連線遭拒或封鎖：如果瀏覽器無法連上網址，請確認沒有本機防火牆或端點安全防護軟體封鎖連至 localhost 設定通訊埠的連線。

排解網路、CORS 和安全性政策問題

網路瀏覽器會強制執行同源政策，除非設定跨源資源共享 (CORS) 標頭和安全性政策，否則 Looker 無法載入擴充功能資源，或呼叫不同來源的外部伺服器：

  • 在瀏覽器控制台中找出 CORS 錯誤：在「控制台」分頁中，尋找含有 Cross-Origin Resource Sharing、CORS、has been blocked by CORS policy 或缺少 Access-Control-Allow-Origin 標頭的錯誤訊息。
  • 設定本機開發伺服器 CORS 標頭：如果您使用 webpack-dev-server (或類似的套件組合工具)，請確認 webpack.config.js 中的 devServer 設定包含 Access-Control-Allow-Origin 標頭：javascript devServer: { headers: { "Access-Control-Allow-Origin": "*" } }
  • 設定正式版託管和外部 API CORS 標頭：如果擴充功能會從外部服務 (例如 Cloud Storage、Amazon S3 或自訂後端伺服器) 載入資產或要求資料，請設定託管服務傳回 Access-Control-Allow-Origin 標頭，允許 Looker 執行個體網域。此外，請確認沒有任何網路 Proxy 或防火牆從回應中移除 CORS 標頭，並確保外部網域列在 manifest.lkml 的 external_api_urls 中。
  • 檢查內容安全政策 (CSP) 和強化擴充功能載入：如果 在載入擴充功能時遇到 CSP 違規，請依序前往 「管理」>「平台」>「擴充功能架構」，查看「強化擴充功能載入」 設定。

排解驗證和 API 存取問題

擴充功能會透過擴充功能 SDK，代表登入的使用者與 Looker API 互動。如果 API 呼叫失敗，且「Network」分頁中顯示 401 Unauthorized 或 403 Forbidden 狀態碼，請檢查下列項目：

  • 區分 401 和 403 錯誤：
    • 401 Unauthorized：要求未經驗證。如果擴充功能 SDK 未正確初始化，或擴充功能在 SDK 完成驗證交握前嘗試呼叫 API，通常就會發生這個錯誤。
    • 403 Forbidden：要求已通過驗證，但登入的使用者缺少必要的 Looker 權限，或擴充功能的 manifest.lkml 未在 core_api_methods 中包含呼叫的方法。
  • 驗證使用者角色和權限：在「管理」>「使用者」和「管理」>「角色」中，檢查登入使用者的指派角色、權限集和模型集：
    • 確認使用者具備擴充功能使用權限，包括 access_data (以及視需要具備 explore 或 develop)，適用於包含擴充功能 LookML 模型和擴充功能查詢模型的模型集。
    • 確認使用者的角色包含擴充功能呼叫的各個 Looker API 端點所需的特定權限。
  • 呼叫 API 前，請確認 SDK 情境已準備就緒：確認擴充功能程式碼會等待擴充功能 SDK 情境初始化，再叫用 API 方法。

排解擴充功能 SDK 和依附元件問題

如果 npm 或 Yarn 套件安裝發生問題，或缺少 SDK 供應商元件，擴充功能可能無法編譯或連結至 Looker：

  • 驗證 Node.js 模組安裝：在終端機中，前往擴充功能專案的根目錄，並檢查 node_modules 目錄：
    1. 如果缺少 node_modules 或依附元件似乎損毀，請刪除 node_modules 目錄和鎖定檔案 (yarn.lock 或 package-lock.json)。
    2. 選用：如果套件安裝作業一再失敗，請清除套件管理工具快取 (例如執行 npm cache clean --force)。
    3. 確認安裝的 Node.js 版本符合專案需求，然後執行 yarn install 或 npm install 執行全新安裝。
  • 檢查 ExtensionProvider 初始化：開啟擴充功能的主要進入點檔案 (例如 App.js 或 index.js)，確認 <ExtensionProvider> (從 @looker/extension-sdk-react 匯入) 包裝了需要 Looker SDK 內容的應用程式元件：javascript ReactDOM.render( <ExtensionProvider> <App /> </ExtensionProvider>, document.getElementById('root') );如果缺少 <ExtensionProvider>，或您將其放在呼叫 SDK 的元件之後，子元件就無法存取 SDK 內容。

排解執行階段 JavaScript 和邏輯錯誤

如果擴充功能的設定、開發伺服器、權限和 SDK 設定都有效，問題可能是擴充功能的自訂 JavaScript 或 TypeScript 程式碼發生執行階段錯誤：

  • 分析控制台堆疊追蹤：在瀏覽器的「Console」分頁中，找出紅色錯誤訊息，然後按一下展開箭頭，查看完整的堆疊追蹤。堆疊追蹤記錄的頂端行會指出發生錯誤的原始碼檔案和行號。按一下檔案連結 (例如 MyComponent.js:42)，即可直接跳到「Sources」分頁中的該行。
  • 檢查未定義或空值：如果發生 TypeError: Cannot read properties of undefined 等錯誤，請確認非同步 API 回應或屬性已完成載入，再讓程式碼讀取巢狀屬性。新增防禦性檢查 (例如 if (myObject && myObject.property) 或選用鏈結 myObject?.property)。
  • 驗證 API 回應格式：確認程式碼會處理 Looker API 呼叫傳回的實際資料結構 (例如，在呼叫陣列方法前，先驗證回應酬載是物件還是陣列)。
  • 使用中斷點和記錄功能偵錯：在瀏覽器的「來源」分頁中，在失敗行之前設定中斷點，暫停執行並即時檢查變數值，或新增 console.log() 陳述式來追蹤執行流程。

確認 Looker 版本相容性

Looker 的重大功能更新或變更，可能需要相容版本的 Looker Extension SDK：

  1. 在擴充功能專案的 package.json 檔案中，檢查 @looker/extension-sdk (和 @looker/extension-sdk-react，如有使用) 的版本。
  2. 在 Looker 網頁介面中，依序前往「Help」>「About」或「Admin」>「General」>「Settings」，查看執行個體目前的發布版本。
  3. 請比較您的 Looker 發布版本與 @looker/extension-sdk 說明文件中的相容性附註。
  4. 如果 Looker 執行個體最近升級，且擴充功能使用過時的 SDK，或擴充功能使用較新 SDK 功能，但舊版 Looker 不支援，請將 SDK 套件更新至相容版本： bash npm install @looker/extension-sdk@latest 更新套件後，請重新安裝依附元件，並重新啟動開發伺服器。

收集診斷資訊

如果按照疑難排解步驟操作後仍無法解決問題，請先收集下列資訊，再與支援團隊聯絡：

  1. Looker 執行個體和專案資訊：
    • Looker 執行個體網址 (例如 instance_name.looker.com)。
    • Looker 發布版本。
    • LookML 專案的名稱，其中包含擴充功能和 manifest.lkml 中的 application 名稱。
  2. 擴充功能設定和 SDK 詳細資料：
    • manifest.lkml 檔案中 application 宣告的副本或螢幕截圖。
    • package.json 中指定的 @looker/extension-sdk 版本。
    • 擴充功能是在本機開發伺服器 (url) 執行，還是已部署至正式環境 (file)。
  3. 錯誤記錄和螢幕截圖：
    • 瀏覽器「控制台」和「網路」分頁中的錯誤螢幕截圖或全文 (包括失敗 4xx 或 5xx 要求的「要求標頭」和回應酬載)。
    • 如果 API 呼叫持續傳回 5xx 伺服器錯誤，請提供 looker.log (適用於客戶託管執行個體) 或 Logging 的 Logs Explorer (適用於 Looker (Google Cloud Core) 執行個體) 的相符記錄摘錄。
  4. 疑難排解摘要和重現步驟：
    • 您已執行的疑難排解步驟摘要和結果。
    • 重現問題的確切步驟，或最小可重現範例 (如果您懷疑 Looker 擴充功能架構或擴充功能 SDK 有問題)。

聯絡支援團隊

如果已驗證上述所有步驟，但問題仍未解決，請按照下列指示操作：