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 da Looker Marketplace, puoi fare clic su Explorer API nel menu Applicazioni di Looker per aprire Explorer API e visualizzare la documentazione attuale delle API. Se non hai installato l'estensione Explorer API, puoi installarla dalla sezione Applicazioni di Looker Marketplace.
Forse utilizzando Explorer API, hai individuato il flusso di lavoro migliore per creare dinamicamente un Look, aggiornare la query sottostante e pianificarlo per i vari stakeholder della tua azienda. La domanda più comune è: come posso eseguire queste chiamate o funzioni al di fuori di API Explorer? Esistono tre modi comuni per accedere all'API:
- SDK (Software Development Kit) API di Looker
- Richieste HTTP
- Strumenti di sviluppo software
Questa pagina illustra come utilizzare questi metodi.
Prima di iniziare: autenticazione e porte
Indipendentemente da come accedi all'API di Looker, avrai innanzitutto bisogno di due informazioni: l'autenticazione dell'API personale (sotto forma di ID client e client secret) e il numero di porta utilizzato dall'istanza di Looker.
Per trovare un ID client e un client secret:
- Se sei un amministratore di Looker, visita la 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, riceverai il tuo ID client e il tuo 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 7/07/2020, il percorso dell'API Looker predefinito utilizza la porta 443. Per le istanze di Looker ospitate su AWS create prima del 7/07/2020, il percorso predefinito dell'API Looker utilizza la porta 19999.
Se ospiti la tua istanza, chiedi il numero di porta all'amministratore di sistema. Può essere impostato nel campo URL host API del pannello di amministrazione di Looker. Per verificarlo, vai al menu a discesa del menu Amministrazione in Looker e seleziona API.
Per saperne di più sulle porte, consulta la pagina della documentazione della guida introduttiva all'API Looker. I seguenti esempi utilizzano una porta API pari a 19999, ma devi confermare la porta utilizzata dall'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 codice sorgente ed 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. Prendiamo come esempio l'autore e sviluppatore web 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." Spiega che cos'è un SDK e come questo si relaziona con le API in un ottimo articolo, Qual è la differenza tra un'API e un SDK?
Gli SDK di Looker ospitano tutti gli endpoint API che potresti voler o dover utilizzare e sono pacchettizzati in modo da consentirti di interagire perfettamente con Looker utilizzando il linguaggio di programmazione che preferisci. Le funzioni consentono di eseguire le seguenti attività:
- Invia dati a Looker
- Acquisisci 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. Passi iluser_idper specificare quale utente vuoi aggiornare. -
Utilizza
models.WriteUserper specificare la modalità di aggiornamento dell'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 usi uno dei nostri SDK, se usi un IDE come Visual Studio Code e fai clic sul comando (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: cerca metodi e file del modello.
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 effettuare 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 persino la tua smart TV. Esistono vari tipi di richieste HTTP. Il modo in cui puoi utilizzare 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 aggiornano i dati e altri eliminano o rimuovono dati da Looker.
| Action (Azione) | Metodo |
| Crea |
POST
|
| Leggi |
GET
|
| Aggiorna |
PUT
|
| Elimina |
DELETE
|
Iniziamo con il curling. Per alcune informazioni, 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 così creato un token di accesso. Quindi, 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 è necessario sostituire il testo nell'esempio di codice con le tue informazioni. Gli URL delle istanze ospitate da Looker assumono il formatohttps://<hostname>.<subdomain>.<domain>.com; dove 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 devi inserire il valore appropriato, sostituendo il<value>nell'esempio di codice. Ad esempio, nel codice seguente, dove mostraclient_id=<value>&client_secret=<value>, sostituisci la prima<value>conclient_ide la seconda<value>conclient_secret.
Ecco il 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 per quanto tempo è valido. Spesso dura circa 60 minuti (3600 secondi).
Ora che disponi di un token di accesso, puoi effettuare le chiamate che vuoi. Tutti gli endpoint sono elencati in base alla versione dell'API nella documentazione relativa al riferimento API Looker 4.0. E ricorda che il sito della community di Looker è un'ottima risorsa per porre ad altri utenti di Looker domande su come sfruttano l'API, per apprendere le best practice o per condividere i successi che hai avuto con l'API con altri utenti.
Supponiamo che tu voglia creare un nuovo utente. Per farlo:
- Scrivi una richiesta
POSTcurl che passa il tuo token per comunicare a Looker che hai l'autorizzazione. - Includi un corpo, in questo caso in formato JSON, per indicare a Looker gli attributi che vuoi assegnare al nuovo utente. Esistono alcuni campi obbligatori per le chiamate API, quindi consulta la documentazione di riferimento sull'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 maggiori informazioni sui comandi curl, vai a questo gist GitHub.
Hai appena creato un utente con il nome, il cognome e l'indirizzo email che contiene i valori inseriti in precedenza.
E se volessi scriverlo in uno script in modo da non doverlo scrivere ogni volta che vuoi completare il flusso di lavoro? Puoi utilizzare un linguaggio di programmazione e una libreria come la libreria requests di Python.
Ad esempio, ecco uno script che utilizza la libreria requests per ottenere un Look utilizzando l'ID Look (<value> nella chiamata looks), applicare un nuovo filtro e poi 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 o sfruttare gli endpoint API tramite una Graphic User Interface (GUI). A uno strumento di sviluppo software viene applicata la stessa procedura valida per le richieste HTTP. Per prima cosa, accedi con il tuo client secret e l'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 l'autorizzazione, il corpo, i parametri e le intestazioni all'interno delle loro UI e quindi di generare la richiesta per te. Inoltre, eseguiranno l'endpoint quando premi Invia.
Pronti! (ma fai attenzione)
Ora che puoi utilizzare l'API di Looker tramite un SDK, una richiesta HTTP e uno strumento di sviluppo software, mettiti alla prova. Tuttavia, tieni presente che, anche se l'utilizzo dell'API può aiutare ad automatizzare processi come la creazione o la riassegnazione di una pianificazione dopo che un utente lascia l'azienda, un utilizzo improprio dell'API può danneggiare un'istanza.
Alcuni aspetti generali da ricordare:
- Fai attenzione quando modifichi le autorizzazioni o elimini 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 al di fuori dell'orario di lavoro per ottenere prestazioni ottimali.
- Esiste un limite di file aperto su ogni server di istanza, quindi è possibile che un'istanza venga arrestata in modo anomalo a causa di un utilizzo irresponsabile dell'API.
- Testa flussi di lavoro e funzioni su piccola scala prima di aggiungerli alla produzione.
- Non condividere mai le credenziali dell'API e non lasciarle in un file dove altri utenti possono accedervi.
Se hai una domanda o vuoi condividere un'idea interessante, dai un'occhiata alla community di Looker. Non esitare a contattarci se c'è qualcosa che possiamo migliorare o se vuoi aggiungere altri esempi alla nostra documentazione.