Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

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

透過 Visual Studio Code (VS Code) 的 Looker by Google Cloud 擴充功能，您可以在本機電腦環境中直接開發 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 為基礎的本機 IDE。IDE 必須包含內建 AI 代理 (例如 Cursor)，如果 IDE 沒有內建 AI 代理，則必須整合獨立代理工具 (例如 Gemini CLI 或 Claude Code)。如要瞭解如何將 IDE 連線至代理程式，請參閱本機 IDE 的說明文件。
適用於 VS Code 的 Looker 擴充功能。
MCP 伺服器，例如 Looker 管理的 MCP 伺服器。

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

事前準備

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

Looker 管理的 MCP 伺服器 (選用，但建議使用)：如果您打算使用 AI 輔助開發功能，請將 IDE 和 AI 代理連線至 Looker 管理的 MCP 伺服器。如需設定 MCP 伺服器的操作說明，請參閱「Looker 代管的 MCP 伺服器」說明文件頁面。詳情請參閱工具的說明文件。
Looker 權限：如要編輯模型，您必須擁有 develop Looker 權限。
Looker 執行個體：執行個體必須執行 Looker 26.6 以上版本。
專案設定：您必須在 Looker 中擁有專案 (設定為裸存放區或設定為 Git)。
安裝 Git (選用)：如要複製 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 Explorer，請參閱「使用 API Explorer」頁面。

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

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

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

在 redirect_uri 中，輸入 IDE 的回呼網址。請根據 IDE 或編碼工具，使用下列其中一個回呼網址：

IDE 或工具	回呼網址
Antigravity IDE (適用於 Looker 26.12 以上版本)	antigravity-ide://google.vscode-looker-official/oauth_callback
Code-OSS	code-oss://google.vscode-looker-official/oauth_callback
Cursor	cursor://google.vscode-looker-official/oauth_callback
HTTPS	https://google.vscode-looker-official/oauth_callback
Kiro (Looker 26.16 以上版本支援 Kiro 的 OAuth)	kiro://google.vscode-looker-official/oauth_callback
Looker	looker://google.vscode-looker-official/oauth_callback
VS Code	vscode://google.vscode-looker-official/oauth_callback
滑浪風帆	windsurf://google.vscode-looker-official/oauth_callback

確認「Enabled」欄位已設為 true。
按照「註冊 OAuth 用戶端應用程式」說明文件中的說明，填寫 display_name 和 description 欄位。

應用程式註冊完成後，API 探索工具會傳回回應，其中包含註冊摘要。請確認重新導向 URI 與您在要求參數中輸入的內容相符。您可以使用 Get OAuth Client App 端點和 client_guid 值，查看註冊詳細資料。

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

安裝擴充功能

這項擴充功能已在兩大擴充功能市集上架：

Visual Studio Marketplace (適用於標準 VS Code)
開啟 VSX 登錄檔 (適用於 Cursor、Antigravity IDE 和 VSCodium)

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

開啟 IDE，例如 VS Code 或 Cursor。
按一下活動列中的「擴充功能」圖示。
找到「Looker by Google Cloud」，然後按一下「安裝」。
安裝擴充功能後，活動列中會顯示「Looker」圖示。

設定擴充功能

如要使用 Looker 執行個體詳細資料設定擴充功能，請執行互動式新手上路導覽：

開啟工作區，然後開啟指令面板 (macOS 上為 Command-Shift-P，Windows/Linux 上為 Ctrl+Shift+P)。
執行「Looker: Show Onboarding Walkthrough」(Looker：顯示新手上路導覽) 指令，開啟新手上路導覽。
按照導覽中的提示，輸入 Looker 執行個體網址、專案 ID 和驗證詳細資料。如果您使用裸露存放區，系統也會在過程中提示您填入專案的 LookML 檔案。

使用 OAuth 進行驗證 (建議)

建議使用 OAuth 2.1 驗證流程。在新手上路導覽期間，系統會提示您選擇 OAuth，請選擇 OAuth 並提供下列設定值：

Looker 執行個體網址：Looker 執行個體的網址。
OAuth 用戶端 ID：Looker 管理員提供的 OAuth 用戶端 ID (client_guid)。
專案 ID：要編輯的 LookML 專案名稱。如要尋找，請在 Looker 執行個體中開啟「LookML 專案」頁面。專案 ID 位於「專案」欄中。

使用 API 憑證驗證

如要使用 Looker API 金鑰，請按照說明文件建立 API 憑證。在新手上路導覽期間，系統會提示您選擇 API 憑證，請提供下列設定值：

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

設定

雖然建議使用新手上路導覽，您也可以在 VS Code settings.json 檔案中設定擴充功能設定。這個檔案位於工作區 .vscode 資料夾 (.vscode/settings.json) 或全域使用者設定檔 (settings.json)。您也可以使用 VS Code 設定編輯器 (「偏好設定：開啟設定 (使用者介面)」) 設定這些檔案。

所有 looker.<setting> 屬性都必須在 VS Code settings.json 檔案中定義，包括擴充功能 MCP 設定 looker.mcpServerUrl。在 AI 代理程式的 MCP 設定檔 (例如 .agents/mcp_config.json) 或其他設定檔中定義這些設定，將無法搭配擴充功能使用。

您可以在 settings.json 中設定下列擴充功能設定：

設定	說明	預設
`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`	LookML 專案 ID。	-
`looker.mcpServerUrl`	擴充功能本機 MCP Proxy 會將要求轉送至目標 MCP 伺服器的網址。只有在與 `looker.instanceURL/mcp` 不同時才設定 (例如 `http://localhost:5000/mcp`)。	`looker.instanceURL/mcp`
`looker.acceptSelfSignedCertificates`	忽略 SSL 憑證錯誤 (例如自行簽署的憑證)。警告：不建議啟用這個選項。	`false`
`looker.askBeforeOverwritingRemote`	偵測到衝突時，一律先詢問是否要覆寫遠端檔案。	`false`

設定 MCP 用戶端

如要讓 AI 代理程式透過擴充功能與 Looker 互動，請將代理程式設定為連線至擴充功能的本機 MCP Proxy (位於 http://127.0.0.1:5050/mcp)。

AI 代理會參照自己的 MCP 設定檔 (例如 VS Code 中的 .agents/mcp_config.json、Claude Code 中的 .mcp.json 或 Cursor 中的 .cursor/mcp.json)。將這項設定指向本機 Proxy，可讓擴充功能擷取代理的 MCP 要求，並使用適當的驗證標頭轉送要求。

Looker 管理的 MCP 伺服器 (預設和建議)

擴充功能會執行本機反向 Proxy (預設：http://127.0.0.1:5050/mcp)，連線至 Looker 的內建代管 MCP 伺服器 (LOOKER_INSTANCE_URL/mcp)。Proxy 會自動插入 OAuth 持有者權杖，並緩衝處理 AI 代理程式工具要求，直到待處理的本機檔案同步完成為止，確保驗證工具不會評估伺服器上的過時程式碼。

自訂或自行託管的 MCP 伺服器 (選用)

如果貴機構代管自訂 MCP 伺服器 (例如獨立的 MCP Toolbox for Databases)：

在 VS Code 設定中，將 looker.mcpServerUrl 設為自訂伺服器網址 (例如 http://localhost:5000/mcp)。
將 IDE 的 MCP 用戶端設為指向 http://127.0.0.1:5050/mcp 的擴充功能 Proxy。

Visual Studio Code (Copilot)

開啟 VS Code，並在專案根目錄中建立 .agents 目錄 (如果尚未建立)。
建立 .agents/mcp_config.json 檔案 (如果還沒有的話)，然後開啟該檔案。
新增下列設定並儲存檔案：

      {
        "mcpServers": {
          "Looker": {
            "serverUrl": "http://127.0.0.1:5050/mcp",
            "disabledTools": [
              "query_url",
              "get_looks",
              "run_look",
              "make_look",
              "get_dashboards",
              "run_dashboard",
              "make_dashboard",
              "add_dashboard_element",
              "add_dashboard_filter",
              "generate_embed_url",
              "health_pulse",
              "health_analyze",
              "health_vacuum",
              "get_project_files",
              "get_project_file",
              "create_project_file",
              "update_project_file",
              "delete_project_file",
              "get_project_directories",
              "create_project_directory",
              "delete_project_directory",
              "project_git_branch"
            ]
          }
        }
      }

Claude Code

如果專案根目錄中沒有 .mcp.json 檔案，請建立該檔案。
新增下列設定並儲存檔案：

      {
        "mcpServers": {
          "Looker": {
            "type": "http",
            "url": "http://127.0.0.1:5050/mcp"
          }
        }
      }

Cursor

如果專案根目錄中沒有 .cursor 目錄，請建立該目錄。
建立 .cursor/mcp.json 檔案 (如果還沒有的話)，然後開啟該檔案。
新增下列設定並儲存檔案：

      {
        "mcpServers": {
          "Looker": {
            "type": "http",
            "url": "http://127.0.0.1:5050/mcp"
          }
        }
      }

開啟「游標」，然後依序前往「設定」>「游標設定」>「MCP」。伺服器連線後，會顯示綠色的「有效」狀態。

Cline

在 VS Code 中開啟 Cline 擴充功能，然後按一下「MCP Servers」(MCP 伺服器) 圖示。
按一下「設定 MCP 伺服器」開啟設定檔。
新增下列設定並儲存檔案：

      {
        "mcpServers": {
          "Looker": {
            "type": "http",
            "url": "http://127.0.0.1:5050/mcp"
          }
        }
      }

滑浪風帆

開啟 Windsurf，然後前往 Cascade 助理。
按一下 MCP 圖示，然後點選「設定」開啟設定檔。
新增下列設定並儲存檔案：

      {
        "mcpServers": {
          "Looker": {
            "type": "http",
            "url": "http://127.0.0.1:5050/mcp"
          }
        }
      }

透過 Looker 驗證

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

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

填入本機 LookML 專案

如要開始開發，請使用適合存放區設定的方法，在本機 IDE 中開啟 LookML 專案：

Git 存放區

如果 LookML 專案已設定 Git，請按照下列步驟操作：

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

裸存放區模式

如果 LookML 專案設為裸存放區，請按照下列步驟操作：

開啟工作區後，為專案建立並開啟空白的本機資料夾。
開啟指令面板 (macOS 為 Command-Shift-P 鍵，Windows/Linux 為 Ctrl+Shift+P 鍵)。
執行「Looker: Show Onboarding Walkthrough」(Looker：顯示新手上路導覽) 指令，開啟新手上路導覽。
在「選取專案」步驟中，選取要使用的 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」(開發人員：重新載入視窗) 命令，可能有助於解決問題。