Phenquestions
Mensen bij GitHub, en zowel externe ontwikkelaars, kunnen onmogelijk al deze complexiteit beheren zonder een gemeenschappelijke interface. Deze gemeenschappelijke interface is wat we de GitHub API noemen. Elk GitHub-hulpprogramma zoals een cli, web-UI, enz. gebruikt deze ene gemeenschappelijke interface om bronnen te beheren (resources zijn entiteiten zoals repositories, ssh-sleutels, enz.).
In deze zelfstudie leren we een paar basisprincipes van hoe een interface werkt met een API met behulp van GitHub API v3 en Python3. De nieuwste v4 van GitHub API vereist dat je meer leert over GraphQL, wat resulteert in een steilere leercurve. Dus ik blijf bij alleen versie drie, die nog steeds actief en behoorlijk populair is.
Praten met een web-API
Met web-API's kunt u alle services die worden aangeboden door een web-app, zoals GitHub, programmatisch gebruiken in de taal van uw keuze. We gaan bijvoorbeeld Python gebruiken voor onze use case, hier:. Technisch gezien kun je alles doen wat je doet op GitHub met behulp van de API, maar we zullen ons beperken tot het alleen lezen van de openbaar toegankelijke informatie.
Je Python-programma praat met een API op dezelfde manier als je browser met een website praat. Dat wil zeggen, meestal via HTTPS-verzoeken. Deze verzoeken zullen verschillende 'delen' bevatten, te beginnen met de methode van het verzoek [GET, POST, PUT, DELETE], de URL zelf, een querystring, een HTTP-header en een body of een payload. De meeste hiervan zijn optioneel. We moeten echter een verzoekmethode en de URL opgeven waarnaar we het verzoek doen.
Wat dit zijn en hoe ze worden weergegeven in een HTTPS-verzoek, zullen we langzaam zien als we beginnen met het schrijven van Python-scripts om te communiceren met GitHub.
Een voorbeeld
SSH-sleutels toevoegen aan een nieuw gemaakte server is altijd een onhandig proces. Laten we een Python-script schrijven dat uw openbare SSH-sleutels van GitHub ophaalt en het toevoegt aan het bestand Authorized_keys op elke Linux- of Unix-server waarop u dit script uitvoert. Als u niet weet hoe u SSH-sleutels moet genereren of gebruiken, vindt u hier een uitstekend artikel over hoe u dat precies kunt doen. Ik ga ervan uit dat je je eigen openbare SSH-sleutels hebt gemaakt en toegevoegd aan je GitHub-account.
Een zeer eenvoudige en naïeve Python-implementatie om de hierboven beschreven taak te bereiken, is zoals hieronder weergegeven:
importverzoekenimporteer os
# Gebruikersinvoer krijgen
unix_user = input("Vul uw Unix-gebruikersnaam in: ")
github_user = input("Vul uw GitHub-gebruikersnaam in: ")
# Controleren .ssh-map bestaat en het bestand Authorized_keys wordt geopend
ssh_dir = '/home/'+unix_user+'/.ssh/'
zo niet os.pad.bestaat (ssh_dir):
os.makedirs(ssh_dir)
Authorized_keys_file = open(ssh_dir+'authorized_keys','a')
# Een verzoek verzenden naar de GiHub API en het antwoord opslaan in een variabele met de naam 'respons'
api_root = "https://api.github.kom"
request_header = 'Accepteren':'applicatie/vnd.github.v3+json'
reactie = verzoeken.get(api_root+'/users/'+github_user+'/keys', headers = request_header)
## Het antwoord verwerken en sleutels toevoegen aan het bestand Authorized_keys
voor ik als antwoord.json():
geautoriseerde_sleutels_bestand.schrijven(i['key']+'\n')
Laten we de verwerking van Python-bestanden en diverse details negeren en strikt naar het verzoek en de reactie kijken. Eerst hebben we de aanvraagmodule importverzoeken geïmporteerd. Met deze bibliotheek kunnen we heel gemakkelijk API-aanroepen doen. Deze bibliotheek is ook een van de beste voorbeelden van een goed uitgevoerd open source-project done. Hier is de officiële site voor het geval je de documenten van dichterbij wilt bekijken.
Vervolgens stellen we een variabele in api_root.
api_root = "https://api.github.kom"Dit is de algemene substring in alle URL's waarnaar we API-aanroepen zullen doen. Dus in plaats van “https://api.github.com” elke keer dat we toegang nodig hebben tot https://api.github.com/gebruikers of https://api.github.com/gebruikers/api_root+'/users/' of api_root+'/gebruikers/ zoals weergegeven in het codefragment.
Vervolgens stellen we de header in ons HTTPS-verzoek in, wat aangeeft dat reacties bedoeld zijn voor versie 3 API en JSON-geformatteerd moeten zijn. GitHub zou deze header-informatie respecteren.
1. GET-verzoek
Dus nu we onze URL en (een optionele) header-informatie hebben opgeslagen in verschillende variabelen, is het tijd om het verzoek in te dienen.
reactie = verzoeken.get(api_root+'/users/'+github_user+'/keys', headers = request_header)Het verzoek is van het type 'get' omdat we openbaar beschikbare informatie van GitHub lezen. Als je iets zou schrijven onder je GitHub-gebruikersaccount, zou je POST gebruiken. Evenzo zijn andere methoden bedoeld voor andere functies, zoals DELETE is voor het verwijderen van bronnen zoals repositories.
2. API-eindpunt
Het API-eindpunt waar we naar streven is:
https://api.github.com/gebruikers/Elke GitHub-bron heeft zijn eigen API-eindpunt. Uw verzoeken voor GET, PUT, DELETE, enz. worden vervolgens gedaan tegen het eindpunt dat u heeft opgegeven. Afhankelijk van het toegangsniveau dat je hebt, zal GitHub je dan ofwel toestaan om door te gaan met dat verzoek of het weigeren.
De meeste organisaties en gebruikers op GitHub stellen een enorme hoeveelheid informatie leesbaar en openbaar in. Mijn GitHub-gebruikersaccount heeft bijvoorbeeld een aantal openbare repositories en openbare SSH-sleutels die iedereen kan lezen (zelfs zonder een GitHub-gebruikersaccount). Als u een meer fijnmazige controle over uw persoonlijke account wilt hebben, kunt u een "Personal Access Token" genereren om bevoorrechte informatie te lezen en te schrijven die is opgeslagen in uw persoonlijke GitHub-account. Als u een app van derden schrijft die bedoeld is om door andere gebruikers dan u te worden gebruikt, heeft uw app een OAuth-token van de genoemde gebruiker nodig.
Maar zoals u kunt zien, is veel nuttige informatie toegankelijk zonder een token te maken.
3. Reactie
Het antwoord wordt geretourneerd door de GitHub API-server en wordt opgeslagen in de variabele met de naam respons. Het volledige antwoord kan op verschillende manieren worden gelezen, zoals hier gedocumenteerd. We hebben expliciet om JSON-type inhoud van GitHub gevraagd, dus we zullen het verzoek verwerken alsof het JSON is. Om dit te doen roepen we de json()-methode aan vanuit de request-module die deze zal decoderen in native Python-objecten zoals woordenboeken en lijsten.
U kunt zien dat de sleutels worden toegevoegd aan het bestand Authorized_keys in deze for-lus:
voor ik als antwoord.json():geautoriseerde_sleutels_bestand.schrijven(i['key']+'\n')
Als u het antwoord afdrukt.json() object, zult u merken dat het een Python-lijst is met Python-woordenboeken als leden. Elk woordenboek heeft een sleutel met de naam 'sleutel' met uw openbare SSH-sleutel als waarde voor die sleutel. U kunt deze waarden dus één voor één toevoegen aan uw Authorized_keys-bestand. En nu kun je eenvoudig SSH naar je server sturen vanaf elke computer die een van de privé SSH-sleutels heeft die overeenkomen met een van de openbare sleutels die we zojuist hebben toegevoegd.
Verder verkennen
Veel werk met API's omvat een zorgvuldige inspectie van de API-documentatie zelf, meer dan het schrijven van regels code. In het geval van GitHub is de documentatie een van de beste in de branche. Maar het lezen van API-documenten en het doen van API-aanroepen met Python is nogal oninteressant als een op zichzelf staande activiteit.
Voordat je verder gaat, raad ik je aan om één taak te bedenken die je wilt uitvoeren met Python op je GitHub-account. Probeer het vervolgens te implementeren door alleen de officiële documentatie te lezen die wordt geleverd door Python, de afhankelijke bibliotheken en GitHub. Dit zal je ook helpen om een gezondere mindset aan te nemen, waarbij je begrijpt wat er in je code gebeurt en deze geleidelijk verbetert in de loop van de tijd.
