Risoluzione dei problemi dell'API Looker

Nota: a partire dalla versione 22.4 di Looker, l'API Looker 4.0 è in disponibilità generale. L'API 3.1 è deprecata.

Questa pagina presenta procedure di risoluzione dei problemi che potresti riscontrare con l'API Looker:

• L'endpoint API non è raggiungibile
• Il risultato dell'API è testo senza senso
• Le chiamate API non rispondono
• Errori di codifica non validi
• Errori Metodo non trovato
• Errori relativi alla richiesta non valida (400)
• Errori Vietato (403)
• Errori Non trovato (404)
• Errori Metodo non consentito (405)
• Errori (409) in conflitto
• Errori di convalida (422)
• Errori Troppi richieste (429)
• Errori interni del server (500)

L'endpoint API non è raggiungibile

Se non riesci a raggiungere un endpoint API:

• Verifica le credenziali dell'API
• Verificare l'URL dell'host dell'API
• Verifica la porta dell'API
• Verificare l'URL di chiamata API

Verifica le credenziali dell'API

Se l'endpoint API di Looker non è raggiungibile, verifica innanzitutto che le credenziali dell'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 utenti e fai clic per modificare la pagina.
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 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 dell'API non corretto. 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 quelle installate 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 all'utente.

Gli amministratori di Looker possono vedere l'URL dell'host dell'API nelle impostazioni dell'amministratore dell'API, come descritto in maggiore dettaglio nella pagina della documentazione Impostazioni amministratore - API. Per visualizzare l'URL dell'host dell'API:

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

3. Visualizza l'URL dell'host dell'API.

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

   https://<instance_name>.cloud.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 per sapere come aprire una console per il tuo browser.

2. Inserisci il tuo URL host API seguito da /alive. Ad esempio, se il tuo 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 le istanze ospitate su Amazon Web Services (AWS) create il 07/07/2020 o in una data successiva, 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 predefinito dell'API Looker utilizza la porta 19999:

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

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

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

Se questi controlli non riescono, il problema potrebbe essere che stai chiamando l'API in modo errato o che nel tuo codice sono presenti altri errori. Controlla le chiamate API e il codice nello script. Se è corretto, consulta la sezione successiva sulla verifica del trasferimento.

Verifica la porta dell'API

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

La porta API deve inoltrare il server Looker. Per i deployment Looker ospitati dal cliente, chiedi all'amministratore di rete di controllare le impostazioni della porta dell'API. La porta API è principalmente 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 per la porta API siano le stesse della porta dell'istanza Looker:

• Proxy
• Bilanciatori del carico
• Firewall

Verifica l'URL di chiamata dell'API

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

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

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

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

Il formato dell'URL per gli endpoint API è disponibile in Explorer API, sul Portale per gli sviluppatori di Looker oppure nella documentazione Riferimento API.

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

/api/4.0/running_queries

Di conseguenza, l'URL completo dell'endpoint API per l'endpoint Get All Running Query sull'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 è privo di 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 vengono visualizzati come testo binario.

In questo caso, devi assicurarti che la libreria HTTP 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 si tratta di un risultato binario oppure 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 stringa.

Le chiamate API non rispondono

Se sei in grado di aprire Explorer API ma le tue chiamate API non rispondono, verifica che l'impostazione URL host API della tua istanza di Looker sia impostata correttamente. Gli amministratori di Looker possono vedere l'URL dell'host dell'API nelle impostazioni dell'amministratore 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 cerchi di effettuare una chiamata API, durante la richiesta potrebbe essere necessario impostare l'intestazione Content-Type corretta. Gli standard per il protocollo HTTP richiedono che qualsiasi richiesta POST, PUT o PATCH contenga un'intestazione Content-Type. Poiché l'API Looker utilizza JSON nel suo complesso, 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 visualizzi un errore Metodo non trovato, ad esempio method not found: all_looks(), la prima cosa da verificare è la tua versione API. Esistono diverse chiamate API nuove nell'API 4.0 o rimosse nell'API 4.0. Per l'elenco degli aggiornamenti, consulta l'annuncio sull'API Looker 4.0 generalmente disponibile.

Errori Richiesta errata (400)

Un errore 400 Bad Request indica che i dati forniti in una chiamata API non sono riconoscibili. La causa dell'errore è spesso un errore o un JSON non valido, magari 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 Vietato (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. La restituzione di un errore 403 anziché di un errore 404 potrebbe, in alcuni casi, verificare l'esistenza di un determinato oggetto Explore, dashboard o LookML quando il proprietario può preferire che questa informazione non sia nota. Per evitare ciò, Looker restituisce un errore 404 in questi casi e l'errore associato nell'interfaccia utente di Looker dice: "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 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é 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 problema può verificarsi anche quando si utilizza una versione obsoleta della gemma dell'SDK Ruby. Assicurati di tenere aggiornate queste perle. Puoi controllare all'indirizzo https://rubygems.org/gems/looker-sdk.

Questo può verificarsi anche quando non includi la parte /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 se qualcosa va storto, di solito con aspetti come le autorizzazioni. Il messaggio di risposta per un errore 404 fornisce informazioni, se presenti, minime. Questa operazione è intenzionale, dal momento che gli errori 404 vengono mostrati a persone 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 o il client secret dell'API non sia valido (consulta la sezione Verifica le credenziali dell'API in precedenza 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 con codice 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 corrispondere all'URL dell'API dell'istanza di Looker nel formato https://<your-looker-hostname>:<port>. Segue un file looker.ini di esempio:

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

Puoi anche visualizzare un errore 404 dopo aver eseguito l'accesso. Se hai eseguito l'accesso e viene visualizzato un errore 404, significa che non hai le autorizzazioni per il comando API 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 target non supporta questo metodo.

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

Ad esempio, in Looker potresti riscontrare questo problema se cercassi 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 richiesta con lo stato attuale della risorsa di destinazione.

È più probabile che si verifichino conflitti in risposta a una richiesta PUT. Un esempio comune non di Looker di questo errore si verifica quando un file caricato sul server è precedente a quello esistente sul server, causando un conflitto tra il controllo della versione e la 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, controlla se l'oggetto che stai cercando di creare esiste già.

Errori di convalida (422)

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

• Campi mancanti: c'è un parametro obbligatorio che non è stato fornito (la risposta di errore indicherà quale campo è mancante).
• Non valido: il valore fornito non corrisponde a un valore esistente oppure il formato non è corretto. Ad esempio, se cerchi di creare un look e l'ID query fornito 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 nome o un ID già presente sulla tua 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, verrà visualizzato un errore di convalida con il codice already_exists.

Consulta il messaggio di risposta di errore per i dettagli sui campi mancanti o obbligatori o sui campi con valori non validi. Il messaggio di risposta fornisce tutti gli errori di convalida contemporaneamente. Pertanto, se mancano campi e anche campi errati, la risposta all'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 includeva il campo dialect obbligatorio e presentava un valore non valido nel campo db_timezone.

Numero eccessivo di richieste (429)

Il codice di stato della risposta 429 Too Many Requests indica che l'utente ha inviato troppe richieste in un determinato lasso di tempo ("limitazione di frequenza"). Per saperne di più sui criteri 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 generica "catch-all". In genere, ciò 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, quindi, se visualizzi questo errore in modo coerente durante il tentativo di interazione con Looker, ti consigliamo di contattare l'assistenza Looker.