Risoluzione dei problemi relativi all'API Looker

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

L'endpoint API non è raggiungibile

Se non riesci a raggiungere un endpoint API:

Verifica le credenziali API

Se il tuo endpoint API Looker non è raggiungibile, verifica innanzitutto che le credenziali API siano corrette. Per visualizzare le credenziali dell'API:

  1. In Looker, accedi al pannello di amministrazione selezionando l'opzione Admin (Amministrazione) nel pannello di navigazione a sinistra.
  2. Nel riquadro sinistro della pagina Amministrazione, scorri verso il basso e fai clic su Utenti.
  3. Cerca il tuo nome utente nell'elenco degli utenti e fai clic su di esso per modificare la tua pagina utente.
  4. Fai clic su Edit API Keys (Modifica chiavi API). Puoi vedere il Client-ID e fare clic sull'icona a forma di occhio per visualizzare il Client Secret per ciascuna chiave API che hai configurato. Verifica che le credenziali dell'API corrispondano a quelle che utilizzi nello script.

Verifica l'URL dell'API

Un altro problema comune quando si raggiunge un endpoint API è un URL host dell'API errato. La maggior parte delle istanze di Looker utilizza l'URL predefinito per l'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 dell'host dell'API deve indicare il nome host e la porta dell'API rivolti agli utenti.

Gli amministratori di Looker possono vedere l'URL dell'host dell'API nelle impostazioni di amministrazione dell'API (descritto più dettagliatamente nella pagina della documentazione Impostazioni di amministrazione - API). Per visualizzare l'URL dell'host dell'API:

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

  3. Visualizza l'URL dell'API host.

    Se il campo URL host API è vuoto, l'istanza di Looker utilizza il formato predefinito, ovvero:

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

Per testare l'URL host API:

  1. Apri un browser, quindi apri la console del browser.

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

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

    Se il campo URL host API è vuoto, utilizza l'URL dell'API predefinito. Ad esempio, per le istanze ospitate su Google Cloud, Microsoft Azure e su quelle 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>.cloud.looker.com:443/alive

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

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

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

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

Se questi controlli non vanno a buon fine, è possibile che tu stia chiamando l'API in modo errato o che siano presenti altri errori nel codice. Controlla le chiamate API e il codice nello script. Se sono corretti, consulta la sezione successiva sulla verifica del trasferimento.

Verifica la porta API

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

La porta dell'API deve inoltrarsi al server Looker. Per i deployment di Looker ospitati dal cliente, chiedi all'amministratore di rete di verificare le impostazioni della porta dell'API. In genere, la porta API è 443 o 19999. La porta dell'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 siano le stesse per la porta dell'API e per la porta dell'istanza di Looker:

  • Proxy
  • Bilanciatori del carico
  • Firewall

Verificare l'URL della chiamata API

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

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

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

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

Il formato dell'URL per gli endpoint API è disponibile in Explorer API o nella documentazione di Riferimento API.

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

/api/4.0/running_queries

Di conseguenza, l'URL completo dell'endpoint API per l'endpoint Get All Running Lookup sull'istanza di Looker docsexamples.dev.looker.com sarebbe quindi il seguente:

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

Il risultato dell'API è un 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 delle API saranno file di testo, pertanto altri tipi di file vengono visualizzati come testo binario.

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

Le chiamate API non rispondono

Se riesci ad 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 dell'host dell'API nelle impostazioni di amministrazione dell'API di Looker (come descritto nella pagina della documentazione Impostazioni di amministrazione - API).

Errori di codifica non validi

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

Tieni presente che l'utilizzo di un SDK Looker sarà in grado di gestire automaticamente questo problema.

Errori Metodo non trovato

Se visualizzi un errore Metodo non trovato, ad esempio method not found: all_looks(), la prima cosa da controllare è la versione dell'API. Esistono diverse chiamate API nuove in API 4.0 o rimosse in API 4.0. Per l'elenco degli aggiornamenti, vedi l'annuncio dell'API Looker 4.0 in disponibilità generale.

Errori di richiesta errata (400)

Un errore 400 Bad Request indica che i dati forniti in una chiamata API non sono riconoscibili. Il problema è spesso un file JSON inaccessibile o non valido, forse un errore di analisi. Nella maggior parte dei casi, poiché gli errori 400 hanno già superato l'autenticazione, il messaggio di risposta fornirà informazioni più specifiche sull'errore.

Errori (401) Non autorizzato

Un errore 401 Unauthorized in una chiamata API significa che la chiamata non è autenticata correttamente. Per ulteriori informazioni sulla risoluzione dei problemi, consulta l'articolo Come posso risolvere gli errori 401? Articolo della community.

Errori Non consentito (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 potrebbe preferire che non sia noto. Per evitare che questo accada, Looker restituisce un codice 404 in questi casi e l'errore associato nell'interfaccia utente di Looker indica: "Impossibile trovare la pagina richiesta. Non esiste o non hai l'autorizzazione per visualizzarlo."

A seconda dell'ambiente in cui è ospitata l'istanza di Looker e della sua configurazione, il numero di porta e l'URL associato da cui è possibile accedere all'API potrebbero essere diversi. Quando utilizzi un numero di porta errato, è possibile che venga visualizzato l'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é a 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 API.

Questo può verificarsi anche quando utilizzi una versione obsoleta del gem Ruby SDK. Assicurati di tenere aggiornate queste perle. Puoi controllare all'indirizzo https://rubygems.org/gems/looker-sdk.

Questo può succedere anche se non includi la parte /api/<version number>/ dell'URL. In questo caso, se un utente tenta 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 se si verificano problemi, in genere relativi alle autorizzazioni. Il messaggio di risposta relativo a un errore 404 fornisce informazioni minime o nulle. Questa operazione è 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, è molto probabile che l'ID client API o il client secret non siano validi (consulta la sezione Verificare le credenziali API in precedenza in questa pagina). L'endpoint REST di accesso all'API è il seguente:

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

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

  • Per un client codegen Swagger, base_url deve essere il seguente:

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

  • Per le implementazioni dell'SDK Looker che utilizzano looker.ini, il valore di api_version deve essere 4.0 e il valore di base_url deve corrispondere all'URL dell'API dell'istanza di Looker nel formato https://<your-looker-hostname>:<port>. Di seguito è riportato un file looker.ini di esempio:

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

Puoi visualizzare un errore 404 anche dopo aver eseguito l'accesso. Se hai eseguito l'accesso e visualizzi un errore 404, significa che non disponi delle autorizzazioni per il comando API che hai appena chiamato.

Errori Metodo non consentito (405)

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

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

Ad esempio, un modo in cui potresti riscontrare questo problema in Looker è cercare 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, pertanto si verifica un errore 405.

Errori in conflitto (409)

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

In genere si verificano conflitti in risposta a una richiesta PUT. Un esempio comune non Looker di questo errore si verifica quando si carica un file precedente a quello esistente sul server, causando un conflitto nel controllo della versione.

Potresti riscontrare questo errore in Looker quando provi a verificare 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 cercando di creare esiste già.

Errori di convalida (422)

Gli errori di convalida si verificano quando qualcosa nella richiesta non ha superato i controlli dei dati eseguiti. La richiesta contiene uno o più dei seguenti tipi di errori (la risposta specificherà gli errori esatti):

  • Campi mancanti: è presente un parametro obbligatorio che non è stato fornito (la risposta di errore indicherà il campo mancante).
  • 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 fornito nella chiamata API non corrisponde a una query esistente, riceverai un errore di convalida.
  • Esiste già: la chiamata API sta tentando di creare un oggetto con un ID o un nome già presente nell'istanza di Looker. Ad esempio, i nomi delle connessioni al database devono essere univoci. Se provi a creare una nuova connessione di database che utilizza il nome di una connessione esistente, riceverai un errore di convalida con il codice already_exists.

Consulta il messaggio di risposta di errore per informazioni dettagliate su quali campi potrebbero essere mancanti o obbligatori oppure quali possono presentare valori non validi. Il messaggio di risposta fornirà tutti gli errori di convalida contemporaneamente. Pertanto, se mancano campi ed esistono anche campi non corretti, la risposta di errore elencherà tutti i problemi relativi alla tua 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, nella chiamata API mancava il campo dialect obbligatorio e in db_timezone era stato specificato anche un valore non valido.

Troppe errori relativi a richieste (429)

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 di frequenza"). Per saperne di più sulle norme di limitazione di frequenza di Looker, consulta il post della community di Looker Esiste un limite al numero di richieste API che è possibile inviare contemporaneamente?

Errori di errore interno del server (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 "catch-all" generica. Solitamente, questo indica che il server non riesce a trovare un codice di errore 5xx più specifico da restituire in risposta. Qualsiasi risposta 500 da Looker è imprevista. Di conseguenza, se visualizzi questo errore costantemente durante il tentativo di interagire con Looker, ti consigliamo di aprire una richiesta di assistenza.