Phenquestions
Människor på GitHub, och tredjepartsutvecklare, kan omöjligt hantera all denna komplexitet utan ett gemensamt gränssnitt. Det här gemensamma gränssnittet är vad vi kallar GitHub API. Varje GitHub-verktyg som ett cli, webbgränssnitt osv använder det här vanliga gränssnittet för att hantera resurser (resurser är enheter som förvar, ssh-nycklar, etc).
I den här handledningen lär vi oss några grundläggande om hur man gränssnitt med ett API med GitHub API v3 och Python3. Den senaste versionen av GitHub API kräver att du lär dig mer om GraphQL vilket resulterar i brantare inlärningskurva. Så jag kommer att hålla mig till bara version tre som fortfarande är aktiv och ganska populär.
Hur man pratar med ett webb-API
Webb-API: er är det som gör det möjligt för dig att använda alla tjänster som erbjuds av en webbapp, som GitHub, programmatiskt med ditt eget språk. Till exempel ska vi använda Python för vårt användningsfall här. Tekniskt kan du göra allt du gör på GitHub med API men vi kommer att begränsa oss till att bara läsa den offentligt tillgängliga informationen.
Ditt Python-program kommer att prata med ett API på samma sätt som din webbläsare pratar med en webbplats. Det vill säga, mestadels via HTTPS-förfrågningar. Dessa förfrågningar kommer att innehålla olika "delar", med start från metoden för begäran [GET, POST, PUT, DELETE], webbadressen i sig, en frågesträng, en HTTP-rubrik och en kropp eller en nyttolast. De flesta av dessa är valfria. Vi kommer dock att behöva ange en förfrågningsmetod och den webbadress som vi begär.
Vad dessa är och hur de representeras i en HTTPS-begäran är något vi ser långsamt när vi börjar skriva Python-skript för att interagera med GitHub.
Ett exempel
Att lägga till SSH-nycklar till en nyskapad server är alltid en klumpig process. Låt oss skriva ett Python-skript som hämtar dina offentliga SSH-nycklar från GitHub och lägger till det i filen authorised_keys på vilken Linux- eller Unix-server du kör det här skriptet. Om du inte vet hur man skapar eller använder SSH-nycklar, här är en utmärkt artikel om hur man gör exakt det. Jag antar att du har skapat och lagt till dina egna offentliga SSH-nycklar till ditt GitHub-konto.
En mycket enkel och naiv Python-implementering för att uppnå uppgiften som vi beskrivit ovan är som visas nedan:
importförfrågningarimportera os
# Få användarinmatning
unix_user = input ("Ange ditt Unix-användarnamn:")
github_user = input ("Ange ditt GitHub-användarnamn:")
# Ser till .ssh-katalog finns och öppnar filen authorised_keys
ssh_dir = '/ home /' + unix_user + '/.ssh / '
om inte os.väg.existerar (ssh_dir):
os.makedirs (ssh_dir)
auktoriserade_knappar_fil = öppen (ssh_dir + 'auktoriserade_knappar', 'a')
# Skicka en begäran till GiHub API och lagra svaret i en variabel med namnet 'svar'
api_root = "https: // api.github.com "
request_header = 'Acceptera': 'application / vnd.github.v3 + json '
svar = förfrågningar.få (api_root + '/ användare /' + github_user + '/ tangenter', rubriker = request_header)
## Bearbetar svaret och bifogar nycklar till filen author_keys
för jag som svar.json ():
auktoriserade_tangenter_fil.skriv (i ['key'] + '\ n')
Låt oss ignorera Python-filhantering och diverse detaljer och titta strikt på begäran och svaret. Först importerade vi förfrågningsmodulen importförfrågningar som det här biblioteket gör att vi kan ringa API-samtal mycket enkelt. Detta bibliotek är också ett av de bästa exemplen på ett open source-projekt gjort rätt. Här är den officiella webbplatsen om du vill titta närmare på dokumenten.
Därefter ställer vi in en variabel api_root.
api_root = "https: // api.github.com "Detta är det vanliga underlaget i alla webbadresser som vi kommer att ringa API-samtal till. Så istället för att skriva “https: // api.github.com ”varje gång vi behöver komma åt https: // api.github.com / användare eller https: // api.github.com / användare /api_root + '/ användare /' eller api_root + '/ användare / som visas i kodavsnittet.
Därefter ställer vi in rubriken i vår HTTPS-begäran, vilket indikerar att svaren är avsedda för version 3 API och ska vara JSON-formaterade. GitHub respekterar denna rubrikinformation.
1. FÅ begäran
Så nu när vi har vår URL och (en valfri) rubrikinformation lagrad i olika variabler är det dags att göra en begäran.
svar = förfrågningar.få (api_root + '/ användare /' + github_user + '/ tangenter', rubriker = request_header)Begäran är av typen "get" eftersom vi läser offentligt tillgänglig information från GitHub. Om du skrev något under ditt GitHub-användarkonto skulle du använda POST. På liknande sätt är andra metoder avsedda för andra funktioner som DELETE är för radering av resurser som arkiv.
2. API-slutpunkt
API-slutpunkten som vi strävar efter är:
https: // api.github.com / användare /Varje GitHub-resurs har sin egen API-slutpunkt. Dina önskemål om GET, PUT, DELETE, etc görs sedan mot den slutpunkt du angav. Beroende på vilken åtkomstnivå du har kommer GitHub att antingen låta dig gå igenom den begäran eller neka den.
De flesta organisationer och användare på GitHub ställer in en enorm mängd information som är läsbar och offentlig. Till exempel har mitt GitHub-användarkonto ett par offentliga arkiv och offentliga SSH-nycklar som alla kan läsa åtkomst (även utan ett GitHub-användarkonto). Om du vill ha en mer detaljerad kontroll över ditt personliga konto kan du skapa ett “Personal Access Token” för att läsa och skriva privilegierad information som lagras i ditt personliga GitHub-konto. Om du skriver en tredjepartsapplikation, avsedd att användas av andra användare än dig, är en OAuth-token för nämnda användare vad din applikation skulle kräva.
Men som du kan se kan du få tillgång till mycket användbar information utan att skapa någon token.
3. Svar
Svaret returneras från GitHub API-servern och lagras i variabeln med namnet svar. Hela svaret kan läsas på flera sätt som dokumenterat här. Vi bad uttryckligen om JSON-innehåll från GitHub så vi kommer att behandla begäran, som om det är JSON. För att göra detta kallar vi json () -metoden från begärandemodulen som kommer att avkoda den till Python-ursprungliga objekt som ordböcker och listor.
Du kan se att nycklarna läggs till filen authorised_keys i detta för loop:
för jag som svar.json ():auktoriserade_tangenter_fil.skriv (i ['key'] + '\ n')
Om du skriver ut svaret.json () -objekt kommer du att märka att det är en Python-lista med Python-ordböcker som medlemmar. Varje ordbok har en nyckel med namnet 'nyckel' med din offentliga SSH-nyckel som värde för den nyckeln. Så du kan lägga till dessa värden en efter en till din auktoriserade_key-fil. Och nu kan du enkelt SSH till din server från vilken dator som helst som har någon av de privata SSH-nycklarna som motsvarar en av de offentliga nycklarna som vi just har lagt till.
Utforska vidare
Mycket arbete med API: er innebär noggrann inspektion av API-dokumentationen i sig mer än att skriva kodrader. När det gäller GitHub är dokumentationen en av de finaste i branschen. Men att läsa upp API-dokument och ringa API-samtal med Python är ganska ointressant som en fristående aktivitet.
Innan du går vidare skulle jag rekommendera dig att komma med en uppgift som du vill utföra med Python på ditt GitHub-konto. Försök sedan implementera den genom att bara läsa de officiella dokumentationen från Python, dess beroende bibliotek och GitHub. Detta hjälper dig också att anta en hälsosammare tänkesätt där du förstår vad som händer i din kod och förbättrar den gradvis över tid.
