Guida introduttiva all'estensione Looker per VS Code

L'estensione Looker per VS Code ti consente di sviluppare LookML direttamente all'interno del tuo ambiente desktop locale. Fornisce un'evidenziazione della sintassi avanzata, la sincronizzazione bidirezionale dei file con l'istanza di Looker e l'integrazione con gli 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 programmazione:

  • 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.

Flusso di lavoro basato sull'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 abilitare questo flusso di lavoro, configura i seguenti strumenti:

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

Per saperne di più sul flusso di lavoro basato sull'AI, consulta la pagina della documentazione Sviluppo assistito dall'AI (vibe coding) con Looker.

Prima di iniziare

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

  • Connetti agli strumenti AI: se prevedi di utilizzare lo sviluppo assistito dall'AI, connetti l'IDE e l'agente AI al server MCP gestito da Looker. La configurazione e un esempio di configurazione sono disponibili nella pagina della documentazione del server MCP gestito da Looker. Per ulteriori dettagli, consulta la documentazione degli strumenti.
  • Autorizzazioni Looker: devi disporre dell'autorizzazione develop di Looker per tutti i modelli che vuoi modificare.
  • Istanza di Looker: l'istanza deve eseguire Looker 26.6 o versioni successive.
  • Installazione di Git: devi aver installato Git sulla tua macchina locale per clonare e gestire il repository LookML.
  • Configurazione del progetto: il progetto LookML deve essere configurato per Git.
  • 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 l'Explorer API di Looker per configurare l'integrazione di OAuth. Puoi accedere all'Explorer API utilizzando uno dei seguenti metodi:

Explorer API installato

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

LOOKER_INSTANCE_URL/extensions/marketplace_extension_api_explorer::api-explorer/

Explorer API non installato

Se l'istanza di Looker non ha l'Explorer API, puoi installarlo da Looker Marketplace. Per informazioni su come installare l'Explorer API, consulta la pagina Utilizzo dell'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 e l'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 dell'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:

  1. Segui le istruzioni riportate nella documentazione Registrazione di un'applicazione client OAuth per registrare l'estensione.

  2. Per il campo client_guid:

    • Utilizza un ID univoco a livello globale.
    • Preparati a distribuire l'ID a tutti gli sviluppatori LookML che vogliono utilizzare l'estensione.

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

    IDE o strumento URL di callback
    VS Code 
    vscode://google.vscode-looker-official/oauth_callback
    Antigravity IDE (disponibile in Looker 26.12 e 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
    Looker 
    looker://google.vscode-looker-official/oauth_callback
    Windsurf 
    windsurf://google.vscode-looker-official/oauth_callback

  4. Completa display_name e description come descritto nella documentazione Registrazione di un'applicazione client OAuth.

Una volta registrata l'app, l'Explorer API restituirà una risposta con un riepilogo della registrazione. Puoi utilizzare l'endpoint Get OAuth Client App con client_guid per esaminare i dettagli della registrazione.

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

Installare l'estensione

Per installare l'estensione:

  1. Installa l'estensione Looker per VS Code da Visual Studio Marketplace.
  2. Apri l'IDE, ad esempio VS Code o Cursor.
  3. Fai clic sull'icona Estensioni nella barra delle attività.
  4. Trova l'estensione Looker per VS Code e fai clic su Installa.
  5. Una volta installata l'estensione, nella barra delle attività viene visualizzata l'icona Looker.

Configurare l'estensione

Puoi configurare l'estensione con i dettagli dell'istanza di Looker nel file settings.json dello spazio di lavoro, nell'editor visivo delle impostazioni di VS Code (Preferenze: apri impostazioni dello spazio di lavoro) o nell'interfaccia utente di onboarding interattiva dell'estensione Looker.

I passaggi seguenti mostrano come modificare il file settings.json come esempio. Se utilizzi l'editor delle impostazioni di VS Code o l'interfaccia utente dell'estensione Looker, otterrai lo stesso risultato.

  1. Con uno spazio di lavoro aperto, apri la tavolozza dei comandi (Comando-Shift-P su Mac o Ctrl+Shift+P su Windows/Linux).
  2. Cerca e seleziona Preferenze: apri impostazioni dello spazio di lavoro (JSON).
  3. Aggiungi le variabili di configurazione alle impostazioni. Le variabili di configurazione variano a seconda che il metodo di autenticazione sia OAuth o le credenziali API, come descritto nelle sezioni seguenti.

OAuth 2.1 è il flusso di autenticazione consigliato. Incolla queste impostazioni nel file settings.json dello spazio di lavoro.

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

Sostituisci quanto segue:

  • https://YOUR_INSTANCE_URL: l'URL dell'istanza di Looker.
  • YOUR_OAUTH_CLIENT_ID: l'ID client OAuth (client_guid) che ricevi dall'amministratore di Looker.
  • YOUR_PROJECT_ID: il nome del progetto che vuoi modificare. Per trovarlo, nell'istanza di Looker, apri la pagina Progetti LookML. L'ID progetto si trova nella colonna Progetto.

Autenticazione con le credenziali API

Se preferisci utilizzare le chiavi API Looker, segui la documentazione per creare le credenziali API. Devi anche fornire l'ID progetto.

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

Sostituisci quanto segue:

  • https://YOUR_INSTANCE_URL: l'URL dell'istanza di Looker.
  • YOUR_CLIENT_ID e YOUR_CLIENT_SECRET: l'ID client e il client secret per le credenziali API che utilizzi per l'autenticazione. Per trovare queste credenziali, nell'istanza di Looker, apri la pagina Account e poi, nella sezione Chiavi API, fai clic sul pulsante Gestisci. Si apre la pagina Chiavi API , dove puoi visualizzare gli ID client e i secret.
  • YOUR_PROJECT_ID: il nome del progetto che vuoi modificare. Per trovare il nome del progetto, nell'istanza di Looker, apri la pagina Progetti LookML. L'ID progetto si trova nella colonna Progetto.

Impostazioni

Puoi configurare le seguenti impostazioni MCP nell'area di lavoro dell'IDE.

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 di Looker. Obbligatorio per l'autenticazione con chiave API. -
looker.clientSecret Client secret API Looker. Obbligatorio per l'autenticazione con chiave API. -
looker.projectId ID progetto Looker. -
looker.mcpServerUrl URL del server MCP esterno per il proxy (ad esempio, http://localhost:5000/mcp). -
looker.acceptSelfSignedCertificates Ignora gli errori del certificato SSL (ad esempio, per i certificati autofirmati). Avviso: non è consigliabile abilitare questa opzione. false
looker.askBeforeOverwritingRemote Chiedi sempre prima di sovrascrivere i file remoti quando viene rilevato un conflitto. false

Configurare il client MCP

Per consentire all'agente AI di interagire con Looker tramite l'estensione, devi configurare l'agente in modo che si connetta all'URL del proxy MCP dell'estensione. Per impostazione predefinita, il proxy viene eseguito localmente all'indirizzo http://127.0.0.1:5050.

Se il server MCP è in esecuzione su una porta diversa da 5000 o su una macchina remota, devi aggiornare la configurazione del proxy dell'estensione. Per farlo, aggiorna l'impostazione looker.mcpServerUrl nelle impostazioni dello spazio di lavoro di VS Code. Per ulteriori informazioni, consulta la sezione Impostazioni.

Visual Studio Code (Copilot)

  1. Apri VS Code e crea la directory .vscode nella radice del progetto, se non esiste già.
  2. Crea il file .vscode/mcp.json, se non esiste già, e aprilo.
  3. Aggiungi la seguente configurazione e salva il file: 
      {
        "servers": {
          "looker": {
            "type": "http",
            "url": "http://127.0.0.1:5050"
          }
        }
      }

Claude Code

  1. Crea il file .mcp.json nella radice del progetto, se non esiste già.
  2. Aggiungi la seguente configurazione e salva il file: 
      {
        "mcpServers": {
          "looker": {
            "type": "http",
            "url": "http://127.0.0.1:5050"
          }
        }
      }

Cursore

  1. Crea la directory .cursor nella radice del progetto, se non esiste già.
  2. Crea il file .cursor/mcp.json, se non esiste già, e aprilo.
  3. Aggiungi la seguente configurazione e salva il file: 
      {
        "mcpServers": {
          "looker": {
            "type": "http",
            "url": "http://127.0.0.1:5050"
          }
        }
      }
  1. Apri Cursor e vai a Impostazioni > Impostazioni cursore > MCP. Quando il server si connette, viene visualizzato uno stato attivo verde.

Cline

  1. Apri l'estensione Cline in VS Code e fai clic sull'icona Server MCP.
  2. Fai clic su Configura server MCP per aprire il file di configurazione.
  3. Aggiungi la seguente configurazione e salva il file: 
      {
        "mcpServers": {
          "looker": {
            "type": "http",
            "url": "http://127.0.0.1:5050"
          }
        }
      }

Windsurf

  1. Apri Windsurf e vai all'assistente Cascade.
  2. Fai clic sull'icona MCP e poi su Configura per aprire il file di configurazione.
  3. Aggiungi la seguente configurazione e salva il file: 
      {
        "mcpServers": {
          "looker": {
            "type": "http",
            "url": "http://127.0.0.1:5050"
          }
        }
      }

Autenticazione tramite Looker

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

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

Clonare il progetto LookML

Per iniziare lo sviluppo, devi clonare il repository LookML sulla tua macchina locale.

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

L'estensione rileva automaticamente i file LookML e inizia la sincronizzazione con il branch 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 di log e seleziona Debug o Traccia.

  • 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 l'istanza di Looker sia accessibile dalla rete locale e di avere una connessione internet valida.

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

Passaggi successivi