Risoluzione dei problemi relativi all'API Looker

Questa pagina contiene le procedure di risoluzione dei problemi relativi ai seguenti problemi 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 l'endpoint API di Looker non è raggiungibile, verifica innanzitutto che le credenziali API siano corrette. Per visualizzare le credenziali API:

  1. In Looker, accedi al pannello Amministrazione selezionando l'opzione Amministrazione nel pannello di navigazione a sinistra.
  2. Nel riquadro a sinistra 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 per modificare la tua pagina utente.
  4. Fai clic su Modifica chiavi API. Puoi visualizzare l'ID client e fare clic sull'icona a forma di occhio per visualizzare il client secret per ogni chiave API che hai configurato. Verifica che le credenziali API corrispondano a quelle che utilizzi nello script.

Verifica l'URL dell'API

Un altro problema comune per raggiungere un endpoint API è un URL host 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 situate 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 rivolta agli utenti.

Gli amministratori di Looker possono visualizzare l'URL dell'host dell'API nelle impostazioni di amministrazione dell'API (descritte in dettaglio nella pagina di documentazione Impostazioni di amministrazione - API). Per visualizzare l'URL host dell'API:

  1. Fai clic sull'icona del menu principale di Looker e seleziona Amministrazione per aprire il pannello Amministrazione.
  2. Fai clic su API nel pannello Amministrazione.

  3. Visualizza l'URL host API.

    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 la console del browser.

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

    https://company.cloud.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 Amazon Web Services (AWS) create il 7 luglio 2020 o in data successiva, il percorso API Looker predefinito 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 API Looker predefinito utilizza la porta 19999:

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

Se l'URL dell'API host è corretto, questo URL restituirà 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 che stai chiamando l'API in modo errato o che nel codice sono presenti altri errori. Controlla le chiamate API e il codice nello script. Se sono corretti, consulta la sezione successiva sulla verifica della porta.

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 nell'infrastruttura di rete.

La porta API deve essere inoltrata al server Looker. Per le implementazioni di Looker ospitate dal cliente, chiedi all'amministratore di rete di controllare le impostazioni della porta API. La porta 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 siano le stesse per la porta API e per la porta dell'istanza di Looker:

  • Proxy
  • Bilanciatori del carico
  • Firewall

Verifica l'URL della chiamata API

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

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

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

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

Puoi ottenere il formato dell'URL per gli endpoint API da Explorer API o dalla documentazione di riferimento dell'API.

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

/api/4.0/running_queries

Pertanto, l'URL completo dell'endpoint API per l'endpoint Get All Running Queries nell'istanza di Looker docsexamples.dev.looker.com sarebbe 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 illeggibile, è probabile che tu stia visualizzando il contenuto binario di un file PDF, PNG o JPG. Alcune librerie HTTP REST presuppongono che le risposte API siano file di testo, pertanto altri tipi di file vengono visualizzati come testo binario.

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

Le chiamate API non rispondono

Se riesci ad aprire l'API Explorer, ma le chiamate API non rispondono, verifica che l'impostazione URL dell'host dell'API dell'istanza di Looker sia impostata correttamente. Gli amministratori di Looker possono visualizzare l'URL dell'API host nelle impostazioni amministrative dell'API di Looker (descritte nella pagina di documentazione Impostazioni amministrative - API).

Errori di codifica non validi

Se ricevi un errore di codifica quando tenti di effettuare una chiamata API, potresti dover impostare il valore 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, l'intestazione Content-Type deve essere impostata su application/json.

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

Errori Metodo non trovato

Se ricevi 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 nella versione 4.0 o che sono state rimosse nella versione 4.0. Consulta l'annuncio API Looker 4.0 disponibile a livello generale per l'elenco degli aggiornamenti.

Errori Richiesta non valida (400)

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

Errori di mancata autorizzazione (401)

Un errore 401 Unauthorized in una chiamata API indica che la chiamata API non è autenticata correttamente. Per ulteriori dettagli sulla risoluzione dei problemi, consulta la sezione Come faccio a 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 i quali non dispone dell'autorizzazione. Restituire un errore 403 anziché un errore 404 potrebbe, in alcuni casi, verificare l'esistenza di un determinato oggetto Esplora, dashboard o LookML quando il proprietario potrebbe preferire che non venga scoperto. Per evitare questo problema, Looker restituisce un errore 404 in questi casi e l'errore corrispondente nella UI di Looker recita: "Impossibile trovare la pagina richiesta. Non esiste oppure non disponi dell'autorizzazione per visualizzarla."

A seconda dell'ambiente in cui è ospitata l'istanza di Looker e della sua configurazione, il numero di porta e l'URL associato in cui è possibile accedere all'API potrebbero essere diversi. Quando utilizzi un numero di porta errato, potresti visualizzare un errore 403. Ad esempio, se la tua 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, puoi scoprire di più sulle opzioni di avvio di Looker, dove puoi definire la porta API.

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

Ciò può verificarsi anche quando 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, visualizzerà una risposta 403.

Errori Non trovato (404)

L'errore 404 Not Found è l'errore predefinito se si verifica un problema, in genere con elementi come le autorizzazioni. Il messaggio di risposta per un errore 404 fornisce informazioni minime, se non nulle. Questo è intenzionale, poiché gli errori 404 vengono mostrati alle persone con credenziali di accesso errate o autorizzazioni insufficienti. Looker non vuole fornire informazioni specifiche nei messaggi di risposta 404, in quanto 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 client secret non siano validi (vedi 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 di base_url sia corretto:

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

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

  • Per le implementazioni dell'SDK Looker che utilizzano un 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 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>

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

Errori Method Not Allowed (405)

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

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 supportati dalla risorsa di destinazione.

Ad esempio, potresti riscontrare questo problema in Looker se tentassi 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 verificherà un errore 405.

Errori di conflitto (409)

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

I conflitti si verificano più probabilmente in risposta a una richiesta PUT. Un esempio comune non Looker di questo errore si verifica quando carichi un file precedente a quello esistente sul server, il che comporta un conflitto di controllo della versione.

Potresti riscontrare questo errore in Looker quando tenti di estrarre un nuovo ramo Git utilizzando l'API o quando utilizzi endpoint come create_group() o create_dashboard(). In questi casi, controlla se l'oggetto che stai cercando di creare esiste già.

Errori di convalida (422)

Gli errori di convalida si verificano quando un elemento della richiesta non supera i controlli dei dati eseguiti. La richiesta presenta uno o più dei seguenti tipi di errori (la risposta di errore specificherà gli errori esatti):

  • Campi mancanti: manca un parametro obbligatorio (la risposta di errore indica quale campo manca).
  • Non valido: il valore fornito non corrisponde a un valore esistente o 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, riceverai un errore di convalida.
  • Esiste già: la chiamata API tenta 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 al 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 sui campi mancanti o obbligatori o sui campi con valori non validi. Il messaggio di risposta fornirà tutti gli errori di convalida contemporaneamente. Pertanto, se hai campi mancanti e anche campi errati, la risposta di errore elencherà 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 includeva il campo obbligatorio dialect e conteneva anche un valore non valido nel campo db_timezone.

Errori Troppe 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"). Puoi scoprire di più sulle norme di limitazione di frequenza di Looker nel post della community di Looker Is there a limit to the number of API requests you can send at one time?

Errori interni 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 generica "catch-all". In genere, ciò indica che il server non riesce a trovare un codice di errore 5xx più specifico da restituire nella risposta. Qualsiasi risposta 500 da Looker è imprevista, pertanto, se visualizzi questo errore in modo coerente mentre tenti di interagire con Looker, ti consigliamo di aprire una richiesta di assistenza.