Phenquestions
Ľudia v spoločnosti GitHub a rovnako aj vývojári tretích strán nemôžu túto spoločnú zložitosť zvládnuť bez spoločného rozhrania. Toto spoločné rozhranie nazývame GitHub API. Každá pomôcka GitHub, ako napríklad cli, webové používateľské rozhranie atď., Používa toto spoločné rozhranie na správu zdrojov (zdroje sú entity ako úložiská, kľúče ssh atď.).
V tomto výučbe sa dozvieme niekoľko základných informácií o tom, ako sa dá rozhranie pracovať s API pomocou GitHub API v3 a Python3. Najnovšia v4 GitHub API vyžaduje, aby ste sa dozvedeli niečo o GraphQL, čo vedie k strmšej krivke učenia. Zostanem teda iba pri verzii tri, ktorá je stále aktívna a veľmi populárna.
Ako hovoriť s webovým API
Webové API vám umožňujú využívať všetky služby ponúkané webovou aplikáciou, ako je GitHub, programovo pomocou jazyka podľa vášho výberu. Napríklad tu použijeme Python pre náš prípad použitia. Technicky môžete všetko, čo robíte na GitHube, robiť pomocou API, obmedzíme sa však iba na čítanie verejne prístupných informácií.
Váš program Python bude hovoriť s rozhraním API rovnakým spôsobom, ako hovorí váš prehliadač s webovou stránkou. To znamená, väčšinou prostredníctvom požiadaviek HTTPS. Tieto žiadosti budú obsahovať rôzne „časti“, počnúc metódou žiadosti [GET, POST, PUT, DELETE], samotnou adresou URL, reťazcom dopytu, hlavičkou HTTP a textom alebo užitočným zaťažením. Väčšina z nich je voliteľných. Budeme však musieť poskytnúť metódu žiadosti a adresu URL, na ktorú podávame žiadosť.
Čo to je a ako sú reprezentované v požiadavke HTTPS, uvidíme pomaly, keď začneme písať skripty Pythonu na interakciu s GitHubom.
Príklad
Pridávanie kľúčov SSH na novovytvorený server je vždy neohrabaný proces. Poďme napísať skript v jazyku Python, ktorý načíta vaše verejné kľúče SSH z GitHubu a pridá ho do súboru authorized_keys na ľubovoľnom serveri Linux alebo Unix, kde tento skript spustíte. Ak neviete, ako vygenerovať alebo použiť kľúče SSH, je tu vynikajúci článok, ako presne to urobiť. Budem predpokladať, že ste si vytvorili a pridali svoje vlastné verejné kľúče SSH do svojho účtu GitHub.
Veľmi jednoduchá a naivná implementácia Pythonu na dosiahnutie úlohy, ktorú sme opísali vyššie, je uvedená nižšie:
požiadavky na importimport os
# Získavanie informácií od používateľov
unix_user = input ("Zadajte svoje používateľské meno pre Unix:")
github_user = input ("Zadajte svoje používateľské meno GitHub:")
# Pre istotu .ssh adresár existuje a otvára sa súbor authorized_keys
ssh_dir = '/ home /' + unix_user + '/.ssh / '
ak nie os.cesta.existuje (ssh_dir):
os.makedirs (ssh_dir)
authorized_keys_file = open (ssh_dir + 'authorized_keys', 'a')
# Odoslanie žiadosti do API GiHub a uloženie odpovede do premennej s názvom „odpoveď“
api_root = "https: // api.github.com "
request_header = 'Accept': 'application / vnd.github.v3 + json '
odpoveď = požiadavky.get (api_root + '/ users /' + github_user + '/ keys', headers = request_header)
## Spracovanie odpovede a pripojenie kľúčov k súboru authorized_keys
lebo ja v odpovedi.json ():
authorized_keys_file.write (i ['key'] + '\ n')
Ignorujme prácu so súbormi v Pythone a rôzne podrobnosti a dôsledne sa pozrime na požiadavku a odpoveď. Najprv sme importovali požiadavky modulu na import požiadaviek, ktoré nám táto knižnica umožňuje veľmi ľahko uskutočňovať hovory API. Táto knižnica je tiež jedným z najlepších príkladov projektu open source vykonaného správne. Toto je oficiálna stránka pre prípad, že by ste sa chceli bližšie pozrieť na dokumenty.
Ďalej nastavíme premennú api_root.
api_root = "https: // api.github.com "Toto je bežný podreťazec vo všetkých adresách URL, na ktoré budeme uskutočňovať hovory API. Takže namiesto toho, aby ste napísali „https: // api.github.com “zakaždým, keď potrebujeme získať prístup k rozhraniu https: // api.github.com / users alebo https: // api.github.com / users /api_root + '/ users /' alebo api_root + '/ users / ako je uvedené v útržku kódu.
Ďalej sme nastavili hlavičku v našej požiadavke HTTPS, čo naznačuje, že odpovede sú určené pre API verzie 3 a mali by byť vo formáte JSON. GitHub by rešpektoval túto informáciu o hlavičke.
1. ZÍSKAJTE žiadosť
Takže teraz, keď máme našu adresu URL a (voliteľné) informácie o hlavičke uložené v rôznych premenných, je čas podať žiadosť.
odpoveď = požiadavky.get (api_root + '/ users /' + github_user + '/ keys', headers = request_header)Žiadosť je typu „get“, pretože čítame verejne dostupné informácie z GitHubu. Ak by ste niečo písali pod svojím používateľským účtom GitHub, použili by ste POST. Podobne sú určené aj ďalšie metódy pre ďalšie funkcie, ako napríklad DELETE, určené na mazanie prostriedkov, ako sú napríklad úložiská.
2. Koncový bod API
Koncový bod API, ktorý oslovujeme, je:
https: // api.github.com / users /Každý prostriedok GitHub má svoj vlastný koncový bod API. Vaše požiadavky na GET, PUT, DELETE atď. Sa potom uskutočnia proti zadanému koncovému bodu. V závislosti od úrovne prístupu, ktorú máte, vám GitHub potom buď umožní prejsť s touto požiadavkou, alebo ju zamietnuť.
Väčšina organizácií a používateľov na GitHub nastavuje obrovské množstvo informácií, ktoré sú čitateľné a verejné. Napríklad môj užívateľský účet GitHub má niekoľko verejných úložísk a verejné kľúče SSH, ku ktorým môže ktokoľvek čítať prístup (aj bez používateľského účtu GitHub). Ak chcete mať podrobnejšiu kontrolu nad svojím osobným účtom, môžete vygenerovať „Token osobného prístupu“ na čítanie a zápis privilegovaných informácií uložených vo vašom osobnom účte GitHub. Ak píšete aplikáciu tretej strany, ktorú majú používať iní používatelia ako vy, potom by vaša aplikácia vyžadovala token OAuth uvedeného používateľa.
Ako však vidíte, je možné získať prístup k mnohým užitočným informáciám bez vytvárania tokenu.
3. Odozva
Odozva sa vracia zo servera GitHub API a je uložená v premennej s názvom response. Celá odpoveď sa dala prečítať niekoľkými spôsobmi, ako je to zdokumentované tu. Výslovne sme požiadali o obsah typu JSON z GitHubu, takže žiadosť spracujeme, akoby to bol JSON. Za týmto účelom voláme metódu json () z modulu požiadaviek, ktorá ju dekóduje do natívnych objektov Pythonu, ako sú slovníky a zoznamy.
Kľúče, ktoré sa pripájajú k súboru authorized_keys, vidíte v tejto slučke for:
pre i v odpovedi.json ():authorized_keys_file.write (i ['key'] + '\ n')
Ak si odpoveď vytlačíte.objekt json (), všimnete si, že ide o zoznam Pythonu, ktorého členmi sú slovníky Pythonu. Každý slovník má kľúč s názvom „kľúč“ a svojím verejným kľúčom SSH ako hodnotu tohto kľúča. Tieto hodnoty teda môžete po jednom pridávať do svojho súboru authorized_keys. A teraz môžete ľahko SSH na svoj server z ľubovoľného počítača, ktorý má k dispozícii akýkoľvek zo súkromných kľúčov SSH zodpovedajúcich jednému z verejných kľúčov, ktoré sme práve pripojili.
Skúmame ďalej
Veľa práce s API spočíva v dôkladnejšej kontrole samotnej dokumentácie API, než v písaní riadkov kódu. V prípade GitHub je dokumentácia jednou z najlepších v odbore. Čítanie dokumentov API a uskutočňovanie hovorov API pomocou Pythonu je však ako samostatná aktivita dosť nezaujímavé.
Než pôjdete ďalej, odporučil by som vám vymyslieť jednu úlohu, ktorú by ste chceli vykonať pomocou Pythonu na vašom účte GitHub. Potom to skúste implementovať tak, že si prečítate iba oficiálne dokumentácie poskytované programom Python, jeho závislými knižnicami a GitHub. To vám tiež pomôže osvojiť si zdravšie zmýšľanie, kde pochopíte, čo sa deje vo vašom kóde, a postupne ho vylepšovať.
