開始使用 VS Code 適用的 Looker 擴充功能

VS Code 適用的 Looker 擴充功能可讓您直接在本機桌面環境中開發 LookML。這項擴充功能提供完善的語法醒目顯示功能、與 Looker 執行個體的雙向檔案同步處理功能，以及 AI 程式設計代理整合功能，輕鬆執行「直覺式程式開發」。

這項擴充功能是使用 Visual Studio Code (VS Code) 框架建構而成，支援以 VS Code IDE 為基礎的整合式開發環境 (IDE)，例如下列 IDE 和程式碼編寫工具：

  • Claude Code
  • Codex
  • Cursor
  • Kiro
  • VS Code
  • 滑浪風帆
  • Zed

Looker 擴充功能 for VS Code 不支援非 VS Code 分支的 IDE，例如 IntelliJ 和 Eclipse。

本指南說明如何設定及驗證擴充功能。

AI 輔助工作流程

VS Code 適用的 Looker 擴充功能是 AI 輔助代理開發工作流程的一部分，可編輯及建立 LookML 檔案。如要啟用這項工作流程，請設定下列工具：

  • 適用於 VS Code 的 Looker 擴充功能。
  • 以 VS Code 為基礎的本機 IDE。IDE 必須包含內建 AI 代理 (例如 Cursor)，或者，如果 IDE 不含內建 AI 代理 (例如基本 VS Code)，則 IDE 必須與獨立代理工具 (例如 Gemini CLI 或 Claude Code) 整合。如要瞭解如何將 IDE 連線至代理，請參閱本機 IDE 的說明文件。
  • MCP 伺服器，例如 Looker 管理的 MCP 伺服器。

如要進一步瞭解由 AI 技術支援的工作流程，請參閱「使用 Looker 進行 AI 輔助開發 (直覺式程式開發)」說明文件頁面。

事前準備

安裝擴充功能前，請先符合下列條件：

  • 連線至 AI 工具：如果您打算使用 AI 輔助開發功能，請將 IDE 和 AI 代理連線至 Looker 管理的 MCP 伺服器。設定和範例設定會顯示在 Looker 管理的 MCP 伺服器說明文件頁面。詳情請參閱工具的說明文件。
  • Looker 權限：如要編輯模型，您必須擁有 develop Looker 權限。
  • Looker 執行個體：執行個體必須執行 Looker 26.6 以上版本。
  • 安裝 Git：您必須在本機安裝 Git，才能複製及管理 LookML 存放區。
  • 專案設定：LookML 專案必須設定 Git。
  • OAuth 用戶端 ID：如果您使用 OAuth 驗證 (建議做法)，請務必向 Looker 管理員索取 OAuth 用戶端 ID。

管理員設定

如果貴機構使用 OAuth 進行驗證，Looker 管理員必須在 Looker 管理員使用者介面中，將 VS Code 專用的 Looker 擴充功能註冊為 OAuth 用戶端。

使用 Looker API Explorer 設定 OAuth 整合。您可以透過下列任一方法存取 API Explorer：

已安裝 API Explorer

如果 Looker 執行個體已安裝 API Explorer，您可以使用下列網址格式存取：

LOOKER_INSTANCE_URL/extensions/marketplace_extension_api_explorer::api-explorer/

未安裝 API Explorer

如果 Looker 執行個體沒有 API 瀏覽工具，可以從 Looker Marketplace 安裝。如要瞭解如何安裝 API 瀏覽工具，請參閱「使用 API 瀏覽工具」頁面。

PSA 私人執行個體

如果您使用採用私人服務連線的 Looker (Google Cloud Core) 私人連線執行個體，則無法使用 Looker Marketplace 和 API 探索工具。如要註冊 AI 代理程式，請直接呼叫 oauth_client_apps API 端點。如果使用這個方法，可以略過 API 瀏覽工具程序的其餘步驟。

以下是 curl 指令範例，可用於 oauth_client_apps 端點，註冊代理程式。

curl -X POST "https://LOOKER_INSTANCE_URL/api/4.0/oauth_client_apps/CLIENT_GUID" \
-H "Authorization: token ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "redirect_uri": "REDIRECT_URI",
  "display_name": "CLIENT_NAME",
  "description": "OAuth client to access MCP server using CLIENT_NAME",
  "enabled": true
}'

如要註冊擴充功能，請完成下列步驟：

  1. 請按照「註冊 OAuth 用戶端應用程式」說明文件中的指示註冊擴充功能。

  2. 請完成下列步驟，填寫「client_guid」欄位：

    • 使用任何全域專屬 ID。
    • 請準備好將 ID 分發給想使用擴充功能的 LookML 開發人員。

  3. 如要使用 redirect_uri，請按照下列步驟操作：

    vscode://google.vscode-looker-official/oauth_callback

  4. 按照「註冊 OAuth 用戶端應用程式」說明文件中的步驟，完成 display_name 和 description。

應用程式註冊完成後，API 探索工具會傳回回應，其中包含註冊摘要。您可以使用 Get OAuth Client App 端點和 client_guid 檢查註冊詳細資料。

將產生的 client_guid 提供給開發人員，他們會在設定擴充功能時使用。

安裝擴充功能

如要安裝擴充功能，請完成下列步驟：

  1. 從 Visual Studio Marketplace 安裝 VS Code 的 Looker 擴充功能。
  2. 開啟 IDE，例如 VS Code 或 Cursor。
  3. 按一下活動列中的「擴充功能」圖示。
  4. 找出 VS Code 的 Looker 擴充功能，然後按一下「Install」。
  5. 安裝擴充功能後，活動列中會顯示 「Looker」圖示。

設定擴充功能

您必須在工作區的 settings.json 檔案中，使用 Looker 執行個體詳細資料設定擴充功能。

  1. 開啟工作區，然後開啟指令面板 (在 Mac 上按下 Command-Shift-P 鍵，或在 Windows/Linux 上按下 Ctrl+Shift+P 鍵)。
  2. 搜尋並選取「Preferences: Open Workspace Settings (JSON)」。
  3. 在設定中加入設定變數。設定變數會因驗證方法是 OAuth 或 API 憑證而異。

建議使用 OAuth 2.1 驗證流程。請將這些設定貼到工作區的 settings.json 檔案中。

{
  "looker.instanceUrl": "https://YOUR_INSTANCE_URL",
  "looker.oauthClientId": "YOUR_OAUTH_CLIENT_ID",
  "looker.projectId": "YOUR_PROJECT_ID"
}

更改下列內容：

  • https://YOUR_INSTANCE_URL：Looker 執行個體的網址。
  • YOUR_OAUTH_CLIENT_ID：從 Looker 管理員取得的 OAuth 用戶端 ID (client_guid)。
  • YOUR_PROJECT_ID：要編輯的專案名稱，如要尋找，請在 Looker 執行個體中開啟「LookML 專案」頁面。專案 ID 位於「專案」欄中。

使用 API 憑證進行驗證

如要使用 Looker API 金鑰，請按照說明文件建立 API 憑證。您也必須提供專案 ID。

{
  "looker.instanceUrl": "https://YOUR_INSTANCE_URL",
  "looker.clientId": "YOUR_CLIENT_ID",
  "looker.clientSecret": "YOUR_CLIENT_SECRET",
  "looker.projectId": "YOUR_PROJECT_ID"
}

更改下列內容：

  • https://YOUR_INSTANCE_URL：Looker 執行個體的網址。
  • YOUR_CLIENT_ID 和 YOUR_CLIENT_SECRET：用於驗證的 API 憑證的用戶端 ID 和用戶端密鑰。如要尋找這些憑證，請在 Looker 執行個體中開啟「帳戶」頁面，然後在「API 金鑰」部分中，按一下「管理」按鈕。這會開啟「API 金鑰」頁面，您可以在其中查看用戶端 ID 和密鑰。
  • YOUR_PROJECT_ID：要編輯的專案名稱，如要找出專案名稱，請在 Looker 執行個體中開啟「LookML 專案」頁面。專案 ID 位於「專案」欄中。

設定

您可以在 IDE 工作區中設定下列 MCP 設定。

設定 說明 預設
looker.instanceURL Looker 執行個體的基準網址 (例如 https://mycompany.looker.com)。 -
looker.authURL 用於 OAuth 驗證的網址。如果與執行個體網址不同，才需要設定。 looker.instanceURL
looker.sdkURL 用於 API 要求的網址。如果與執行個體網址不同，才需要設定。 looker.instanceURL
looker.oauthClientId Looker OAuth 用戶端 ID。使用 OAuth 時必須提供。 -
looker.clientId Looker API 用戶端 ID。使用 API 金鑰驗證時必須提供。 -
looker.clientSecret Looker API 用戶端密鑰。使用 API 金鑰驗證時必須提供。 -
looker.projectId Looker 專案 ID。 -
looker.mcpServerUrl 要做為 Proxy 的外部 MCP 伺服器網址 (例如 http://localhost:5000/mcp)。 -
looker.acceptSelfSignedCertificates 忽略 SSL 憑證錯誤 (例如自行簽署的憑證)。警告：不建議啟用這個選項。 false
looker.askBeforeOverwritingRemote 偵測到衝突時，一律先詢問是否要覆寫遠端檔案。 false

透過 Looker 驗證

如果使用 OAuth 驗證，請務必登入，將本機 IDE 連結至 Looker 帳戶。

  1. 開啟指令區塊面板。
  2. 執行「Looker: Sign In (OAuth)」(Looker：登入 (OAuth)) 指令。
  3. 確認提示，開啟瀏覽器。
  4. 在瀏覽器中，授權擴充功能存取您的 Looker 帳戶。
  5. 授權後，瀏覽器會重新導向回 IDE。您應該會看到「成功登入 Looker！」的通知。

複製 LookML 專案

如要開始開發，您必須將 LookML 存放區複製到本機電腦。

  1. 在 VS Code 中開啟新視窗。
  2. 開啟指令區塊面板，然後選取「Git: Clone」。
  3. 輸入遠端 Git 存放區的網址 (例如來自 GitHub 或 GitLab)，然後選擇本機資料夾。
  4. 在 IDE 中開啟複製的資料夾。

擴充功能會自動偵測 LookML 檔案，並開始與 Looker 執行個體開發模式中已簽出的分支機構同步。

疑難排解

您可以在 IDE 的「Output」面板中查看擴充功能記錄。選取「Looker」管道即可查看記錄。如要查看更詳細的記錄，請開啟指令區塊面板，執行「Developer: Set Log Level」指令，然後選取「Debug」或「Trace」。

  • 驗證錯誤：確認 looker.instanceUrl 和 looker.oauthClientId 正確無誤，並確保 Looker 中的重新導向 URI 完全相符。
  • 同步處理問題：檢查擴充功能記錄，解決同步處理問題。如要查看記錄，請開啟「Output」面板，然後從下拉式選單中選取「Looker」。
  • OAuth 期間出現「Bad Request」回應：請確認 Looker 執行個體可從區域網路存取，且您有有效的網際網路連線。

如果擴充功能發生問題，從命令列執行「Developer: Reload Window」(開發人員：重新載入視窗) 命令，可能有助於解決問題。

後續步驟