Phenquestions
Les gens de GitHub, et les développeurs tiers, ne peuvent pas gérer toute cette complexité sans une interface commune. Cette interface commune est ce que nous appelons l'API GitHub. Chaque utilitaire GitHub comme un cli, une interface utilisateur Web, etc. utilise cette interface commune pour gérer les ressources (les ressources étant des entités telles que des référentiels, des clés ssh, etc.).
Dans ce tutoriel, nous allons apprendre quelques bases sur la façon dont on s'interface avec une API en utilisant GitHub API v3 et Python3. La dernière v4 de l'API GitHub vous oblige à vous renseigner sur GraphQL, ce qui entraîne une courbe d'apprentissage plus raide. Je vais donc m'en tenir à la version trois qui est toujours active et assez populaire.
Comment parler à une API Web
Les API Web vous permettent d'utiliser tous les services offerts par une application Web, comme GitHub, par programmation en utilisant le langage de votre choix. Par exemple, nous allons utiliser Python pour notre cas d'utilisation, ici. Techniquement, vous pouvez faire tout ce que vous faites sur GitHub en utilisant l'API mais nous nous limiterons à lire uniquement les informations accessibles au public.
Votre programme Python parlera à une API de la même manière que votre navigateur parlera à un site Web. C'est-à-dire principalement via des requêtes HTTPS. Ces requêtes contiendront différentes « parties », à partir de la méthode de la requête [GET, POST, PUT, DELETE], l'URL elle-même, une chaîne de requête, un en-tête HTTP et un corps ou une charge utile. La plupart d'entre eux sont facultatifs. Nous devrons cependant fournir une méthode de demande et l'URL à laquelle nous faisons la demande.
Qu'est-ce que c'est et comment ils sont représentés dans une requête HTTPS est quelque chose que nous verrons lentement lorsque nous commencerons à écrire des scripts Python pour interagir avec GitHub.
Un exemple
L'ajout de clés SSH à un serveur nouvellement créé est toujours un processus maladroit. Écrivons un script Python qui récupérera vos clés SSH publiques depuis GitHub et l'ajoutera au fichier allowed_keys sur n'importe quel serveur Linux ou Unix sur lequel vous exécutez ce script. Si vous ne savez pas comment générer ou utiliser des clés SSH, voici un excellent article sur la façon de faire exactement cela. Je suppose que vous avez créé et ajouté vos propres clés SSH publiques à votre compte GitHub.
Une implémentation Python très simple et naïve pour réaliser la tâche que nous avons décrite ci-dessus est illustrée ci-dessous :
demandes d'importationimporter le système d'exploitation
# Obtenir l'entrée de l'utilisateur
unix_user = input("Entrez votre nom d'utilisateur Unix : ")
github_user = input("Entrez votre nom d'utilisateur GitHub : ")
# S'assurer .Le répertoire ssh existe et ouvre le fichier enabled_keys
ssh_dir = '/home/'+unix_user+'/.chut/'
sinon os.chemin.existe(ssh_dir):
système d'exploitation.makedirs(ssh_dir)
authorized_keys_file = open(ssh_dir+'authorized_keys','a')
# Envoi d'une requête à l'API GiHub et stockage de la réponse dans une variable nommée 'response'
api_root = "https://api.github.com"
request_header = 'Accepter':'application/vnd.github.v3+json'
réponse = demandes.get(api_root+'/users/'+github_user+'/keys', headers = request_header)
## Traitement de la réponse et ajout des clés au fichier allowed_keys
pour moi en réponse.json() :
fichier_clés_autorisé.écrire(i['clé']+'\n')
Ignorons la gestion des fichiers Python et divers détails et examinons strictement la demande et la réponse. Nous avons d'abord importé le module de requêtes d'import des requêtes cette bibliothèque nous permet de faire des appels API très facilement. Cette bibliothèque est également l'un des meilleurs exemples d'un projet open source bien fait. Voici le site officiel au cas où vous voudriez voir la doc de plus près.
Ensuite, nous définissons une variable api_root.
api_root = "https://api.github.com"Il s'agit de la sous-chaîne commune à toutes les URL vers lesquelles nous effectuerons des appels d'API. Donc au lieu de taper "https://api.github.com" à chaque fois que nous devons accéder à https://api.github.com/users ou https://api.github.fr/utilisateurs/racine_api+'/utilisateurs/' ou alors racine_api+'/users/ comme indiqué dans l'extrait de code.
Ensuite, nous définissons l'en-tête dans notre requête HTTPS, indiquant que les réponses sont destinées à l'API version 3 et doivent être au format JSON. GitHub respecterait ces informations d'en-tête.
1. OBTENIR la demande
Alors maintenant que nous avons notre URL et (facultatif) les informations d'en-tête stockées dans différentes variables, il est temps de faire la demande.
réponse = demandes.get(api_root+'/users/'+github_user+'/keys', headers = request_header)La demande est de type 'get' car nous lisons des informations accessibles au public de GitHub. Si vous écriviez quelque chose sous votre compte utilisateur GitHub, vous utiliseriez POST. De même, d'autres méthodes sont destinées à d'autres fonctions telles que DELETE pour la suppression de ressources telles que les référentiels.
2. Point de terminaison de l'API
Le point de terminaison de l'API que nous recherchons est :
https://api.github.fr/utilisateurs/Chaque ressource GitHub a son propre point de terminaison d'API. Vos demandes de GET, PUT, DELETE, etc. sont ensuite effectuées sur le point de terminaison que vous avez fourni. Selon le niveau d'accès dont vous disposez, GitHub vous autorisera alors à traiter cette demande ou la refusera.
La plupart des organisations et des utilisateurs sur GitHub définissent une énorme quantité d'informations lisibles et publiques. Par exemple, mon compte utilisateur GitHub possède quelques référentiels publics et des clés SSH publiques auxquelles tout le monde peut accéder en lecture (même sans compte utilisateur GitHub). Si vous souhaitez avoir un contrôle plus précis de votre compte personnel, vous pouvez générer un « jeton d'accès personnel » pour lire et écrire des informations privilégiées stockées dans votre compte GitHub personnel. Si vous écrivez une application tierce, destinée à être utilisée par des utilisateurs autres que vous, alors un jeton OAuth dudit utilisateur est ce dont votre application aurait besoin.
Mais comme vous pouvez le voir, de nombreuses informations utiles sont accessibles sans créer de jeton.
3. Réponse
La réponse est renvoyée par le serveur d'API GitHub et est stockée dans la variable nommée response. L'intégralité de la réponse peut être lue de plusieurs manières, comme documenté ici. Nous avons explicitement demandé du contenu de type JSON à GitHub, nous traiterons donc la demande comme s'il s'agissait de JSON. Pour ce faire, nous appelons la méthode json() du module de requêtes qui la décodera en objets natifs Python comme les dictionnaires et les listes.
Vous pouvez voir les clés ajoutées au fichier allowed_keys dans cette boucle for :
pour moi en réponse.json() :fichier_clés_autorisé.écrire(i['clé']+'\n')
Si vous imprimez la réponse.json(), vous remarquerez qu'il s'agit d'une liste Python avec des dictionnaires Python comme membres. Chaque dictionnaire a une clé nommée « clé » avec votre clé SSH publique comme valeur de cette clé. Vous pouvez donc ajouter ces valeurs une par une à votre fichier allowed_keys. Et maintenant, vous pouvez facilement vous connecter en SSH à votre serveur à partir de n'importe quel ordinateur possédant l'une des clés SSH privées correspondant à l'une des clés publiques que nous venons d'ajouter.
Explorer plus loin
Beaucoup de travail avec les API implique une inspection minutieuse de la documentation de l'API elle-même plus que l'écriture de lignes de code. Dans le cas de GitHub, la documentation est l'une des meilleures de l'industrie. Mais lire les documents d'API et passer des appels d'API à l'aide de Python est plutôt inintéressant en tant qu'activité autonome.
Avant d'aller plus loin, je vous recommande de proposer une tâche que vous souhaitez effectuer en utilisant Python sur votre compte GitHub. Essayez ensuite de l'implémenter en lisant uniquement les documentations officielles fournies par Python, ses bibliothèques dépendantes et GitHub. Cela vous aidera également à adopter un état d'esprit plus sain dans lequel vous comprenez ce qui se passe dans votre code et l'améliorez progressivement au fil du temps.
