Phenquestions
Folk hos GitHub og både tredjepartsudviklere kan umuligt administrere al denne kompleksitet uden en fælles grænseflade. Denne fælles grænseflade er, hvad vi kalder GitHub API. Hvert GitHub-værktøj som en cli, web-brugergrænseflade osv. Bruger denne ene fælles grænseflade til at administrere ressourcer (ressourcer er enheder som arkiver, ssh-nøgler osv.).
I denne vejledning lærer vi et par grundlæggende om, hvordan man grænseflader med en API ved hjælp af GitHub API v3 og Python3. Den seneste v4 af GitHub API kræver, at du lærer om GraphQL, hvilket resulterer i en stejlere indlæringskurve. Så jeg vil holde mig til bare version tre, som stadig er aktiv og temmelig populær.
Sådan taler du med en web-API
Web-API'er er det, der gør det muligt for dig at bruge alle de tjenester, der tilbydes af en webapp, som GitHub, programmatisk ved hjælp af dit eget sprog. For eksempel skal vi bruge Python til vores brugssag her. Teknisk set kan du gøre alt hvad du gør på GitHub ved hjælp af API'et, men vi begrænser os til kun at læse de offentligt tilgængelige oplysninger.
Dit Python-program taler til en API på samme måde som din browser taler til et websted. Det vil sige for det meste via HTTPS-anmodninger. Disse anmodninger vil indeholde forskellige 'dele' startende fra metoden til anmodningen [GET, POST, PUT, SLET], selve URL'en, en forespørgselsstreng, en HTTP-header og en body eller en nyttelast. De fleste af disse er valgfri. Vi bliver dog nødt til at angive en anmodningsmetode og den URL, som vi anmoder om.
Hvad disse er, og hvordan de er repræsenteret i en HTTPS-anmodning, er noget, vi ser langsomt, når vi begynder at skrive Python-scripts for at interagere med GitHub.
Et eksempel
Tilføjelse af SSH-nøgler til en nyoprettet server er altid en klodset proces. Lad os skrive et Python-script, der henter dine offentlige SSH-nøgler fra GitHub og tilføjer det til filen author_keys på enhver Linux- eller Unix-server, hvor du kører dette script. Hvis du ikke ved, hvordan man genererer eller bruger SSH-nøgler, er her en fremragende artikel om, hvordan man gør netop det. Jeg antager, at du har oprettet og tilføjet dine egne offentlige SSH-nøgler til din GitHub-konto.
En meget enkel og naiv Python-implementering for at opnå den opgave, vi beskrev ovenfor, er som vist nedenfor:
importanmodningerimporter os
# Få brugerinput
unix_user = input ("Indtast dit Unix-brugernavn:")
github_user = input ("Indtast dit GitHub brugernavn:")
# Være sikker .ssh-katalog findes og åbner filen authorised_keys
ssh_dir = '/ home /' + unix_user + '/.ssh / '
hvis ikke os.sti.findes (ssh_dir):
os.makedirs (ssh_dir)
autoriserede_taster_fil = åbne (ssh_dir + 'autoriserede_taster', 'a')
# Afsendelse af en anmodning til GiHub API og lagring af svaret i en variabel med navnet 'svar'
api_root = "https: // api.github.com "
request_header = 'Accept': 'application / vnd.github.v3 + json '
svar = anmodninger.get (api_root + '/ users /' + github_user + '/ keys', headers = request_header)
## Behandling af svaret og tilføjelse af nøgler til filen authorised_keys
for jeg som svar.json ():
autoriserede_taster_fil.skriv (i ['nøgle'] + '\ n')
Lad os ignorere Python-filhåndtering og diverse detaljer og se nøje på anmodningen og svaret. Først importerede vi anmodningsmodulet importanmodninger, dette bibliotek giver os mulighed for at foretage API-opkald meget let. Dette bibliotek er også et af de bedste eksempler på et open source-projekt gjort rigtigt. Her er det officielle sted, hvis du vil se nærmere på dokumenterne.
Dernæst indstiller vi en variabel api_root.
api_root = "https: // api.github.com "Dette er det almindelige underlag i alle de webadresser, som vi foretager API-opkald til. Så i stedet for at skrive “https: // api.github.com ”hver gang vi skal have adgang til https: // api.github.com / brugere eller https: // api.github.com / brugere /api_root + '/ brugere /' eller api_root + '/ brugere / som vist i kodestykket.
Dernæst indstiller vi overskriften i vores HTTPS-anmodning, hvilket indikerer, at svarene er beregnet til version 3 API og skal være JSON-formateret. GitHub respekterer disse headeroplysninger.
1. FÅ anmodning
Så nu hvor vi har vores URL og (en valgfri) headerinformation gemt i forskellige variabler, er det tid til at fremsætte anmodningen.
svar = anmodninger.get (api_root + '/ users /' + github_user + '/ keys', headers = request_header)Anmodningen er af typen 'get', fordi vi læser offentligt tilgængelige oplysninger fra GitHub. Hvis du skrev noget under din GitHub-brugerkonto, ville du bruge POST. Tilsvarende er andre metoder beregnet til andre funktioner som DELETE er til sletning af ressourcer som arkiver.
2. API-slutpunkt
API-slutpunktet, som vi når ud til, er:
https: // api.github.com / brugere /Hver GitHub-ressource har sit eget API-slutpunkt. Dine anmodninger om GET, PUT, SLET osv. Fremsættes derefter mod det slutpunkt, du har angivet. Afhængigt af det adgangsniveau, du har, giver GitHub dig enten mulighed for at gå igennem med den anmodning eller nægte den.
De fleste organisationer og brugere på GitHub indstiller en enorm mængde information læsbar og offentlig. For eksempel har min GitHub-brugerkonto et par offentlige arkiver og offentlige SSH-nøgler, som alle kan læse adgang (selv uden en GitHub-brugerkonto). Hvis du vil have en mere detaljeret kontrol over din personlige konto, kan du generere et "Personal Access Token" til at læse og skrive privilegerede oplysninger, der er gemt på din personlige GitHub-konto. Hvis du skriver en tredjepartsapplikation, der er beregnet til at blive brugt af andre brugere end dig, så er et OAuth-token af den nævnte bruger det, din applikation ville kræve.
Men som du kan se, kan du få adgang til mange nyttige oplysninger uden at oprette token.
3. Respons
Svaret returneres fra GitHub API-serveren og gemmes i den variabel, der hedder svaret. Hele svaret kunne læses på flere måder som beskrevet her. Vi bad eksplicit om JSON-typeindhold fra GitHub, så vi behandler anmodningen, som om det er JSON. For at gøre dette kalder vi json () -metoden fra anmodningsmodulet, som afkoder den til Python-native objekter som ordbøger og lister.
Du kan se nøglerne tilføjes til filen author_keys i denne for loop:
for jeg som svar.json ():autoriserede_taster_fil.skriv (i ['nøgle'] + '\ n')
Hvis du udskriver svaret.json () objekt, vil du bemærke, at det er en Python-liste med Python-ordbøger som medlemmer. Hver ordbog har en nøgle med navnet 'nøgle' med din offentlige SSH-nøgle som værdi for denne nøgle. Så du kan tilføje disse værdier en efter en til din autoriserede_keys-fil. Og nu kan du nemt SSH ind på din server fra enhver computer, der har nogen af de private SSH-nøgler, der svarer til en af de offentlige nøgler, vi lige har tilføjet.
Udforskning yderligere
Meget arbejde med API'er indebærer omhyggelig inspektion af selve API-dokumentationen mere end at skrive kodelinjer. I tilfælde af GitHub er dokumentationen en af de fineste i branchen. Men at læse op på API-dokumenter og foretage API-opkald ved hjælp af Python er ret uinteressant som en enkeltstående aktivitet.
Før du går videre, vil jeg anbefale dig at komme med en opgave, som du gerne vil udføre ved hjælp af Python på din GitHub-konto. Prøv derefter at implementere det ved kun at læse de officielle dokumentationer leveret af Python, dets afhængige biblioteker og GitHub. Dette vil også hjælpe dig med at vedtage en sundere tankegang, hvor du forstår, hvad der foregår inde i din kode og forbedrer den gradvist over tid.
