Primeiros passos com a extensão do Looker para VS Code

A extensão do Looker para VS Code permite desenvolver o LookML diretamente no ambiente de trabalho local. Ela oferece destaque de sintaxe avançado, sincronização bidirecional de arquivos com a instância do Looker e integração com agentes de programação de IA para "programação de vibe".

A extensão é criada usando o framework do Visual Studio Code (VS Code) e oferece suporte a ambientes de desenvolvimento integrado (IDEs) baseados no VS Code, como os seguintes IDEs e ferramentas de programação:

Claude Code
Codex
Cursor
Kiro
VS Code
Windsurf
Zed

Os IDEs que não são ramificações do VS Code, como IntelliJ e Eclipse, não são compatíveis com a extensão do Looker para VS Code.

Este guia aborda como configurar e autenticar a extensão.

Fluxo de trabalho com tecnologia de IA

A extensão do Looker para VS Code faz parte de um fluxo de trabalho de desenvolvimento de agentes com tecnologia de IA para editar e criar arquivos LookML. Para ativar esse fluxo de trabalho, configure as seguintes ferramentas:

A extensão do Looker para VS Code.
Um ambiente de desenvolvimento integrado local baseado no VS Code. O ambiente de desenvolvimento integrado precisa conter um agente de IA integrado (por exemplo, Cursor) ou, se não contiver um agente de IA integrado (como o VS Code básico), o ambiente de desenvolvimento integrado precisa ser integrado a uma ferramenta de agente independente (como a CLI do Gemini ou o Claude Code). Consulte a documentação do ambiente de desenvolvimento integrado local para saber como conectar o ambiente de desenvolvimento integrado a um agente.
Um servidor MCP, como o MCP Toolbox for Databases.

Para saber mais sobre o fluxo de trabalho com tecnologia de IA, consulte a página de documentação Desenvolvimento assistido por IA (programação de vibe) com o Looker.

Antes de começar

Antes de instalar a extensão, você precisa atender aos seguintes requisitos:

Conectar-se a ferramentas de IA: se você planeja usar o desenvolvimento assistido por IA, conecte seu ambiente de desenvolvimento integrado e seu agente de IA ao MCP Toolbox for Databases. Por exemplo, uma configuração de amostra para conectar o MCP Toolbox à CLI do Gemini aparece na documentação Usar o Looker com o MCP, a CLI do Gemini e outros agentes. Consulte a documentação das ferramentas para mais detalhes.
Permissões do Looker: você precisa ter a permissão develop do Looker para todos os modelos que quiser editar.
Instância do Looker: a instância precisa executar o Looker 26.6 ou uma versão mais recente.
Instalação do Git: você precisa ter o Git instalado na sua máquina local para clonar e gerenciar o repositório do LookML.
Configuração do projeto: o projeto do LookML precisa ser configurado para o Git.
ID do cliente OAuth: se você estiver usando a autenticação OAuth (recomendada), será necessário receber um ID do cliente OAuth do administrador do Looker.

Configuração do Administrador

Se a organização usa o OAuth para autenticação, um administrador do Looker precisa registrar a extensão do Looker para VS Code como um cliente OAuth na interface do administrador do Looker.

Use o API Explorer do Looker para configurar a integração do OAuth. Você pode acessar o API Explorer usando um dos seguintes métodos:

Se a instância do Looker já tiver o API Explorer instalado, você poderá acessá-lo com este formato de URL:
```
https://LOOKER_INSTANCE_URL/extensions/marketplace_extension_api_explorer::api-explorer/
```
Se a instância do Looker não tiver o API Explorer, você poderá instalá-lo no Marketplace do Looker. Consulte a página Usar o API Explorer para mais informações.

Para registrar a extensão, siga estas etapas:

Siga as instruções na documentação Registrar um aplicativo cliente OAuth para registrar a extensão.
Para o campo client_guid, siga estas etapas:
- Use qualquer ID globalmente exclusivo.
- Prepare-se para distribuir o ID para todos os desenvolvedores do LookML que quiserem usar a extensão.

Para redirect_uri, use:

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

Preencha display_name e description conforme descrito na documentação Registrar um aplicativo cliente OAuth.

Depois que o app for registrado, o API Explorer vai retornar uma resposta com um resumo do registro. Você pode usar o endpoint Get OAuth Client App com o client_guid para revisar os detalhes do registro.

Forneça o client_guid gerado aos desenvolvedores. Eles vão usá-lo ao configurar a extensão.

Instalar a extensão

Siga estas etapas para instalar a extensão:

Instale a extensão do Looker para VS Code no Visual Studio Marketplace.
Abra o ambiente de desenvolvimento integrado, como VS Code ou Cursor.
Clique no ícone Extensões na barra de atividades.
Encontre a extensão do Looker para VS Code e clique em Instalar.
Depois que a extensão for instalada, o ícone Looker vai aparecer na barra de atividades.

Configurar a extensão

É necessário configurar a extensão com os detalhes da instância do Looker no arquivo settings.json do espaço de trabalho.

Com um espaço de trabalho aberto, abra a Paleta de comandos (Command-Shift-P no Mac ou Ctrl+Shift+P no Windows/Linux).
Pesquise e selecione Preferências: abrir configurações do espaço de trabalho (JSON).
Adicione as variáveis de configuração às suas configurações. As variáveis de configuração vão variar dependendo se o método de autenticação é OAuth ou credenciais de API.

Autenticar com OAuth (recomendado)

O OAuth 2.1 é o fluxo de autenticação recomendado. Cole essas configurações no arquivo settings.json do espaço de trabalho.

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

Substitua:

https://YOUR_INSTANCE_URL: o URL da instância do Looker.
YOUR_OAUTH_CLIENT_ID: o ID do cliente OAuth (client_guid) que você recebe do administrador do Looker.
YOUR_PROJECT_ID: o nome do projeto que você quer editar. Para encontrá-lo, na instância do Looker, abra a página Projetos do LookML. O ID do projeto está na coluna Projeto.

Autenticar com credenciais de API

Se preferir usar chaves de API Looker, siga a documentação para criar credenciais de API. Você também precisa fornecer o ID do projeto.

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

Substitua:

https://YOUR_INSTANCE_URL: o URL da instância do Looker.
YOUR_CLIENT_ID e YOUR_CLIENT_SECRET: o ID e a chave secreta do cliente para as credenciais de API que você está usando para autenticar. Para encontrar essas credenciais, na instância do Looker, abra a página Conta e, na seção Chaves de API, clique no botão Gerenciar. Isso abre a página Chaves de API , em que é possível conferir os IDs e as chaves secretas do cliente.
YOUR_PROJECT_ID: o nome do projeto que você quer editar. Para encontrar o nome do projeto, na instância do Looker, abra a página Projetos do LookML. O ID do projeto está na coluna Projeto.

Configurações

É possível configurar as seguintes configurações do MCP no espaço de trabalho do ambiente de desenvolvimento integrado.

Configuração	Descrição	Padrão
`looker.instanceURL`	URL de base da instância do Looker (por exemplo, `https://mycompany.looker.com`).	-
`looker.authURL`	URL a ser usado para autenticação OAuth. Defina apenas se for diferente do URL da instância.	`looker.instanceURL`
`looker.sdkURL`	URL a ser usado para solicitações de API. Defina apenas se for diferente do URL da instância.	`looker.instanceURL`
`looker.oauthClientId`	ID do cliente OAuth do Looker. Obrigatório para o OAuth.	-
`looker.clientId`	ID do cliente da API Looker. Obrigatório para a autenticação da chave de API.	-
`looker.clientSecret`	Chave secreta do cliente da API Looker. Obrigatório para a autenticação da chave de API.	-
`looker.projectId`	ID do projeto do Looker.	-
`looker.mcpServerUrl`	URL do servidor MCP externo para proxy (por exemplo, `http://localhost:5000/mcp`).	-
`looker.acceptSelfSignedCertificates`	Ignorar erros de certificado SSL (por exemplo, para certificados autoassinados). Aviso: não é recomendável ativar essa opção.	`false`
`looker.askBeforeOverwritingRemote`	Sempre perguntar antes de substituir arquivos remotos quando um conflito for detectado.	`false`

Autenticar pelo Looker

Se você estiver usando a autenticação OAuth, será necessário fazer login para vincular o ambiente de desenvolvimento integrado local à sua conta do Looker.

Abra a Paleta de comandos.
Execute o comando: Looker: fazer login (OAuth).
Confirme o prompt para abrir o navegador.
No navegador, autorize a extensão a acessar sua conta do Looker.
Após a autorização, o navegador será redirecionado de volta ao ambiente de desenvolvimento integrado. Você vai receber uma notificação informando Login feito no Looker.

Clonar o projeto do LookML

Para começar o desenvolvimento, é necessário clonar o repositório do LookML na sua máquina local.

No VS Code, abra uma nova janela.
Abra a Paleta de comandos e selecione Git: clonar.
Insira o URL do repositório Git remoto (por exemplo, do GitHub ou GitLab) e escolha uma pasta local.
Abra a pasta clonada no ambiente de desenvolvimento integrado.

A extensão detecta automaticamente os arquivos do LookML e começa a sincronizar com a ramificação extraída no Modo de Desenvolvimento da instância do Looker.

Solução de problemas

É possível conferir os registros de extensão no painel Saída do ambiente de desenvolvimento integrado. Selecione o canal Looker para conferir os registros. Para registros mais detalhados, abra a Paleta de comandos, execute o comando Desenvolvedor: definir nível de registro e selecione Depurar ou Rastrear.

Erros de autenticação: verifique se looker.instanceUrl e looker.oauthClientId estão corretos. Confira se o URI de redirecionamento no Looker corresponde exatamente.
Problemas de sincronização: confira os registros de extensão para resolver problemas de sincronização. Para conferir os registros, abra o painel Saída e selecione Looker no menu suspenso.
Resposta de solicitação inválida durante o OAuth: verifique se a instância do Looker está acessível na rede local e se você tem uma conexão de Internet válida.

Se você encontrar problemas com a extensão, executar o comando Desenvolvedor: recarregar janela na Paleta de comandos poderá ajudar a resolvê-los.