Utilizzando l'API Explorer 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 API corrente. Se non hai installato l'estensione Explorer API, puoi farlo dalla sezione Applicazioni di Looker Marketplace.
Magari, utilizzando Explorer API, hai scoperto il flusso di lavoro migliore per creare dinamicamente un Look, aggiornare la query sottostante e pianificarne l'invio a vari stakeholder della tua azienda. Una domanda successiva comune è: come faccio a 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 Looker
- Richieste HTTP
- Strumenti di sviluppo software
Questa pagina ti spiega come utilizzare questi metodi.
Prima di iniziare: autenticazione e porte
Indipendentemente dalla modalità di accesso all'API di Looker, avrai bisogno di due informazioni: l'autenticazione 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, 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 le istanze ospitate su Amazon Web Service (AWS) create il 07/07/2020 o in data successiva, il percorso API Looker predefinito utilizza la porta 443. Per le istanze di Looker ospitate su AWS create prima del 07/07/2020, il percorso API Looker predefinito utilizza la porta 19999.
Se ospiti la tua istanza, chiedi all'amministratore di sistema il numero di porta. Può essere impostato nel campo URL dell'host dell'API del pannello di amministrazione di Looker. Per visualizzarlo, vai al menu a discesa Amministrazione in Looker e seleziona API.
Per saperne di più sulle porte, consulta la pagina della documentazione Guida introduttiva all'API Looker. Gli esempi seguenti utilizzano una porta API di 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 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 in entrata e in uscita dalla 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 cos'è un SDK e il suo rapporto con le API.
Gli SDK di Looker contengono tutti gli endpoint API che potresti voler o dover utilizzare e sono confezionati in modo da consentirti di interagire facilmente con Looker utilizzando il linguaggio di programmazione che preferisci. Le funzioni ti consentono di eseguire le seguenti attività:
- Inviare dati a Looker
- Recuperare i 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. Passauser_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 utilizzi un IDE come Visual Studio Code e fai clic con il tasto Comando (F12 nelle impostazioni predefinite di Visual Studio Code) e poi selezioni Vai alle definizioni, puoi visualizzare tutti i metodi e tutti i parametri accettati o restituiti dai metodi. In alternativa, puoi visualizzarli nel repository GitHub dell'SDK. Cerca i metodi e i file di modello.
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 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 anche 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 trasmetti nell'ambito della chiamata API. Alcuni metodi forniscono dati, altri li inviano a Looker, altri ancora li aggiornano e altri li eliminano o rimuovono da Looker.
| Azione | Metodo |
| Crea |
POST
|
| Leggi |
GET
|
| Aggiorna |
PUT
|
| Elimina |
DELETE
|
Iniziamo a fare curling. Per informazioni di base, Zendesk offre un ottimo tutorial, Installing and using cURL.
Per iniziare a effettuare chiamate HTTP all'API Looker, la prima cosa da fare è chiamare l'endpoint login dell'API Looker utilizzando l'ID client e il client secret. In questo modo viene creato un token di accesso. Quindi, prendi questo token di accesso e passalo a ogni chiamata. Il token di accesso garantisce che la chiamata provenga da un utente autorizzato.
Questa pagina utilizza alcune notazioni per indicare dove devi sostituire il testo nell'esempio di codice con le tue informazioni. Gli URL delle istanze ospitate da Looker hanno il formatohttps://<hostname>.<subdomain>.<domain>.com. Quando vedi questa notazione negli esempi in 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<value>nell'esempio di codice. Ad esempio, nel seguente codice, dove viene visualizzatoclient_id=<value>&client_secret=<value>, sostituisci il primo<value>con il tuoclient_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 indica che Looker riconosce le tue credenziali API. Il token viene restituito con un valore expires_in, che indica la durata della validità del token. Spesso è di circa 60 minuti (3600 secondi).
Ora che hai un token di accesso, puoi effettuare chiamate. Tutti gli endpoint sono elencati per versione dell'API nella documentazione di riferimento dell'API Looker 4.0. Ricorda che il sito della community di Looker è un'ottima risorsa per chiedere ad altri utenti di Looker come sfruttano l'API, per imparare le best practice o per condividere con altri utenti i successi ottenuti con l'API.
Supponiamo che tu voglia creare un nuovo utente. Per farlo:
- Scrivi una richiesta curl
POSTche trasmetta il tuo token per comunicare a Looker che sei autorizzato. - Includi un corpo, in questo caso formattato come JSON, per indicare a Looker gli attributi che vuoi che abbia il nuovo utente. Esistono alcuni campi obbligatori per le chiamate API, quindi consulta la documentazione di 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 sta per intestazione e -d sta per dati. Per maggiori informazioni sui comandi curl, consulta questo gist di GitHub.
Hai appena creato un utente con nome, cognome e indirizzo email con i valori che hai inserito in precedenza.
E se volessi scrivere questo in uno script, in modo da 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, 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 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). La stessa procedura si applica a uno strumento di sviluppo software come alle richieste HTTP. Il primo passaggio consiste nell'accedere con il client secret e l'ID client. Quindi, memorizza il token di accesso come token di tipo 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 generare la richiesta per te. Eseguirà 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, vai avanti e prova le varie funzionalità. Tuttavia, tieni presente che, sebbene l'utilizzo dell'API possa contribuire ad automatizzare processi come la creazione o la riassegnazione di una pianificazione dopo che un utente ha lasciato la tua azienda, un utilizzo improprio dell'API può danneggiare un'istanza.
Alcune cose 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 annullate facilmente.
- Le chiamate API aumentano l'utilizzo dell'istanza, quindi prova a pianificarle al di fuori delle ore di punta per ottenere prestazioni ottimali.
- Esiste un limite di file aperti su ogni server di istanza, quindi è possibile arrestare in modo anomalo 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 a cui altri utenti possono accedere.
Se hai una domanda o vuoi condividere un'idea interessante, consulta la community di Looker. Non esitare a comunicarci se c'è qualcosa che possiamo migliorare o se vuoi che aggiungiamo altri esempi alla nostra documentazione.