開始使用 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

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

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

AI 輔助工作流程

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

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

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

事前準備

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

連結至 AI 工具：如要使用 AI 輔助開發功能，請將 IDE 和 AI 代理連結至 MCP Toolbox for Databases。舉例來說，如要將 MCP Toolbox 連接至 Gemini CLI，請參閱「搭配使用 Looker、MCP、Gemini CLI 和其他代理程式」說明文件中的範例設定。詳情請參閱工具的說明文件。
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：

如果 Looker 執行個體已安裝 API Explorer，您可以使用下列網址格式存取：
```
https://LOOKER_INSTANCE_URL/extensions/marketplace_extension_api_explorer::api-explorer/
```
如果 Looker 執行個體沒有 API 瀏覽工具，可以從 Looker Marketplace 安裝。詳情請參閱「使用 API Explorer」頁面。

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

請按照「註冊 OAuth 用戶端應用程式」說明文件中的指示註冊擴充功能。
請完成下列步驟，填寫 client_guid 欄位：
- 使用任何全域專屬 ID。
- 請準備好將 ID 分發給想使用擴充功能的 LookML 開發人員。

如要使用 redirect_uri，請輸入：

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

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

應用程式註冊完成後，API Explorer 會傳回含有註冊摘要的回應。您可以使用 Get OAuth Client App 端點和 client_guid 檢查註冊詳細資料。

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

安裝擴充功能

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

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

設定擴充功能

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

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

使用 OAuth 進行驗證 (建議)

建議使用 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 帳戶。

開啟指令區塊面板。
執行「Looker: Sign In (OAuth)」(Looker：登入 (OAuth)) 指令。
確認提示，開啟瀏覽器。
在瀏覽器中，授權擴充功能存取您的 Looker 帳戶。
授權完成後，瀏覽器會重新導向回 IDE。畫面上應會顯示「Successfully signed in to Looker!」(已成功登入 Looker！)通知。

複製 LookML 專案

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

在 VS Code 中開啟新視窗。
開啟指令區塊面板，然後選取「Git: Clone」。
輸入遠端 Git 存放區的網址 (例如來自 GitHub 或 GitLab)，然後選擇本機資料夾。
在 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」(開發人員：重新載入視窗) 指令，可能有助於解決問題。