Explication d'un script Python pour l'API Cato

Ce programme d'exemple est court et n'inclut aucune logique de prise de décision ou de code pour répéter les actions.  Il aurait pu être encore plus court en combinant certaines des lignes de code en une seule ligne.  Les lignes de code supplémentaires ont été incluses pour faciliter l'explication de ce qui se passe.

# Importer le code de la bibliothèque Python
import os
import urllib.request
import ssl
import json

# Obtenir la clé API Cato d'une variable d'environnement
cato_api_key = os.getenv("CATO_API_KEY")

# Créer la requête GraphQL à envoyer
get_total_admins = '''{
    admins (accountID: 12345) {
        total        
    }
}'''
graphql_query = {'query': get_total_admins}

# Construire la requête http
cato_api_url = "https://api.catonetworks.com/api/v1/graphql2"
headers = {'x-api-key': cato_api_key,
           'Content-Type':'application/json'}
unverified_ctx = ssl._create_unverified_context()
json_post = json.dumps(graphql_query)
json_post_encoded = json_post.encode()
request = urllib.request.Request(url=cato_api_url, data=json_post_encoded, headers=headers)

# Envoyer la requête et convertir la réponse en un dictionnaire Python
response = urllib.request.urlopen(request, context=unverified_ctx, timeout=30)
json_response_encoded = response.read()
json_response = json_response_encoded.decode()
get_admins_total_result = json.loads(json_response)

# Extraire le total des données retournées et l'imprimer
 total = get_admins_total_result['data']['admins']['total']
print('Le nombre total d'administrateurs défini pour votre compte est : {}'.format(total))

Le schéma fourni ci-dessous montre la séquence d'événements qui se produisent lorsque le programme est exécuté :

L'une des raisons pour lesquelles Python est utilisé pour le programme d'exemple est la disponibilité d'un ensemble riche de bibliothèques.  Ces bibliothèques fournissent des fonctions et des objets capables de gérer un large éventail de tâches.  Nous allons maintenant passer en revue chaque bibliothèque importée et fournir des notes pour expliquer pourquoi elle est nécessaire.

import os

import urllib.request

import ssl

import json

Cette ligne de code utilise la fonction de bibliothèque getenv pour lire la clé API à partir d'une variable d'environnement et l'assigner à une variable.

cato_api_key = os.getenv("CATO_API_KEY")

Le serveur GraphQL de Cato s'attend à recevoir cette clé dans un en-tête HTTP.  La clé n'est pas fournie dans le document JSON car la spécification GraphQL n'inclut pas l'autorisation dans la norme.  Inclure l'autorisation dans le document JSON serait une violation de la spécification.  La clé API Cato est générée via l'application de gestion Cato.  Pour plus d'informations sur la création d'une clé API, voir Génération de clés API pour l'API Cato.

Les deux prochaines lignes de code créent un répertoire Python contenant une paire clé/valeur.  La valeur de l'entrée est construite à l'aide d'une chaîne multi-lignes Python qui définit la requête qui sera envoyée au serveur GraphQL.

get_total_admins = '''{
    admins (accountID: 12345) {
        total    
    }
}'''
graphql_query = {'query': get_total_admins}

Le serveur GraphQL de Cato interprétera cette chaîne comme signifiant : exécuter la fonction get_total_admins, en lui passant deux arguments (accountID et type) et en retournant uniquement le nombre "total" d'entités.  Ou dit plus directement, "Retourner le nombre total d'entités d'administrateurs qui sont définies pour le compte d'exemple # 12345".  Cet exemple spécifique de l'appel API admins illustre un avantage important d'une API GraphQL

En fait, l'appel admins peut renvoyer beaucoup plus de données.  Par exemple, il est possible pour une application de demander à admins de retourner des détails sur chaque administrateur.  Cependant, cette application a seulement besoin de connaître le nombre total d'administrateurs.  Cette caractéristique de GraphQL évite ce qu'on appelle le sur-collecte et peut grandement simplifier le code nécessaire pour mettre en œuvre l'application.

Dans cette section du programme, un objet de requête est construit.  Cet objet sera utilisé pour envoyer l'appel API au serveur GraphQL en utilisant HTTPS. Cet objet de requête nécessite des informations fournies par plusieurs autres objets qui doivent être créés en premier.   Tout d'abord, un objet chaîne simple est construit pour contenir l'URL du serveur GraphQL que l'objet de requête enverra la requête à.

cato_api_url = "https://api.catonetworks.com/api/v1/graphql2"

Ensuite, un dictionnaire est créé qui définit deux en-têtes HTTP.  Ces en-têtes sont utilisés par l'objet de requête pour construire une requête HTTP POST que le serveur GraphQL acceptera.  Sans ces en-têtes, les requêtes HTTP POST seraient rejetées par le serveur.

headers = {'x-api-key': cato_api_key,           
           'Content-Type':'application/json'}

La prochaine ligne de code crée un objet de contexte SSL. Python utilise cet objet pour déterminer comment il doit crypter les requêtes HTTP et les envoyer en utilisant la sécurité au niveau du transport (TLS). Ici, nous créons un objet de contexte SSL qui ne vérifie pas les certificats. Cela a été fait pour éviter les erreurs de certificats dans les réseaux soumis à une inspection TLS en amont.

unverified_ctx = ssl._create_unverified_context()

Les deux lignes de code suivantes convertissent le dictionnaire Python contenant l'appel API Cato en une chaîne et codent cette chaîne en octets.  La deuxième étape est nécessaire pour permettre la transmission de la chaîne sur le réseau.

json_post = json.dumps(graphql_query)
json_post_encoded = json_post.encode()

Enfin, l'objet de requête est créé et le programme est maintenant prêt à envoyer l'appel get_total_admins au serveur.

request = urllib.request.Request(url=cato_api_url, data=json_post_encoded, headers=headers)

Ici, le programme envoie la requête au serveur GraphQL en appelant la fonction urlopen de la bibliothèque urllib.  Appeler cette fonction résultera en le retour d'un objet HTTPResponse.  

response = urllib.request.urlopen(request, context=unverified_ctx, timeout=30)

L'objet retourné par la fonction urlopen inclut un champ de corps qui contient le document JSON retourné par le serveur.  Cela peut être extrait de l'objet en exécutant sa méthode read qui retourne un objet bytes.  Cet objet bytes est ensuite converti en un objet chaîne en appelant la méthode decode de l'objet bytes.

json_response_encoded = response.read()
json_response = json_response_encoded.decode()

Cette chaîne décodée contient un document JSON qui ressemblera à ceci :

{    
    "data" : {
         "admins" : {
              "total": 4
         }
    }
}

Comme vous le verrez, le format des données retournées ressemble beaucoup au format de la requête envoyée au serveur.  C'est intentionnel et constitue un autre avantage de l'utilisation de la spécification GraphQL pour implémenter une API.  Cette approche simplifie le codage de l'application en conservant les données retournées dans le même format que la requête.

La dernière ligne de code dans cette section du programme utilise la fonction de bibliothèque json 'loads' pour convertir le texte JSON retourné en un dictionnaire imbriqué Python.  

get_total_admin_result = json.loads(json_response)

Les deux dernières lignes du code extraient la valeur du champ total qui a été retourné par le serveur et l'impriment sur la console. 

total = get_total_admins_result['data']['get_total_admins']['total']
print('Le nombre total d'admins défini pour votre compte est : {}'.format(total)) 

La sortie ressemblera à ceci :

Le nombre total d'admins défini pour votre compte est : 4