Grâce à l'explorateur d'API de Looker, les utilisateurs peuvent tester les appels d'API presque instantanément sans avoir à écrire une seule ligne de code. Si vous avez installé l'extension API Explorer depuis la place de marché Looker, vous pouvez cliquer sur API Explorer (Explorateur d'API) dans le menu Applications (Applications) de Looker pour ouvrir l'explorateur d'API et afficher la documentation actuelle de l'API. Si vous n'avez pas installé l'extension Explorateur d'API, vous pouvez l'installer depuis la section Applications de la place de marché Looker.
Grâce à API Explorer, vous avez peut-être trouvé le meilleur workflow pour créer dynamiquement une analyse, mettre à jour la requête sous-jacente et la planifier pour différents partenaires de votre entreprise. La question suivante qui se pose souvent est la suivante : comment exécuter ces appels ou fonctions en dehors d'API Explorer ? Il existe trois façons courantes d'accéder à l'API:
- Kits de développement logiciel (SDK) de l'API Looker
- Requêtes HTTP
- Outils de développement logiciel
Cette page explique comment utiliser ces méthodes.
Avant de commencer: Authentification et ports
Quelle que soit la manière dont vous accédez à l'API Looker, vous devez d'abord disposer de deux informations: votre authentification API personnelle (sous la forme d'un ID client et d'un secret client) et le numéro de port utilisé par votre instance Looker.
Pour trouver un ID client et un code secret client:
- Si vous êtes administrateur Looker, accédez à la page Utilisateurs de l'interface utilisateur de Looker pour l'utilisateur qui vous intéresse, puis à Modifier les clés.
- Si vous n'êtes pas administrateur Looker, votre administrateur Looker vous a fourni votre ID client et votre code secret client.
Pour les instances Looker hébergées sur Google Cloud ou Microsoft Azure, ainsi que pour les instances hébergées sur Amazon Web Services (AWS) et créées le 07/07/2020 ou après, le chemin d'accès par défaut de l'API Looker utilise le port 443. Pour les instances Looker hébergées sur AWS et créées avant le 07/07/2020, le chemin d'accès par défaut de l'API Looker utilise le port 19999.
Si vous hébergez votre propre instance, demandez à votre administrateur système de vous indiquer le numéro de port. Il peut être défini dans le champ URL hôte de l'API du panneau d'administration de Looker. Pour le vérifier, accédez au menu déroulant Admin (Administration) dans Looker, puis sélectionnez API (API).
Pour en savoir plus sur les ports, consultez la page de documentation Premiers pas avec l'API Looker. Les exemples suivants utilisent un port d'API de 19999, mais vous devez vérifier le port utilisé par votre instance.
Option 1: Utiliser un kit de développement logiciel (SDK) Looker
Looker propose des SDK clients officiels de l'API Looker en Python, Ruby, TypeScript et JavaScript, Swift, Kotlin et R. Vous trouverez le code source et des exemples dans le dépôt GitHub sdk-examples
de Looker.
Un SDK fournit des outils ou des bibliothèques qui permettent aux développeurs d'interagir avec une plate-forme ou une application donnée. Dans ce cas, les SDK de Looker contiennent généralement des API. Pour reprendre un exemple du développeur Web et auteur Kristopher Sandoval, "les API sont des lignes téléphoniques qui permettent de communiquer à l'intérieur et à l'extérieur de la maison. Le SDK est la maison elle-même et tout son contenu." Dans son excellent article What Is the Difference Between an API and a SDK? (Quelle est la différence entre une API et un SDK ?), il explique ce qu'est un SDK et comment il se rapporte aux API.
Les SDK de Looker contiennent tous les points de terminaison d'API que vous souhaitez ou devez utiliser. Ils sont empaquetés de manière à vous permettre d'interagir facilement avec Looker à l'aide du langage de programmation de votre choix. Les fonctions vous permettent d'effectuer les tâches suivantes:
- Envoyer des données à Looker
- Obtenir des données à partir de Looker
- Mettre à jour des données dans Looker
- Supprimer des données dans Looker
Voici un exemple de mise à jour d'un utilisateur avec le SDK Python:
-
Initialisez la session avec
looker_sdk.init
. -
Mettez à jour l'utilisateur avec
sdk.update_user
. Vous transmettezuser_id
pour spécifier l'utilisateur que vous souhaitez mettre à jour. -
Utilisez
models.WriteUser
pour spécifier comment vous souhaitez mettre à jour l'utilisateur.
#### 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)
Lorsque vous utilisez l'un de nos SDK, si vous utilisez un IDE tel que Visual Studio Code et que vous effectuez un clic avec la touche commande (F12 dans les paramètres par défaut de Visual Studio Code), puis sélectionnez Accéder aux définitions, vous pouvez voir toutes les méthodes et tous les paramètres acceptés ou renvoyés par les méthodes. Vous pouvez également les consulter dans le dépôt GitHub du SDK. Recherchez les méthodes et les fichiers de modèle.
Option 2: Requêtes HTTP avec curl ou une bibliothèque de requêtes
Que faire si vous ne souhaitez pas écrire de script ni passer des mois ou des années à apprendre un nouveau langage de programmation ? Dans ce cas, vous pouvez utiliser curl pour effectuer des requêtes HTTP afin d'utiliser l'API Looker.
Une requête HTTP envoie un message à une destination, qui peut être un serveur, un téléphone ou même votre smart TV. Il existe plusieurs types de requêtes HTTP. La façon dont vous utilisez ces requêtes avec l'API Looker dépend de la nature de la méthode que vous transmettez dans l'appel d'API. Certaines méthodes vous fournissent des données, d'autres en envoient à Looker, d'autres les mettent à jour, et d'autres les suppriment ou les retirent de Looker.
Action | Méthode |
Créer |
POST
|
Lire |
GET
|
Mettre à jour |
PUT
|
Supprimer |
DELETE
|
Commençons à jouer au curling. Pour en savoir plus, consultez le tutoriel de Zendesk Installer et utiliser cURL.
Pour commencer à effectuer des appels HTTP à l'API Looker, vous devez d'abord appeler le point de terminaison login
de l'API Looker à l'aide de votre ID client et de votre secret client. Un jeton d'accès est alors créé. Vous pouvez ensuite transmettre ce jeton d'accès à chaque appel. Le jeton d'accès garantit que l'appel provient d'un utilisateur autorisé.
Cette page utilise quelques notations pour indiquer où vous devez remplacer le texte de l'exemple de code par vos informations. Les URL d'instance hébergées par Looker prennent la formehttps://<hostname>.<subdomain>.<domain>.com
. Lorsque vous voyez cette notation dans les exemples de cette page, remplacez la section<hostname>.<subdomain>.<domain>.com
par l'URL de votre instance Looker. De plus, nous utilisons la notation<value>
pour indiquer où vous devez saisir la valeur appropriée, en remplaçant<value>
dans l'exemple de code. Par exemple, dans le code suivant, oùclient_id=<value>&client_secret=<value>
s'affiche, remplacez le premier<value>
par votreclient_id
et le second<value>
par votreclient_secret
.
Voici la commande curl pour obtenir le jeton d'accès:
curl -d "client_id=<value>&client_secret=<value>" https://<hostname>.<subdomain>.<domain>.com:19999/login
Voici la réponse :
{"access_token":"ABCDEFGHIJLMNOP1234","token_type":"Bearer","expires_in":3600}
La réception du jeton vous indique que Looker reconnaît vos identifiants d'API. Le jeton est renvoyé avec une valeur expires_in
, qui indique la durée pendant laquelle le jeton est valide. Elle est souvent d'environ 60 minutes (3 600 secondes).
Maintenant que vous disposez d'un jeton d'accès, vous pouvez passer tous les appels que vous souhaitez. Tous les points de terminaison sont listés par version d'API dans la documentation de référence sur l'API Looker 4.0. N'oubliez pas que le site de la communauté Looker est une excellente ressource pour poser des questions à d'autres utilisateurs de Looker sur la façon dont ils exploitent l'API, pour découvrir les bonnes pratiques ou pour partager vos succès avec d'autres utilisateurs.
Supposons que vous souhaitiez créer un utilisateur. Pour ce faire, procédez comme suit :
- Écrivez une requête
POST
curl qui transmet votre jeton pour indiquer à Looker que vous êtes autorisé. - Incluez un corps, au format JSON dans ce cas, pour indiquer à Looker les attributs que vous souhaitez que votre nouvel utilisateur possède. (Certains champs sont obligatoires pour les appels d'API. Veuillez donc consulter la documentation de référence sur l'API Looker 4.0.)
- Terminez la notation curl par le point de terminaison que vous souhaitez utiliser, dans ce cas
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
correspond à l'en-tête, et -d
aux données. Pour en savoir plus sur les commandes curl, consultez cet extrait GitHub.
Vous venez de créer un utilisateur avec le prénom, le nom et l'adresse e-mail que vous avez saisis précédemment.
Que faire si vous souhaitez écrire cela dans un script afin de ne pas avoir à écrire ces commandes chaque fois que vous souhaitez effectuer ce workflow ? Vous pouvez utiliser un langage de programmation et une bibliothèque comme la bibliothèque requests
de Python.
Par exemple, voici un script qui utilise la bibliothèque requests
pour obtenir un look à l'aide de l'ID de look (<value>
dans l'appel looks
), appliquer un nouveau filtre, puis télécharger les résultats au format 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)
Option 3: Outils de développement logiciel
Des outils tels que Postman ou Paw permettent aux utilisateurs d'interagir ou d'exploiter des points de terminaison d'API via une interface utilisateur graphique (IUG). Le même processus s'applique à un outil de développement logiciel qu'aux requêtes HTTP. La première étape consiste à vous connecter avec votre code secret client et votre ID client. Stockez ensuite le jeton d'accès en tant que jeton de support pour autoriser les appels d'API suivants, comme indiqué ici dans Postman.
Postman ou d'autres outils de développement logiciel (comme Paw) vous permettent de spécifier l'autorisation, le corps, les paramètres et les en-têtes dans leurs UI, puis de générer la requête à votre place. Ils exécuteront également le point de terminaison lorsque vous appuierez sur Envoyer.
Allez-y ! (mais faites attention)
Maintenant que vous pouvez utiliser l'API Looker via un SDK, une requête HTTP et un outil de développement logiciel, lancez-vous et testez-la ! Toutefois, sachez que, bien que l'utilisation de l'API puisse vous aider à automatiser des processus tels que la création ou la réaffectation d'un planning après le départ d'un utilisateur de votre entreprise, une utilisation incorrecte de l'API peut endommager une instance.
Voici quelques points généraux à retenir:
- Soyez prudent lorsque vous modifiez des autorisations ou supprimez des utilisateurs, en particulier de manière groupée. Il est possible de supprimer ou de bloquer de nombreux utilisateurs, y compris des administrateurs, et de telles actions ne sont pas facilement réversibles.
- Les appels d'API augmentent l'utilisation des instances. Essayez donc de les planifier en dehors des heures de pointe pour optimiser les performances.
- Une limite de fichiers ouverts s'applique à chaque serveur d'instance. Il est donc possible de planter une instance en raison d'une utilisation irresponsable de l'API.
- Testez les workflows et les fonctions à petite échelle avant de les ajouter en production.
- Ne partagez jamais vos identifiants API ni ne les laissez dans un fichier auquel d'autres utilisateurs peuvent accéder.
Si vous avez une question ou souhaitez partager une idée, consultez la communauté Looker. N'hésitez pas à nous indiquer ce que nous pouvons améliorer ou si vous souhaitez ajouter d'autres exemples à notre documentation.