Risoluzione dei problemi dell'API Looker

Questa pagina contiene procedure per la risoluzione dei problemi che potresti riscontrare con l'API Looker:

L'endpoint API non è raggiungibile

Se non riesci a raggiungere un endpoint API:

Verifica le credenziali dell'API

Se l'endpoint dell'API Looker non è raggiungibile, per prima cosa verifica che le credenziali dell'API siano corrette. Per visualizzare le credenziali API:

  1. In Looker, accedi al amministratore pannello selezionando l'opzione Amministrazione nel pannello di navigazione a sinistra
  2. Nel riquadro a sinistra della pagina Amministratore scorri verso il basso e fai clic su Utenti.
  3. Fai clic sul nome utente nell'elenco degli utenti per modificarlo.
  4. Fai clic su Modifica chiavi API. Puoi vedere l'ID client e fare clic sull'icona a forma di occhio per visualizzare il client secret per ogni chiave API configurata. Verifica che le credenziali dell'API corrispondano a quelle che utilizzi nello script.

Verifica l'URL dell'API

Un altro problema comune nel raggiungere un endpoint API è un URL host API errato. La maggior parte delle istanze di Looker utilizza l'URL predefinito dell'API. Tuttavia, le installazioni di Looker che utilizzano un percorso API alternativo o le installazioni di Looker poste dietro un bilanciatore del carico (ad esempio una configurazione del cluster) o qualsiasi altro proxy potrebbero non utilizzare l'URL predefinito. In questo caso, l'URL host dell'API deve indicare il nome host e la porta dell'API rivolti all'utente.

Gli amministratori di Looker possono visualizzare l'URL host dell'API nelle impostazioni di amministrazione dell'API (descritte in modo più dettagliato nella pagina della documentazione Impostazioni amministratore - API). Per visualizzare l'URL dell'host dell'API:

  1. Accedi al riquadro Amministrazione selezionando l'opzione Amministrazione nel pannello di navigazione a sinistra.
  2. Fai clic su API nel riquadro Amministratore.

  3. Visualizza l'URL host dell'API.

    Se il campo API Host URL (URL host API) è vuoto, l'istanza di Looker utilizza il formato predefinito, ossia:

    https://<instance_name>.looker.com:<port>

Per testare l'URL host dell'API:

  1. Apri un browser e apri la console del browser. Questo articolo di ConcreteCMS.org potrebbe esserti utile se devi scoprire come aprire una console per il tuo browser.

  2. Inserisci il tuo URL host API seguito da /alive. Ad esempio, se l'URL host dell'API è https://company.api.looker.com, inserisci:

    https://company.api.looker.com/alive

    Se il campo URL host API è vuoto, utilizza l'URL API predefinito. Ad esempio, per le istanze ospitate su Google Cloud, Microsoft Azure e le istanze ospitate su Amazon Web Services (AWS) create a partire dal 07/07/2020, il percorso predefinito dell'API Looker utilizza la porta 443:

    https://<instance_name>.looker.com:443/alive

    Per le istanze ospitate su AWS create prima del 07/07/2020, il percorso predefinito dell'API Looker utilizza la porta 19999:

    https://<instance_name>.looker.com:19999/alive

Se l'URL dell'host dell'API è corretto, verrà visualizzata una pagina web vuota, non una pagina di errore:

Puoi anche verificare di aver raggiunto l'API esaminando la risposta di rete nella console del browser. La risposta della rete deve essere 200:

Se questi controlli non vanno a buon fine, il problema potrebbe essere dovuto al fatto che l'API è stata chiamata in modo errato o sono presenti altri errori nel codice. Controlla le chiamate API e il codice nello script. Se è corretto, consulta la prossima sezione sulla verifica della porta.

Verifica la porta dell'API

Se i controlli indicati sopra non vanno a buon fine e hai un deployment di Looker ospitato dal cliente, è possibile che la porta dell'API debba essere aperta sull'infrastruttura di rete.

La porta dell'API deve inoltrare al server Looker. Per i deployment Looker ospitati dal cliente, chiedi all'amministratore di rete di controllare le impostazioni della porta dell'API. La porta dell'API è più comunemente 443 o 19999. La porta API deve avere le stesse impostazioni di configurazione della porta dell'istanza di Looker (9999 per impostazione predefinita). L'amministratore di rete deve verificare che le seguenti impostazioni per la porta API siano le stesse della porta dell'istanza di Looker:

  • Proxy
  • Bilanciatori del carico
  • Firewall

Verificare l'URL chiamata API

Assicurati di utilizzare l'URL corretto per la tua chiamata API. Il formato di un URL endpoint API è:

<API Host URL>/api/<API version>/<API call>

Se utilizzi l'URL host predefinito dell'API, il formato di un URL endpoint API è:

https://<instance_name>:<port>/api/<API version>/<API call>

Puoi trovare il formato URL per gli endpoint API da Explorer API, sul portale per gli sviluppatori di Looker o nella documentazione API Reference.

Ad esempio, il riferimento API 4.0 fornisce il seguente percorso relativo per l'endpoint Get All Running Queries:

Quindi l'URL completo dell'endpoint API per l'istanza di Looker docsexamples.dev.looker.com è il seguente:

https://docsexamples.dev.looker.com:443/api/4.0/running_queries

Il risultato dell'API è testo senza senso

Se l'API restituisce una risposta di testo incomprensibile, è probabile che tu stia visualizzando il contenuto binario di un file PDF, PNG o JPG. Alcune librerie REST HTTP presuppongono che le risposte dell'API siano file di testo, quindi altri tipi di file verranno visualizzati come testo binario.

In questo caso, devi assicurarti che la tua libreria REST HTTP gestisca la risposta dell'API come dati binari, non come testo. In alcuni casi, ciò può significare impostare un flag sulla chiamata API per comunicare alla libreria REST HTTP che è un risultato binario oppure potrebbe significare gestire il risultato in un modo speciale, come un flusso di byte o come un array di byte, invece di assegnare il risultato a una variabile di stringa.

Le chiamate API non rispondono

Se puoi aprire Explorer API ma le chiamate API non rispondono, verifica che l'impostazione URL host API dell'istanza di Looker sia configurata correttamente. Gli amministratori di Looker possono vedere l'URL host dell'API nelle impostazioni di amministrazione dell'API Looker, come descritto nella pagina della documentazione Admin settings - API (Impostazioni amministratore - API).

Errori di codifica non validi

Se ricevi un errore di codifica quando tenti di effettuare una chiamata API, potrebbe essere necessario impostare il Content-Type corretto nell'intestazione durante la richiesta. Gli standard del protocollo HTTP richiedono che qualsiasi richiesta POST, PUT o PATCH contenga un'intestazione Content-Type. Poiché l'API Looker utilizza JSON in tutto il processo, l'intestazione Content-Type deve essere impostata su application/json.

Tieni presente che l'utilizzo di un SDK Looker gestirà automaticamente questo problema per te.

Errori "Metodo non trovato"

Se viene visualizzato un errore Metodo non trovato, ad esempio method not found: all_looks(), la prima cosa da verificare è la versione dell'API. Esistono diverse chiamate API nuove nell'API 4.0 o che sono state rimosse nell'API 4.0. Per l'elenco degli aggiornamenti, consulta l'annuncio API Looker 4.0 disponibile generalmente.

Errori relativi a richieste errate (400)

Un errore 400 Bad Request indica che i dati forniti in una chiamata API non sono riconoscibili. La causa non è spesso un file JSON o è danneggiato, forse un errore di analisi. Nella maggior parte dei casi, gli errori 400 hanno già superato l'autenticazione, quindi il messaggio di risposta all'errore fornisce informazioni più specifiche sull'errore.

Errori non consentiti (403)

L'API Looker non restituisce errori 403 ogni volta che un utente tenta di accedere a un oggetto LookML o ad altri contenuti per cui non dispone dell'autorizzazione. La restituzione di un errore 403 anziché 404 potrebbe, in alcuni casi, verificare l'esistenza di un particolare oggetto Explore, dashboard o LookML quando il proprietario può preferire che non sia noto. Per evitare ciò, in questi casi Looker restituisce un errore 404 e l'errore associato nell'interfaccia utente di Looker indica: "La pagina richiesta non è stata trovata. Non esiste o non hai l'autorizzazione per visualizzarlo."

A seconda dell'ambiente in cui è ospitata l'istanza di Looker e della configurazione dell'istanza di Looker, il numero di porta e l'URL associato a cui è possibile accedere all'API potrebbero essere diversi. Quando utilizzi un numero di porta errato, potresti visualizzare un errore 403. Ad esempio, se l'istanza di Looker è configurata con la porta API predefinita 443, la connessione a https://mycompany.looker.com/api/4.0/login (anziché https://mycompany.looker.com:443/api/4.0/login) restituirà un errore 403. Per le istanze ospitate dal cliente, scopri di più sulle opzioni di avvio di Looker, in cui puoi definire la porta dell'API.

Questo può accadere anche se utilizzi una versione obsoleta della gemma dell'SDK Ruby. Assicurati di tenere aggiornate queste gemme. Puoi controllare all'indirizzo https://rubygems.org/gems/looker-sdk.

Questo può accadere anche quando non includi la porzione /api/<version number>/ dell'URL. In questo caso, se un utente cerca di connettersi a https://mycompany.looker.com:443/login, vedrà una risposta 403.

Errori Non trovato (404)

Un errore 404 Not Found è l'errore predefinito, qualcosa che non va, generalmente con autorizzazioni come le autorizzazioni. Il messaggio di risposta per un errore 404 fornisce informazioni minime (se presenti). Lo scopo è intenzionale, dal momento che gli errori 404 vengono mostrati agli utenti con credenziali di accesso errate o autorizzazioni insufficienti. Looker non vuole fornire informazioni specifiche nei messaggi di risposta 404, poiché queste informazioni potrebbero essere utilizzate per mappare la "superficie di attacco" dell'API Looker.

Se i tentativi di accesso all'API restituiscono errori 404, è più probabile che il tuo ID client API3 o il client secret non siano validi (consulta la sezione Verificare le credenziali dell'API in questa pagina). L'endpoint REST di accesso all'API è uno dei seguenti, a seconda della versione dell'API in uso:

https://<your-looker-hostname>:<port>/api/4.0/login
https://<your-looker-hostname>:<port>/api/3.1/login

Se utilizzi un'API Swagen codegen o un SDK Looker, assicurati che il valore base_url sia corretto:

  • Per un client codegen Swagger, il valore di base_url deve essere uno dei seguenti in base alla versione dell'API in uso:
    • https://<your-looker-hostname>:<port>/api/4.0/
    • https://<your-looker-hostname>:<port>/api/3.1/

  • Per le implementazioni dell'SDK Looker che utilizzano looker.ini, il valore di api_version deve essere 4.0 o 3.1 e il valore di base_url deve essere uguale all'URL dell'API dell'istanza di Looker nel formato https://<your-looker-hostname>:<port>. Esempio di file looker.ini:

    # api_version should be either 4.0 or 3.1
api_version=4.0
base_url=https://<your-looker-hostname>:<port>

Dopo aver eseguito l'accesso potresti anche visualizzare l'errore 404. Se hai eseguito l'accesso e viene visualizzato un errore 404, significa che non disponi delle autorizzazioni per il comando API che hai appena chiamato.

Errori di metodo non consentito (405)

Un errore 405 Method Not Allowed indica che il server conosce il metodo della richiesta, ma la risorsa di destinazione non supporta questo metodo.

Il server deve generare un campo di intestazione Allow in una risposta con codice di stato 405. Il campo deve contenere un elenco di metodi attualmente supportati dalla risorsa di destinazione.

Ad esempio, un modo che potresti riscontrare in Looker è quello di tentare di utilizzare l'endpoint update_dashboard() per aggiornare i metadati di una dashboard LookML. La modifica del parametro id di una dashboard LookML non è supportata tramite l'API Looker, quindi si verifica un errore 405.

Errori in conflitto (409)

Il codice di stato della risposta 409 Conflict indica un conflitto di richieste con lo stato attuale della risorsa di destinazione.

In genere i conflitti si verificano in risposta a una richiesta PUT. Un esempio comune di questo tipo di errore si verifica quando viene caricato un file più vecchio di quello esistente sul server, causando un conflitto di controllo della versione.

Potresti riscontrare questo errore in Looker quando provi a eseguire il check-out di un nuovo ramo git utilizzando l'API o quando utilizzi endpoint come create_group() o create_dashboard(). In questi casi, verifica se l'oggetto che stai tentando di creare esiste già.

Errori di convalida (422)

Gli errori di convalida si verificano quando qualcosa nella richiesta non supera i controlli dei dati. La richiesta contiene uno o più dei seguenti tipi di errore (la risposta di errore specifica gli errori esatti):

  • Campi mancanti: è stato fornito un parametro obbligatorio (la risposta di errore indica quale campo manca).
  • Non valido: il valore fornito non corrisponde a un valore esistente o il valore non è nel formato corretto. Ad esempio, se provi a creare un look e l'ID query che fornisci nella chiamata API non corrisponde a una query esistente, verrà visualizzato un errore di convalida.
  • Esiste già: la chiamata API sta tentando di creare un oggetto con un ID o un nome già presente nella tua istanza di Looker. Ad esempio, i nomi di connessione al database devono essere univoci. Se provi a creare una nuova connessione al database che utilizza il nome di una connessione esistente, riceverai un errore di convalida con il codice already_exists.

Leggi il messaggio di risposta di errore per i dettagli sui campi mancanti o obbligatori oppure sui campi che potrebbero avere valori non validi. Il messaggio di risposta fornirà tutti gli errori di convalida contemporaneamente. Pertanto, se mancano dei campi e anche quelli non corretti, la risposta di errore elenca tutti i problemi relativi alla chiamata API.

Ecco un esempio di risposta:

{
  "message": "Validation Failed",
  "errors": [
    {
    "field": "dialect",
    "code": "missing_field",
    "message": "This field is required.",
    "documentation_url": "http://docs.looker.com/"
    },
    {
    "field": "db_timezone",
    "code": "invalid",
    "message": "Must specify a database timezone when user timezones are activated.",
    "documentation_url": "http://docs.looker.com/"
    }
  ],
    ...

In questo caso, la chiamata API non aveva il campo obbligatorio dialect e presentava anche un valore non valido nel campo db_timezone.

Troppe richieste (429) errori

Il codice di stato della risposta 429 Too Many Requests indica che l'utente ha inviato troppe richieste in un determinato periodo di tempo ("limitazione della frequenza"). Per saperne di più sui criteri di limitazione della frequenza di Looker, consulta l'articolo della community di Looker Esiste un limite al numero di richieste API che puoi inviare contemporaneamente?

Errori del server interno (500)

Il codice di risposta 500 Internal Server Error indica che il server ha riscontrato una condizione imprevista che gli ha impedito di soddisfare la richiesta.

Questa risposta di errore è una risposta generica "catch-all". In genere, indica che il server non riesce a trovare un codice di errore 5xx più specifico da restituire in risposta. Qualsiasi risposta 500 da Looker è inaspettata, quindi, se visualizzi questo errore in modo coerente durante il tentativo di interagire con Looker, ti consigliamo di contattare l'assistenza di Looker.