Utilizzando Explorer API di Looker, gli utenti possono testare le chiamate API quasi istantaneamente senza dover scrivere una sola riga di codice. Se hai installato l'estensione Explorer API dal marketplace di Looker, puoi fare clic su Explorer API nel menu Applicazioni di Looker per aprire Explorer API e visualizzare la documentazione dell'API corrente. Se non hai installato l'estensione API Explorer, puoi farlo dalla sezione Applications (Applicazioni) di Looker Marketplace.
Forse, utilizzando Explorer API, hai trovato il flusso di lavoro migliore per creare dinamicamente un look, aggiornare la query sottostante e pianificarlo per vari stakeholder della tua azienda. Una domanda successiva comune è: come posso eseguire queste chiamate o funzioni al di fuori di Explorer API? Esistono tre modi comuni per accedere all'API:
- Software development kit (SDK) dell'API di Looker
- Richieste HTTP
- Strumenti di sviluppo software
Questa pagina spiega come utilizzare questi metodi.
Prima di iniziare: autenticazione e porte
Indipendentemente da come accedi all'API di Looker, devi prima disporre di due informazioni: l'autenticazione API personale (sotto forma di ID cliente e segreto cliente) e il numero di porta utilizzato dalla tua istanza Looker.
Per trovare un ID client e un client secret:
- Se sei un amministratore di Looker, vai alla pagina Utenti nell'interfaccia utente di Looker per l'utente che ti interessa e vai a Modifica chiavi.
- Se non sei un amministratore di Looker, avrai ricevuto l'ID client e il client secret dall'amministratore di Looker.
Per le istanze di Looker ospitate su Google Cloud o Microsoft Azure e per quelle ospitate su Amazon Web Service (AWS) create a partire dal 07/07/2020, il percorso dell'API Looker predefinito utilizza la porta 443. Per le istanze di Looker ospitate su AWS create prima del 07/07/2020, il percorso dell'API Looker predefinito utilizza la porta 19999.
Se ospiti la tua istanza, rivolgiti all'amministratore di sistema per conoscere il numero di porta. Può essere impostato nel campo URL host API del pannello di amministrazione di Looker. Per farlo, vai al menu a discesa Amministratore in Looker e seleziona API.
Per saperne di più sulle porte, vai alla pagina della documentazione Guida introduttiva all'API Looker. I seguenti esempi utilizzano una porta API pari a 19999, ma devi verificare la porta utilizzata dalla tua istanza.
Opzione 1: utilizza un software development kit (SDK) Looker
Looker offre SDK client ufficiali dell'API Looker in Python, Ruby, Typescript e JavaScript, Swift, Kotlin e R. Puoi trovare il codice sorgente e gli esempi nel repository GitHub di sdk-examples di Looker.
Un SDK fornisce strumenti o librerie che consentono agli sviluppatori di interagire con una determinata piattaforma o applicazione. In questo caso, gli SDK di Looker in genere contengono API. Per citare un esempio dello sviluppatore web e autore Kristopher Sandoval, "le API sono linee telefoniche che consentono la comunicazione all'interno e all'esterno della casa. L'SDK è la casa stessa e tutti i suoi contenuti". In un ottimo articolo, Qual è la differenza tra un'API e un SDK?, spiega che cos'è un SDK e come si relaziona alle API.
Gli SDK di Looker contengono tutti gli endpoint API che potresti voler o dover utilizzare e sono pacchettizzati in modo da consentirti di interagire facilmente con Looker utilizzando il linguaggio di programmazione che preferisci. Le funzioni ti consentono di svolgere le seguenti attività:
- Invia i dati a Looker
- Recuperare i dati da Looker
- Aggiorna i dati in Looker
- Eliminare i dati in Looker
Ecco un esempio di come aggiornare un utente con l'SDK Python:
-
Inizializza la sessione con
looker_sdk.init. -
Aggiorna l'utente con
sdk.update_user. Trasmettiuser_idper specificare l'utente che vuoi aggiornare. -
Utilizza
models.WriteUserper specificare come vuoi aggiornare l'utente.
#### Initialize API/SDK for more info go here: https://pypi.org/project/looker-sdk
from looker_sdk import methods40, models
sdk = looker_sdk.init40()
me = sdk.me()
# print(me)
new_friend = sdk.update_user(user_id=29,
body=models.WriteUser(first_name="newnew", last_name="new_again"))
print(new_friend)
Quando utilizzi uno dei nostri SDK, se usi un IDE come Visual Studio Code e fai clic con il tasto Ctrl (F12 nelle impostazioni predefinite di Visual Studio Code) e poi selezioni Vai alle definizioni, puoi vedere tutti i metodi e tutti i parametri accettati o restituiti dai metodi. In alternativa, puoi trovarli nel repository GitHub dell'SDK cercando i file di metodi e modelli.
Opzione 2: richieste HTTP con curl o una libreria di richieste
E se non volessi scrivere un copione o passare mesi o anni a imparare un nuovo linguaggio di programmazione? In questo caso, puoi utilizzare curl per inviare richieste HTTP per utilizzare l'API di Looker.
Una richiesta HTTP invia un messaggio a una destinazione, che può essere un server, un telefono o perfino una smart TV. Esistono diversi tipi di richieste HTTP. Il modo in cui utilizzi queste richieste con l'API di Looker dipende dalla natura del metodo che passi nell'ambito della chiamata API. Alcuni metodi forniscono dati, altri li inviano a Looker, altri li aggiornano e altri ancora li eliminano o rimuovono da Looker.
| Azione | Metodo |
| Crea |
POST
|
| Leggi |
GET
|
| Aggiorna |
PUT
|
| Elimina |
DELETE
|
Iniziamo a giocare a curling. Per informazioni di base, Zendesk offre un ottimo tutorial, Installazione e utilizzo di cURL.
Per iniziare a effettuare chiamate HTTP all'API Looker, la prima cosa da fare è chiamare l'endpoint login dell'API Looker utilizzando il tuo ID client e il tuo client secret. Viene creato un token di accesso. Devi poi prendere il token di accesso e passarlo a ogni chiamata. Il token di accesso garantisce che la chiamata provenga da un utente autorizzato.
Questa pagina utilizza un paio di notazioni per indicare dove devi sostituire il testo nel codice di esempio con le tue informazioni. Gli URL delle istanze ospitate da Looker assumono il formatohttps://<hostname>.<subdomain>.<domain>.com; nel punto in cui questa notazione è presente negli esempi di questa pagina, sostituisci la sezione<hostname>.<subdomain>.<domain>.comcon l'URL dell'istanza di Looker. Inoltre, utilizziamo la notazione<value>per indicare dove inserire il valore appropriato, sostituendo<value>nell'esempio di codice. Ad esempio, nel seguente codice, dove mostraclient_id=<value>&client_secret=<value>, sostituisci il primo<value>conclient_ide il secondo<value>con il tuoclient_secret.
Ecco il comando curl per ottenere il token di accesso:
curl -d "client_id=<value>&client_secret=<value>" https://<hostname>.<subdomain>.<domain>.com:19999/login
Ecco la risposta:
{"access_token":"ABCDEFGHIJLMNOP1234","token_type":"Bearer","expires_in":3600}
La ricezione del token ti informa che Looker riconosce le tue credenziali API. Il token viene restituito con un valore expires_in, che indica per quanto tempo è valido. Spesso la durata è di circa 60 minuti (3600 secondi).
Ora che hai un token di accesso, puoi effettuare tutte le chiamate che vuoi. Tutti gli endpoint sono elencati in base alla versione dell'API nella documentazione del riferimento all'API Looker 4.0. Inoltre, ricorda che il sito della community di Looker è un'ottima risorsa per porre altre domande agli utenti di Looker su come sfruttano l'API, per conoscere le best practice o per condividere con altri utenti i risultati ottenuti con l'API.
Supponiamo di voler creare un nuovo utente. Per farlo:
- Scrivi una richiesta curl
POSTche trasmette il tuo token per comunicare a Looker che hai l'autorizzazione. - Includi un corpo, in questo caso formattato come JSON, per indicare a Looker gli attributi che vuoi che il nuovo utente abbia. Esistono alcuni campi obbligatori per le chiamate API, quindi consulta la documentazione del riferimento dell'API Looker 4.0.
- Termina la notazione curl con l'endpoint che vuoi utilizzare, in questo caso
users.
curl -H "Authorization: token <value>
" -H "Content-Type: application/json" -d "{\"first_name\": \"<value>\",\"last_name\": \"<value>\", \"email\":\"<value>\"}" https://<hostname>.<subdomain>.<domain>.com:19999/api/4.0/users
-H indica l'intestazione, mentre -d indica i dati. Per ulteriori informazioni sui comandi curl, vai a questo gist di GitHub.
Hai appena creato un utente con nome, cognome e indirizzo email contenente i valori inseriti in precedenza.
E se volessi scrivere tutto in uno script per non dover scrivere questi comandi ogni volta che vuoi completare questo flusso di lavoro? Puoi utilizzare un linguaggio di programmazione e una libreria come la libreria requests di Python.
Ad esempio, di seguito è riportato uno script che utilizza la libreria requests per ottenere un look utilizzando l'ID look (<value> nella chiamata looks), applicare un nuovo filtro e scaricare i risultati come file CSV:
import requests
ID = '<value>'
SECRET = '<value>'
PARAMS = {'client_id':<value>,
'client_secret': <value>}
URL = "https://<hostname>.<subdomain>.<domain>.com:19999/api/4.0/login"
r = requests.post(url = <value>, params = <value>, verify=False)
data = r.json()
token = data['access_token']
print(token)
headers = {'Authorization': "Bearer " + token}
print(headers)
look_url = "https://<hostname>.<subdomain>.<domain>.com:19999/api/4.0/looks/<value>"
look = requests.get(look_url, headers=headers, verify=False)
json = look.json()
query = json['query']
### ADD MODEL HERE
### ADD FILTER
body = {
"model":"<value>",
"view":query['view'],
"fields":query['fields'],
"filters":{<value>}
}
print(body)
run_inline = "https://<hostname>.<subdomain>.<domain>.com:19999/api/4.0/queries/run/csv"
run_query = requests.post(run_inline, headers = headers, json=body, verify=False)
print(run_query._content)
print(run_query.url)
Opzione 3: strumenti di sviluppo software
Strumenti come Postman o Paw consentono agli utenti di interagire con gli endpoint API o di utilizzarli tramite una GUI (Graphic User Interface). Per gli strumenti di sviluppo software si applica la stessa procedura utilizzata per le richieste HTTP. Per prima cosa devi accedere con il tuo client secret e il tuo ID client. Quindi, memorizza il token di accesso come token di connessione per autorizzare le chiamate API successive, come mostrato qui in Postman.
Postman o altri strumenti di sviluppo software (come Paw) ti consentono di specificare autorizzazione, corpo, parametri e intestazioni all'interno delle loro interfacce utente e quindi di generare la richiesta per te. Inoltre, eseguiranno l'endpoint quando premi invia.
Vai avanti! (ma fai attenzione)
Ora che puoi utilizzare l'API di Looker tramite un SDK, una richiesta HTTP e uno strumento di sviluppo software, non esitare a provarla. Tuttavia, tieni presente che, sebbene l'utilizzo dell'API possa aiutarti ad automatizzare processi come la creazione o la riassegnazione di una pianificazione dopo che un utente lascia la tua azienda, un utilizzo improprio dell'API può danneggiare un'istanza.
Ecco alcune indicazioni generali da ricordare:
- Fai attenzione quando modifichi le autorizzazioni o elimini gli utenti, soprattutto in blocco. È possibile eliminare o bloccare molti utenti, inclusi gli amministratori, e azioni come questa non possono essere facilmente annullate.
- Le chiamate API aumentano l'utilizzo delle istanze, quindi prova a pianificarle per le ore di riposo per ottenere un rendimento ottimale.
- Esiste un limite di file aperti su ogni server di istanza, quindi è possibile arrestare un'istanza tramite un utilizzo irresponsabile dell'API.
- Prova i flussi di lavoro e le funzioni su piccola scala prima di aggiungerli alla produzione.
- Non condividere mai le tue credenziali API e non lasciarle in un file dove altri utenti possono accedervi.
Se hai una domanda o vuoi condividere un'idea interessante, visita la community di Looker. Non esitare a comunicarci se c'è qualcosa che possiamo migliorare o se ci sono altri esempi che vorresti aggiungere alla nostra documentazione.