Google 会使用 AI 技术将内容翻译成您偏好的语言。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
光标
Kiro
VS Code
Windsurf
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 辅助开发（氛围编程 (vibe coding)）文档页面。

准备工作

在安装扩展程序之前，您必须满足以下要求：

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。

Admin 设置

如果您的组织使用 OAuth 进行身份验证，Looker 管理员必须在 Looker 管理界面中将 Looker 扩展程序注册为 VS Code 的 OAuth 客户端。

使用 Looker API Explorer 设置 OAuth 集成。您可以使用以下方法之一访问 API Explorer：

已安装 API Explorer

如果您的 Looker 实例已安装 API 探索器，您可以使用以下网址格式访问它：

LOOKER_INSTANCE_URL/extensions/marketplace_extension_api_explorer::api-explorer/

未安装 API Explorer

如果您的 Looker 实例没有 API Explorer，您可以从 Looker Marketplace 安装它。如需了解如何安装 API Explorer，请参阅使用 API Explorer 页面。

PSA 专用实例

如果您使用的是采用专用服务访问通道的 Looker (Google Cloud Core) 私密连接实例，则不支持 Looker Marketplace 和 API Explorer。如需注册 AI 智能体，您必须直接调用 oauth_client_apps API 端点。如果您使用此方法，则可以跳过此 API Explorer 程序的其余步骤。

以下示例展示了如何使用 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://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	windsurf://google.vscode-looker-official/oauth_callback

确保将已启用字段设置为 true。
按照注册 OAuth 客户端应用文档中的说明填写 display_name 和 description 字段。

应用注册后，API Explorer 将返回包含注册摘要的响应。确保重定向 URI 与您在请求参数中输入的内容一致。您可以使用 client_guid 值的 Get OAuth Client App 端点来查看注册详细信息。

向开发者提供生成的 client_guid 值；他们将在配置扩展程序时使用该值。

安装扩展程序

该扩展程序已在两个主要的扩展程序市场中发布：

Visual Studio Marketplace（适用于标准 VS Code）
Open VSX Registry（适用于 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 实例网址、项目 ID 和身份验证详细信息。如果您使用的是裸代码库，系统还会在此过程中提示您使用项目的 LookML 文件填充工作区。

使用 OAuth 进行身份验证（推荐）

建议使用 OAuth 2.1 身份验证流程。在初始配置向导中收到提示时，选择 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 设置编辑器（偏好设置：打开设置 (UI)）来配置这些设置。

所有 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 代理将请求转发到的目标 MCP 服务器的网址。仅当与 `looker.instanceURL/mcp` 不同时（例如 `http://localhost:5000/mcp`）才应设置。	`looker.instanceURL/mcp`
`looker.acceptSelfSignedCertificates`	忽略 SSL 证书错误（例如，对于自签名证书）。警告：不建议启用此选项。	`false`
`looker.askBeforeOverwritingRemote`	检测到冲突时，始终先询问是否覆盖远程文件。	`false`

配置 MCP 客户端

如需让 AI 智能体通过扩展程序与 Looker 进行交互，您必须将智能体配置为连接到扩展程序的本地 MCP 代理 (http://127.0.0.1:5050/mcp)。

AI 智能体引用自己的 MCP 配置文件（例如 VS Code 中的 .agents/mcp_config.json、Claude Code 中的 .mcp.json 或 Cursor 中的 .cursor/mcp.json）。将此配置指向本地代理可让扩展程序捕获代理的 MCP 请求，并使用相应的身份验证标头转发这些请求。

Looker 管理的 MCP 服务器（默认且推荐）

该扩展程序会运行一个本地反向代理（默认：http://127.0.0.1:5050/mcp），该代理会连接到 Looker 的内置托管 MCP 服务器 (LOOKER_INSTANCE_URL/mcp)。该代理会自动注入 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 的扩展代理。

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/mcp.json 文件（如果尚不存在），并打开该文件。
添加以下配置并保存文件：

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

打开 Cursor，然后依次前往设置 > Cursor 设置 > MCP。服务器连接时，系统会显示绿色的活跃状态。

Cline

在 VS Code 中打开 Cline 扩展程序，然后点击 MCP 服务器图标。
点击配置 MCP 服务器以打开配置文件。
添加以下配置并保存文件：

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

Windsurf

打开 Windsurf 并前往 Cascade 助理。
点击 MCP 图标，然后点击配置以打开配置文件。
添加以下配置并保存文件：

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

通过 Looker 进行身份验证

如果您使用的是 OAuth 身份验证，则必须登录才能将本地 IDE 关联到您的 Looker 账号。

打开命令面板。
运行命令：Looker：登录 (OAuth)。
确认提示以打开浏览器。
在浏览器中，授权该扩展程序访问您的 Looker 账号。
授权后，浏览器会重定向回您的 IDE。您应该会看到一条通知，告知您已成功登录 Looker！

填充本地 LookML 项目

如需开始开发，请使用适合您的代码库配置的方法在本地 IDE 中打开 LookML 项目：

Git 代码库

如果您的 LookML 项目已配置为使用 Git，请按以下步骤操作：

在 VS Code 中，打开一个新窗口。
打开命令面板，然后选择 Git：克隆。
输入远程 Git 代码库（例如 GitHub 或 GitLab）的网址，然后选择一个本地文件夹。
在 IDE 中打开已克隆的文件夹。

裸代码库模式

如果您的 LookML 项目配置为裸代码库，请按以下步骤操作：

在工作区处于打开状态时，为您的项目创建并打开一个空的本地文件夹。
打开命令面板（在 macOS 上按 Command-Shift-P，在 Windows/Linux 上按 Ctrl+Shift+P）。
运行 Looker: Show Onboarding Walkthrough 命令以打开新手入门演示。
在选择项目步骤中，选择要处理的 LookML 项目，然后点击下一步。
该扩展程序会识别出您的本地文件夹为空，并提示您使用项目的文件填充工作区。点击 Populate Workspace 以填充工作区。
完成初始配置演练。

工作区填充完毕后，扩展程序会自动开始将本地文件夹与 Looker 实例的开发模式中已签出的分支同步。

问题排查

您可以在 IDE 的输出面板中查看扩展程序日志。选择 Looker 渠道以查看日志。如需获取更详细的日志，请打开命令面板，运行 Developer: Set Log Level 命令，然后选择 Debug 或 Trace。

身份验证错误：验证您的 looker.instanceURL 和 looker.oauthClientId 是否正确。确保 Looker 中的重定向 URI 完全一致。
同步问题：检查扩展程序日志以解决同步问题。如需查看日志，请打开输出面板，然后从下拉菜单中选择 Looker。
OAuth 期间出现“错误请求”响应：确保您的 Looker 实例可从本地网络访问，并且您有有效的互联网连接。

如果您遇到扩展程序方面的问题，可以从命令面板运行 Developer: Reload Window 命令来解决这些问题。