VS Code Looker 扩展程序使用入门

借助 Looker 扩展程序（适用于 VS Code），您可以直接在本地桌面环境中开发 LookML。它提供丰富的语法突出显示、与 Looker 实例的双向文件同步，以及与 AI 编码智能体的集成，以实现“氛围编程 (vibe coding)”。

该扩展程序是使用 Visual Studio Code (VS Code) 框架构建的，并且支持基于 VS Code IDE 的集成开发环境 (IDE)，例如以下 IDE 和编码工具：

  • Claude Code
  • Codex
  • 光标
  • Kiro
  • VS Code
  • Windsurf
  • Zed

Looker 扩展程序（适用于 VS Code）不支持并非 VS Code 分支的 IDE，例如 IntelliJ 和 Eclipse。

本指南介绍了如何设置扩展程序并对其进行身份验证。

AI 赋能的工作流

Looker 扩展程序（适用于 VS Code）是用于修改和创建 LookML 文件的 AI 赋能的智能体开发工作流的一部分。如需启用此工作流，请配置以下工具：

  • Looker 扩展程序（适用于 VS Code） 。
  • 基于 VS Code 的本地 IDE 。该 IDE 必须包含内置 AI 智能体 （例如 Cursor），或者，如果该 IDE 不包含内置 AI 智能体（例如基本 VS Code），则该 IDE 必须与独立智能体工具 （例如 Gemini CLI 或 Claude Code）集成。如需了解如何将 IDE 连接到智能体，请参阅本地 IDE 的文档。
  • 一个 MCP 服务器 ，例如 Looker 管理的 MCP 服务器。

如需详细了解依托 AI (技术) 的工作流，请参阅使用 Looker 进行 AI 辅助开发（氛围编程 (vibe coding)）文档页面。

准备工作

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

  • 连接到 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 管理界面中将 Looker 扩展程序（适用于 VS Code）注册为 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 Explorer，您可以从 Looker Marketplace 安装它。如需了解如何安装 API Explorer，请参阅使用 API Explorer页面。

PSA 专用实例

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

以下是可与 oauth_client_apps 端点搭配使用的 curl 命令示例，用于注册智能体。

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 Explorer 将返回包含注册摘要的响应。您可以使用 Get OAuth Client App 端点和 client_guid 查看注册详细信息。

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

安装扩展程序

如需安装扩展程序，请完成以下步骤：

  1. 从 Visual Studio Marketplace 安装 Looker 扩展程序（适用于 VS Code）。
  2. 打开 IDE，例如 VS Code 或 Cursor。
  3. 点击活动栏中的扩展程序 图标。
  4. 找到 Looker 扩展程序（适用于 VS Code） ，然后点击安装 。
  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 要代理的外部 MCP 服务器的网址（例如 http://localhost:5000/mcp）。 -
looker.acceptSelfSignedCertificates 忽略 SSL 证书错误（例如，对于自签名证书）。警告：不建议启用此选项。 false
looker.askBeforeOverwritingRemote 检测到冲突时，始终先询问是否覆盖远程文件。 false

通过 Looker 进行身份验证

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

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

克隆 LookML 项目

如需开始开发，您必须将 LookML 代码库克隆到本地机器。

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

该扩展程序会自动检测 LookML 文件，并开始与 Looker 实例的开发模式中的检出分支同步。

问题排查

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

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

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

后续步骤