Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Guida introduttiva all'estensione Looker per VS Code

L'estensione Looker by Google Cloud per Visual Studio Code (VS Code) ti consente di sviluppare LookML direttamente nel tuo ambiente desktop locale. Fornisce un'evidenziazione della sintassi avanzata, la sincronizzazione bidirezionale dei file con l'istanza di Looker e l'integrazione con agenti di programmazione AI per il "vibe coding".

L'estensione è creata utilizzando il framework Visual Studio Code (VS Code) e supporta gli ambienti di sviluppo integrati (IDE) basati sull'IDE VS Code, come i seguenti IDE e strumenti di codifica:

Claude Code
Codex
Cursore
Kiro
VS Code
Windsurf
Zed

Gli IDE che non sono fork di VS Code, come IntelliJ ed Eclipse, non sono supportati dall'estensione Looker per VS Code.

Questa guida spiega come configurare e autenticare l'estensione.

Workflow abilitato all'AI

L'estensione Looker per VS Code fa parte di un flusso di lavoro di sviluppo agentico basato sull'AI per la modifica e la creazione di file LookML. Per attivare questo flusso di lavoro, configura i seguenti strumenti:

Un IDE locale basato su VS Code. L'IDE deve contenere un agente AI integrato (ad esempio, Cursor) oppure, se non contiene un agente AI integrato, deve essere integrato con uno strumento agentico autonomo (come Gemini CLI o Claude Code). Consulta la documentazione del tuo IDE locale per scoprire come connetterlo a un agente.
L'estensione Looker per VS Code.
Un server MCP, ad esempio il server MCP gestito da Looker.

Per saperne di più sul workflow reso possibile dall'AI, consulta la pagina di documentazione Sviluppo assistito dall'AI (vibe coding) con Looker.

Prima di iniziare

Prima di installare l'estensione, devi soddisfare i seguenti requisiti:

Server MCP gestito da Looker (facoltativo, ma consigliato): se prevedi di utilizzare lo sviluppo assistito dall'AI, connetti il tuo IDE e il tuo agente AI al server MCP gestito da Looker. Le istruzioni per configurare il server MCP sono disponibili nella pagina della documentazione relativa al server MCP gestito da Looker. Per ulteriori dettagli, consulta la documentazione degli strumenti.
Autorizzazioni Looker: devi disporre dell'autorizzazione Looker develop per tutti i modelli che vuoi modificare.
Istanza di Looker: la tua istanza deve eseguire Looker 26.6 o versioni successive.
Configurazione del progetto: devi avere un progetto in Looker (configurato come repository bare o configurato per Git).
Installazione di Git (facoltativa): se prevedi di clonare il repository LookML, devi aver installato Git sulla tua macchina locale.
ID client OAuth: se utilizzi l'autenticazione OAuth (opzione consigliata), devi ottenere un ID client OAuth dall'amministratore di Looker.

Configurazione amministratore

Se la tua organizzazione utilizza OAuth per l'autenticazione, un amministratore di Looker deve registrare l'estensione Looker per VS Code come client OAuth nell'interfaccia utente di amministrazione di Looker.

Utilizza Explorer API di Looker per configurare l'integrazione OAuth. Puoi accedere a Explorer API utilizzando uno dei seguenti metodi:

Explorer API installato

Se la tua istanza di Looker ha già installato l'API Explorer, puoi accedervi con questo formato URL:

LOOKER_INSTANCE_URL/extensions/marketplace_extension_api_explorer::api-explorer/

Explorer API non installato

Se la tua istanza Looker non dispone di API Explorer, puoi installarlo da Looker Marketplace. Consulta la pagina Utilizzo di Explorer API per informazioni su come installare Explorer API.

Istanza privata PSA

Se utilizzi un'istanza di connessioni private di Looker (Google Cloud core) che utilizza l'accesso privato ai servizi, Looker Marketplace ed Explorer API non sono supportati. Per registrare un agente AI, devi chiamare direttamente l'endpoint API oauth_client_apps. Se utilizzi questo metodo, puoi saltare i passaggi rimanenti di questa procedura di Explorer API.

Di seguito è riportato un esempio di comando curl che puoi utilizzare con l'endpoint oauth_client_apps per registrare l'agente.

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

Per registrare l'estensione, completa i seguenti passaggi:

Segui le istruzioni riportate nella documentazione Registrazione di un'applicazione client OAuth per registrare l'estensione.
Per il campo client_guid, completa i seguenti passaggi:
- Utilizza un ID univoco globale.
- Prepara la distribuzione dell'ID a tutti gli sviluppatori LookML che vogliono utilizzare l'estensione.

Per redirect_uri, inserisci l'URL di callback per il tuo IDE. A seconda dell'IDE o dello strumento di codifica, utilizza uno dei seguenti URL di callback:

IDE o strumento	URL di callback
Antigravity IDE (disponibile in Looker 26.12 o versioni successive)	antigravity-ide://google.vscode-looker-official/oauth_callback
Code-OSS	code-oss://google.vscode-looker-official/oauth_callback
Cursore	cursor://google.vscode-looker-official/oauth_callback
HTTPS	https://google.vscode-looker-official/oauth_callback
Kiro (il supporto OAuth per Kiro è disponibile in Looker 26.16 o versioni successive)	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

Assicurati che il campo Attivato sia impostato su true.
Compila i campi display_name e description come descritto nella documentazione Registrazione di un'applicazione client OAuth.

Una volta registrata l'app, Explorer API restituirà una risposta con un riepilogo della registrazione. Assicurati che l'URI di reindirizzamento corrisponda a quello inserito nel parametro della richiesta. Puoi utilizzare l'endpoint Get OAuth Client App con il valore client_guid per esaminare i dettagli della registrazione.

Fornisci il valore client_guid generato agli sviluppatori, che lo utilizzeranno durante la configurazione dell'estensione.

Installare l'estensione

L'estensione è disponibile in entrambi i principali marketplace di estensioni:

Visual Studio Marketplace (per VS Code standard)
Open VSX Registry (per Cursor, Antigravity IDE e VSCodium)

Per installare l'estensione, completa i seguenti passaggi:

Apri l'IDE, ad esempio VS Code o Cursor.
Fai clic sull'icona Estensioni nella barra delle attività.
Trova Looker by Google Cloud e fai clic su Installa.
Una volta installata l'estensione, nella barra delle attività viene visualizzata l'icona Looker.

Configurare l'estensione

Per configurare l'estensione con i dettagli dell'istanza di Looker, esegui la procedura dettagliata di onboarding interattiva:

Con uno spazio di lavoro aperto, apri il riquadro dei comandi (Cmd+Shift+P su macOS o Ctrl+Shift+P su Windows/Linux).
Esegui il comando Looker: Show Onboarding Walkthrough per aprire la procedura dettagliata di onboarding.
Segui le istruzioni nella procedura dettagliata per inserire l'URL dell'istanza di Looker, l'ID progetto e i dettagli di autenticazione. Se utilizzi un repository bare, ti verrà chiesto anche di compilare il tuo spazio di lavoro con i file LookML del progetto durante questa procedura.

Eseguire l'autenticazione con OAuth (consigliato)

OAuth 2.1 è il flusso di autenticazione consigliato. Quando ti viene chiesto durante la procedura dettagliata di onboarding, scegli OAuth e fornisci i seguenti valori di configurazione:

URL istanza Looker: l'URL della tua istanza di Looker.
ID client OAuth: l'ID client OAuth (client_guid) che ricevi dall'amministratore di Looker.
ID progetto: il nome del progetto LookML che vuoi modificare. Per trovarlo, all'interno dell'istanza di Looker, apri la pagina Progetti LookML. L'ID progetto si trova nella colonna Progetto.

Autenticarsi con le credenziali API

Se preferisci utilizzare le chiavi API Looker, segui la documentazione per creare le credenziali API. Quando ti viene richiesto durante la procedura dettagliata di onboarding, scegli le credenziali API e fornisci i seguenti valori di configurazione:

URL istanza Looker: l'URL della tua istanza Looker.
ID client e client secret: l'ID client e il client secret per le credenziali API che stai utilizzando per l'autenticazione. Per trovare queste credenziali, apri la pagina Account all'interno dell'istanza di Looker, poi, nella sezione Chiavi API, fai clic sul pulsante Gestisci per visualizzare gli ID client e i secret.
ID progetto: il nome del progetto che vuoi modificare. Per trovare il nome del progetto, nella tua istanza di Looker, apri la pagina Progetti LookML. L'ID progetto si trova nella colonna Progetto.

Impostazioni

Sebbene sia consigliabile utilizzare la procedura dettagliata di onboarding, puoi anche configurare le impostazioni dell'estensione nel file settings.json di VS Code. Questo file si trova nella cartella .vscode dello spazio di lavoro (.vscode/settings.json) o nel file delle impostazioni utente globali (settings.json). Puoi anche configurarle utilizzando l'editor visivo delle impostazioni di VS Code (Preferenze: Apri Impostazioni (UI)).

Tutte le proprietà looker.<setting> devono essere definite nei file settings.json di VS Code, inclusa l'impostazione dell'estensione MCP looker.mcpServerUrl. La definizione di queste impostazioni in un file di configurazione MCP di un agente AI (ad esempio .agents/mcp_config.json) o in altri file di impostazioni non funzionerà con l'estensione.

Puoi configurare le seguenti impostazioni dell'estensione in settings.json:

Impostazione	Descrizione	Predefinito
`looker.instanceURL`	URL di base dell'istanza di Looker (ad esempio, `https://mycompany.looker.com`).	-
`looker.authURL`	URL da utilizzare per l'autenticazione OAuth. Imposta solo se diverso dall'URL dell'istanza.	`looker.instanceURL`
`looker.sdkURL`	URL da utilizzare per le richieste API. Imposta solo se diverso dall'URL dell'istanza.	`looker.instanceURL`
`looker.oauthClientId`	ID client OAuth di Looker. Obbligatorio per OAuth.	-
`looker.clientId`	ID client API Looker. Obbligatorio per l'autenticazione con chiave API.	-
`looker.clientSecret`	Client secret dell'API Looker. Deprecato. Utilizza la procedura dettagliata di onboarding per configurare le credenziali API.	-
`looker.projectId`	ID progetto LookML.	-
`looker.mcpServerUrl`	URL del server MCP di destinazione a cui il proxy MCP locale dell'estensione inoltra le richieste. Impostato solo se diverso da `looker.instanceURL/mcp` (ad esempio, `http://localhost:5000/mcp`).	`looker.instanceURL/mcp`
`looker.acceptSelfSignedCertificates`	Ignora gli errori del certificato SSL (ad esempio, per i certificati autofirmati). Avviso: l'attivazione di questa opzione non è consigliata.	`false`
`looker.askBeforeOverwritingRemote`	Chiedi sempre prima di sovrascrivere i file remoti quando viene rilevato un conflitto.	`false`

Configura il client MCP

Per consentire all'agente AI di interagire con Looker tramite l'estensione, devi configurare l'agente in modo che si connetta al proxy MCP locale dell'estensione all'indirizzo http://127.0.0.1:5050/mcp.

Il tuo agente AI fa riferimento al proprio file di configurazione MCP (ad esempio .agents/mcp_config.json in VS Code, .mcp.json in Claude Code o .cursor/mcp.json in Cursor). Se punti questa configurazione al proxy locale, l'estensione può acquisire le richieste MCP dell'agente e inoltrarle con le intestazioni di autenticazione appropriate.

Server MCP gestito da Looker (impostazione predefinita e consigliata)

L'estensione esegue un proxy inverso locale (impostazione predefinita: http://127.0.0.1:5050/mcp) che si connette al server MCP gestito integrato di Looker (LOOKER_INSTANCE_URL/mcp). Il proxy inserisce automaticamente i token di autenticazione OAuth e memorizza nel buffer le richieste di strumenti dell'agente AI finché non vengono completate le sincronizzazioni dei file locali in attesa, garantendo che gli strumenti di convalida non valutino mai codice obsoleto sul server.

Server MCP personalizzato o self-hosted (facoltativo)

Se la tua organizzazione ospita un server MCP personalizzato (ad esempio MCP Toolbox for Databases autonomo):

Nelle impostazioni di VS Code, imposta looker.mcpServerUrl sull'URL del server personalizzato (ad esempio, http://localhost:5000/mcp).
Configura il client MCP dell'IDE in modo che punti al proxy dell'estensione all'indirizzo http://127.0.0.1:5050/mcp.

Visual Studio Code (Copilot)

Apri VS Code e crea la directory .agents nella radice del progetto, se non esiste già.
Crea il file .agents/mcp_config.json, se non esiste già, e aprilo.
Aggiungi la seguente configurazione e salva il file:

      {
        "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

Crea il file .mcp.json nella root del progetto, se non esiste già.
Aggiungi la seguente configurazione e salva il file:

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

Cursore

Crea la directory .cursor nella directory principale del progetto, se non esiste già.
Crea il file .cursor/mcp.json, se non esiste già, e aprilo.
Aggiungi la seguente configurazione e salva il file:

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

Apri Cursore e vai a Impostazioni > Impostazioni cursore > MCP. Quando il server si connette, viene visualizzato uno stato attivo verde.

Cline

Apri l'estensione Cline in VS Code e fai clic sull'icona MCP Servers.
Fai clic su Configura server MCP per aprire il file di configurazione.
Aggiungi la seguente configurazione e salva il file:

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

Windsurf

Apri Windsurf e vai all'assistente Cascade.
Fai clic sull'icona MCP e poi su Configura per aprire il file di configurazione.
Aggiungi la seguente configurazione e salva il file:

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

Autenticarsi tramite Looker

Se utilizzi l'autenticazione OAuth, devi accedere per collegare il tuo IDE locale al tuo account Looker.

Apri la tavolozza dei comandi.
Esegui il comando Looker: Sign In (OAuth).
Accetta il prompt per aprire il browser.
Nel browser, autorizza l'estensione ad accedere al tuo account Looker.
Dopo l'autorizzazione, il browser reindirizza nuovamente all'IDE. Dovresti visualizzare una notifica che indica Accesso a Looker riuscito.

Compila il progetto LookML locale

Per iniziare lo sviluppo, apri il progetto LookML nel tuo IDE locale utilizzando il metodo appropriato per la configurazione del repository:

Repository Git

Se il tuo progetto LookML è configurato per Git, segui questi passaggi:

In VS Code, apri una nuova finestra.
Apri la tavolozza dei comandi e seleziona Git: Clone.
Inserisci l'URL del repository Git remoto (ad esempio, da GitHub o GitLab) e scegli una cartella locale.
Apri la cartella clonata nell'IDE.

Modalità repository bare

Se il tuo progetto LookML è configurato come repository bare, segui questi passaggi:

Con un workspace aperto, crea e apri una cartella locale vuota per il tuo progetto.
Apri il riquadro dei comandi (Cmd+Shift+P su macOS o Ctrl+Shift+P su Windows/Linux).
Esegui il comando Looker: Show Onboarding Walkthrough per aprire la procedura dettagliata di onboarding.
Nel passaggio Seleziona progetto, seleziona il progetto LookML su cui vuoi lavorare e fai clic su Avanti.
L'estensione riconosce che la cartella locale è vuota e ti chiede di compilare lo spazio di lavoro con i file del progetto. Fai clic su Popola workspace per popolare lo spazio di lavoro.
Completa la procedura dettagliata di onboarding.

Una volta compilato lo spazio di lavoro, l'estensione inizia automaticamente a sincronizzare la cartella locale con il ramo estratto nella modalità di sviluppo dell'istanza di Looker.

Risoluzione dei problemi

Puoi visualizzare i log delle estensioni nel riquadro Output dell'IDE. Seleziona il canale Looker per visualizzare i log. Per log più dettagliati, apri la tavolozza dei comandi, esegui il comando Sviluppatore: imposta livello log e seleziona Debug o Trace.

Errori di autenticazione: verifica che looker.instanceURL e looker.oauthClientId siano corretti. Assicurati che l'URI di reindirizzamento in Looker corrisponda esattamente.
Problemi di sincronizzazione: controlla i log delle estensioni per risolvere i problemi di sincronizzazione. Per visualizzare i log, apri il riquadro Output e seleziona Looker dal menu a discesa.
Risposta Richiesta errata durante OAuth: assicurati che la tua istanza di Looker sia accessibile dalla tua rete locale e di disporre di una connessione a internet valida.

Se riscontri problemi con l'estensione, l'esecuzione del comando Sviluppatore: ricarica finestra dalla tavolozza dei comandi può aiutarti a risolverli.