Con l'esploratore API di Looker, gli utenti possono testare le chiamate API quasi istantaneamente senza dover scrivere una singola 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 comune è come eseguire queste chiamate o funzioni al di fuori di API Explorer. 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 cliente e il segreto cliente dall'amministratore di Looker.
Per le istanze di Looker ospitate su Google Cloud o Microsoft Azure e per le istanze ospitate su Amazon Web Service (AWS) create il 07/07/2020 o in data successiva, il percorso dell'API Looker predefinito utilizza la porta 443. Per le istanze Looker ospitate su AWS create prima del 07/07/2020, il percorso predefinito dell'API Looker utilizza la porta 19999.
Se ospiti la tua istanza, rivolgiti all'amministratore di sistema per conoscere il numero di porta. Potrebbe essere impostato nel campo URL dell'host dell'API del pannello di amministrazione di Looker. Per visualizzare questa informazione, vai al menu a discesa Amministrazione in Looker e seleziona API.
Per ulteriori informazioni sulle porte, vai alla pagina della documentazione Introduzione 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) di 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à:
- Inviare dati a Looker
- Ottenere dati da Looker
- Aggiornare 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
Cosa succede se non vuoi scrivere uno script 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, uno smartphone o persino la tua 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 li eliminano o li 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. Poi prendi questo token di accesso e lo passi 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 hanno il formatohttps://<hostname>.<subdomain>.<domain>.com. Quando vedi questa notazione negli esempi di questa pagina, sostituisci la sezione<hostname>.<subdomain>.<domain>.comcon l'URL della tua istanza Looker. Inoltre, utilizziamo la notazione<value>per indicare dove inserire il valore appropriato, sostituendo<value>nell'esempio di codice. Ad esempio, nel codice seguente, dove viene mostratoclient_id=<value>&client_secret=<value>, sostituisci il primo<value>conclient_ide il secondo<value>conclient_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 indica che Looker riconosce le tue credenziali API. Il token viene restituito con un valore expires_in, che indica la durata della sua validità. Spesso sono necessari 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 che tu voglia creare un nuovo utente. Per farlo:
- Scrivi una richiesta curl
POSTche trasmetta il tuo token per indicare a Looker che disponi dell'autorizzazione. - Includi un corpo, in questo caso formattato come JSON, per indicare a Looker quali attributi vuoi che abbia il nuovo utente. Esistono alcuni campi obbligatori per le chiamate API, quindi consulta la documentazione del riferimento 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 e -d i dati. Per ulteriori informazioni sui comandi curl, consulta questo gist di GitHub.
Hai appena creato un utente con nome, cognome e indirizzo email contenenti 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 uno strumento di sviluppo software vale la stessa procedura che per le richieste HTTP. Il primo passaggio consiste nell'accedere con la chiave segreta e l'ID client. Poi, memorizza il token di accesso come token bearer per autorizzare le chiamate API successive, come mostrato qui in Postman.
Postman o altri strumenti di sviluppo software (come Paw) ti consentono di specificare l'autorizzazione, il corpo, i parametri e le intestazioni all'interno delle relative UI e poi generano la richiesta per te. Verrà eseguito anche 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, in particolare 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 istanze, quindi è possibile arrestare in modo anomalo un'istanza con 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 credenziali API o lasciarle in un file a cui altri utenti possono accedere.
Se hai una domanda o vuoi condividere un'idea interessante, visita la community di Looker. Non esitare a contattarci se c'è qualcosa che possiamo migliorare o se ci sono altri esempi che vuoi aggiungere alla nostra documentazione.