Phenquestions
Ljudi u GitHubu, kao i treći programeri, nikako ne mogu upravljati svom tom složenošću bez zajedničkog sučelja. Ovo zajedničko sučelje nazivamo GitHub API. Svaki uslužni program GitHub poput cli-a, web korisničkog sučelja itd. Koristi ovo zajedničko sučelje za upravljanje resursima (resursi su entiteti poput spremišta, ssh ključeva itd.).
U ovom uputstvu naučit ćemo nekoliko osnova kako se netko sučeljava s API-jem koristeći GitHub API v3 i Python3. Najnoviji v4 GitHub API-ja zahtijeva da naučite o GraphQL-u što rezultira strmijom krivuljom učenja. Stoga ću se držati samo verzije tri koja je i dalje aktivna i prilično popularna.
Kako razgovarati s web API-jem
Web API-ji omogućavaju vam korištenje svih usluga koje nudi web aplikacija, poput GitHub-a, programski koristeći jezik po vašem izboru. Na primjer, ovdje ćemo koristiti Python za naš slučaj korištenja. Tehnički, sve što radite na GitHubu možete raditi pomoću API-ja, ali mi ćemo se ograničiti samo na čitanje javno dostupnih podataka.
Vaš program Python razgovarat će s API-om na isti način kao i vaš preglednik s web-lokacijom. Odnosno, uglavnom putem HTTPS zahtjeva. Ti će zahtjevi sadržavati različite 'dijelove', počevši od metode zahtjeva [GET, POST, PUT, DELETE], samog URL-a, niza upita, HTTP zaglavlja i tijela ili korisnog tereta. Većina njih nije obavezna. Međutim, trebat ćemo navesti način zahtjeva i URL na koji upućujemo zahtjev.
Što su to i kako su predstavljeni u HTTPS zahtjevu, nešto ćemo vidjeti sporo kad započnemo pisati Python skripte za interakciju s GitHubom.
Primjer
Dodavanje SSH ključeva novostvorenom poslužitelju uvijek je nespretan proces. Napišimo Python skriptu koja će dohvatiti vaše javne SSH ključeve s GitHub-a i dodati ih u datoteku odobreni_kejevi na bilo kojem Linuxu ili Unix poslužitelju na kojem izvodite ovu skriptu. Ako ne znate kako generirati ili koristiti SSH ključeve, evo izvrsnog članka o tome kako to točno učiniti. Pretpostavit ću da ste stvorili i dodali vlastite javne SSH ključeve na svoj GitHub račun.
Vrlo jednostavna i naivna implementacija Pythona za postizanje gore opisanog zadatka prikazana je dolje:
zahtjevi za uvozuvoz os
# Dobivanje korisničkog unosa
unix_user = input ("Unesite svoje Unix korisničko ime:")
github_user = input ("Unesite svoje korisničko ime za GitHub:")
# Biti siguran .ssh direktorij postoji i otvara datoteku odobreni_kejevi
ssh_dir = '/ home /' + unix_user + '/.ssh / '
ako ne os.staza.postoji (ssh_dir):
os.makedirci (ssh_dir)
odobreni_kejevi_datoteka = otvoreni (ssh_dir + 'odobreni_ključevi', 'a')
# Slanje zahtjeva GiHub API-ju i spremanje odgovora u varijablu pod nazivom 'response'
api_root = "https: // api.github.com "
request_header = 'Prihvati': 'application / vnd.github.v3 + json '
odgovor = zahtjevi.dobiti (api_root + '/ users /' + github_user + '/ keys', headers = request_header)
## Obrada odgovora i dodavanje ključeva datoteci odobreni_kejevi
jer ja kao odgovor.json ():
datoteka_datoteke_ovlascenih.napiši (i ['key'] + '\ n')
Zanemarimo rukovanje Python datotekama i razne pojedinosti i strogo se osvrnimo na zahtjev i odgovor. Prvo smo uvezli zahtjeve za uvoz modula zahtjeva ova biblioteka omogućuje nam da vrlo lako upućujemo API pozive. Ova je knjižnica ujedno i jedan od najboljih primjera projekta otvorenog koda izvedenog u redu. Evo službenog mjesta u slučaju da želite detaljnije pogledati dokumente.
Dalje postavljamo varijablu api_root.
api_root = "https: // api.github.com "Ovo je uobičajeni podniz u svim URL-ovima na koje ćemo upućivati API pozive. Dakle, umjesto da upišete “https: // api.github.com ”svaki put kada trebamo pristupiti https: // api.github.com / users ili https: // api.github.com / users /api_root + '/ users /' ili api_root + '/ korisnici / kao što je prikazano u isječku koda.
Dalje, postavili smo zaglavlje u našem HTTPS zahtjevu, ukazujući da su odgovori namijenjeni API-ju verzije 3 i da trebaju biti oblikovani u JSON-u. GitHub bi poštovao ove informacije zaglavlja.
1. GET Zahtjev
Dakle, sada kada imamo svoj URL i (neobavezno) informacije zaglavlja pohranjene u različite varijable, vrijeme je da podnesemo zahtjev.
odgovor = zahtjevi.dobiti (api_root + '/ users /' + github_user + '/ keys', headers = request_header)Zahtjev je tipa 'get' jer čitamo javno dostupne informacije s GitHub-a. Da pišete nešto pod svojim GitHub korisničkim računom, koristili biste POST. Slično su druge metode namijenjene drugim funkcijama poput DELETE za brisanje resursa poput spremišta.
2. Krajnja točka API-ja
Krajnja točka API-ja za kojom težimo je:
https: // api.github.com / users /Svaki GitHub resurs ima vlastitu krajnju točku API-ja. Tada se vaši zahtjevi za GET, PUT, DELETE itd. Podnose u odnosu na krajnju točku koju ste naveli. Ovisno o stupnju pristupa koji imate, GitHub će vam tada omogućiti da prođete s tim zahtjevom ili ga odbiti.
Većina organizacija i korisnika na GitHub-u postavljaju ogromnu količinu informacija čitljivih i javnih. Na primjer, moj GitHub korisnički račun ima nekoliko javnih spremišta i javnih SSH ključeva kojima svatko može čitati pristup (čak i bez korisničkog računa GitHub). Ako želite imati precizniju kontrolu nad svojim osobnim računom, možete generirati "Personal Access Token" za čitanje i pisanje privilegiranih podataka pohranjenih na vašem osobnom GitHub računu. Ako pišete aplikaciju treće strane, koja bi trebala biti korištena od strane korisnika koji nisu vaši, tada je za vašu aplikaciju potreban OAuth žeton navedenog korisnika.
Ali kao što vidite, puno korisnih informacija može se pristupiti bez stvaranja bilo kakvog tokena.
3. Odgovor
Odgovor se vraća s GitHub API poslužitelja i pohranjuje se u varijablu imenovanu response. Cjelokupni odgovor mogao bi se pročitati na nekoliko načina kako je ovdje dokumentirano. Izričito smo zatražili sadržaj tipa JSON s GitHub-a pa ćemo obraditi zahtjev, kao da je JSON. Da bismo to učinili, pozivamo metodu json () iz modula zahtjeva koja će je dekodirati u nativne Python objekte poput rječnika i popisa.
U ovoj petlji for možete vidjeti tipke dodane datoteci odobreni_kejevi:
jer ja kao odgovor.json ():datoteka_datoteke_ovlascenih.napiši (i ['key'] + '\ n')
Ako ispišete odgovor.json (), primijetit ćete da se radi o popisu Python s Python rječnicima kao članovima. Svaki rječnik ima ključ nazvan 'ključ' s vašim javnim SSH ključem kao vrijednost tog ključa. Tako možete dodati ove vrijednosti jednu po jednu u svoju datoteku odobreni_kejevi. A sada na svoj poslužitelj možete lako SSH s bilo kojeg računala koje ima bilo koji od privatnih SSH ključeva koji odgovara jednom od javnih ključeva koje smo upravo dodali.
Dalje istražujući
Puno rada s API-jevima uključuje pažljivu inspekciju same API dokumentacije više od pisanja redaka koda. U slučaju GitHub-a, dokumentacija je jedna od najboljih u industriji. Ali čitanje API dokumenata i upućivanje API poziva pomoću Pythona prilično je nezanimljivo kao samostalna aktivnost.
Prije nego što nastavite dalje, preporučio bih vam da smislite jedan zadatak koji biste željeli izvršiti pomoću Pythona na svom GitHub računu. Zatim ga pokušajte implementirati čitajući samo službenu dokumentaciju koju pruža Python, njegove ovisne knjižnice i GitHub. Ovo će vam također pomoći da usvojite zdraviji način razmišljanja gdje razumijete što se događa unutar vašeg koda i postupno ga poboljšavate.
