Phenquestions
Nii GitHubi inimesed kui ka kolmandate osapoolte arendajad ei suuda kogu seda keerukust ilma ühise liideseta hallata. Seda ühist liidest nimetame GitHubi API-ks. Kõik GitHubi utiliidid, näiteks kliendid, veebiliidesed jne, kasutavad seda ühte tavalist liidest ressursside haldamiseks (ressursid on üksused nagu hoidlad, ssh-võtmed jne).
Selles õpetuses õpime mõningaid põhitõdesid, kuidas üks liidestub API-ga, kasutades GitHub API v3 ja Python3. GitHubi API uusim versioon v4 nõuab, et sa õpiksid GraphQL-i, mille tulemuseks on järsem õppimiskõver. Nii et jään ainult kolmanda versiooni juurde, mis on endiselt aktiivne ja üsna populaarne.
Kuidas rääkida veebi API-ga
Veebi-API-d võimaldavad teil kasutada kõiki veebirakenduse pakutavaid teenuseid, näiteks GitHub, programmeeritult teie valitud keelt kasutades. Näiteks kavatseme siin oma kasutuse korral kasutada Pythoni. Tehniliselt saate GitHubis API abil teha kõike, mida teete, kuid piirdume ainult avalikult juurdepääsetava teabe lugemisega.
Teie Pythoni programm räägib API-ga samamoodi nagu teie brauser veebisaidiga. See tähendab, enamasti HTTPS-i päringute kaudu. Need taotlused sisaldavad erinevaid osi, alustades päringu meetodist [GET, POST, PUT, DELETE], URL-ist endast, päringustringist, HTTP-päisest ja kehast või kasulikust koormusest. Enamik neist on valikulised. Peame siiski esitama päringumeetodi ja URL-i, kuhu me päringu esitame.
Mis need on ja kuidas neid HTTPS-päringus esindatakse, näeme aeglaselt, kui hakkame Pythoni skripte kirjutama GitHubiga suhtlemiseks.
Näide
SSH-võtmete lisamine vastloodud serverisse on alati kohmakas protsess. Kirjutame Pythoni skripti, mis otsib teie avalikud SSH-võtmed GitHubist ja lisab selle mis tahes Linuxi või Unixi serverisse, kus seda skripti käitate, autoriseeritud_klahvid. Kui te ei tea, kuidas SSH-võtmeid genereerida või kasutada, on siin suurepärane artikkel, kuidas täpselt seda teha. Eeldan, et olete loonud ja lisanud oma GitHubi kontole oma avalikud SSH-võtmed.
Väga lihtne ja naiivne Pythoni rakendus ülalkirjeldatud ülesande saavutamiseks on järgmine:
imporditaotlusedimpordi os
# Kasutaja sisendi saamine
unix_user = input ("Sisestage oma Unixi kasutajanimi:")
github_user = input ("Sisestage oma GitHubi kasutajanimi:")
# Kindlaks tegema .ssh-kataloog on olemas ja avatakse autoriseeritud võtmete fail
ssh_dir = '/ kodu /' + unix_user + '/.ssh / '
kui mitte os.tee.olemas (ssh_dir):
os.makedirid (ssh_dir)
Authorized_keys_file = avatud (ssh_dir + 'Author_keys', 'a')
# Taotluse saatmine GiHubi API-le ja vastuse salvestamine muutujasse nimega "vastus"
api_root = "https: // api.github.com "
request_header = 'Nõustu': 'application / vnd.github.v3 + json '
vastus = taotlused.get (api_root + '/ kasutajad /' + github_user + '/ võtmed', päised = request_header)
## Vastuse töötlemine ja autoriseeritud võtmete faili võtmete lisamine
i jaoks vastuseks.json ():
Authorized_keys_file.kirjuta (i ['võti'] + '\ n')
Eiragem Pythoni failide käitlemist ja mitmesuguseid üksikasju ning vaatleme rangelt taotlust ja vastust. Kõigepealt importisime päringute mooduli imporditaotlused, see raamatukogu võimaldab meil API-kõnesid väga lihtsalt teha. See raamatukogu on ka üks parimaid näiteid avatud lähtekoodiga projektist, mis on õigesti tehtud. Siin on ametlik sait juhuks, kui soovite dokumente lähemalt uurida.
Järgmisena määrasime muutuja api_root.
api_root = "https: // api.github.com "See on kõigi URL-ide tavaline alamstruktuur, millele me API-kõnesid teeme. Nii et selle asemel, et tippida „https: // api.github.com ”iga kord, kui peame pääsema juurde aadressile https: // api.github.com / users või https: // api.github.com / users /api_root + '/ kasutajad /' või api_root + '/ kasutajad / nagu koodilõigus näidatud.
Järgmisena määrasime oma HTTPS-i päringus päise, näidates, et vastused on mõeldud versiooni 3 API jaoks ja need peaksid olema JSON-vormingus. GitHub austaks seda päiseteavet.
1. Hangi päring
Nii et nüüd, kui meie URL ja (valikuline) päise teave on salvestatud erinevatesse muutujatesse, on aeg päring esitada.
vastus = taotlused.get (api_root + '/ kasutajad /' + github_user + '/ võtmed', päised = request_header)Taotlus on tüüpi 'get', kuna loeme GitHubist avalikult kättesaadavat teavet. Kui kirjutasite midagi oma GitHubi kasutajakonto all, kasutaksite POST-i. Samamoodi on muud meetodid mõeldud muude funktsioonide jaoks, näiteks DELETE on ressursside, näiteks hoidlate, kustutamiseks.
2. API lõpp-punkt
API otspunkt, mille poole me pöördume, on järgmine:
https: // api.github.com / users /Igal GitHubi ressursil on oma API lõpp-punkt. Teie taotlused GET, PUT, DELETE jne esitatakse teie esitatud lõpp-punkti suhtes. Sõltuvalt teie juurdepääsutasemest lubab GitHub teil selle taotluse läbi teha või keeldub sellest.
Enamik GitHubi organisatsioone ja kasutajaid seab tohutu hulga loetavat ja avalikku teavet. Näiteks on minu GitHubi kasutajakontol paar avalikku hoidlat ja avalikud SSH-võtmed, mida igaüks saab lugeda (ka ilma GitHubi kasutajakontota). Kui soovite oma isikliku konto täpsemat juhtimist, saate luua isikliku juurdepääsuloa oma isiklikule GitHubi kontole salvestatud privilegeeritud teabe lugemiseks ja kirjutamiseks. Kui kirjutate kolmanda osapoole rakendust, mis on mõeldud kasutamiseks teistele kasutajatele kui teie, siis teie rakendus eeldaks nimetatud kasutaja OAuthi märki.
Kuid nagu näete, pääseb juurde palju kasulikku teavet ilma luba loomata.
3. Vastus
Vastus tagastatakse GitHubi API serverist ja salvestatakse muutuja nimega vastus. Kogu vastust saab lugeda mitmel viisil, nagu siin dokumenteeritud. Palusime GitHubilt selgesõnaliselt JSON-tüüpi sisu, nii et töötleme päringut, nagu oleks see JSON. Selleks kutsume päringute moodulist meetodit json (), mis dekodeerib selle Pythoni natiivobjektideks, näiteks sõnastikud ja loendid.
Selles näete, et võtmele autoriseeritud_klahvid on lisatud võtmed tsükli jaoks:
i jaoks vastuseks.json ():Authorized_keys_file.kirjuta (i ['võti'] + '\ n')
Kui printite vastuse.json () objekti, märkate, et see on Pythoni loend, mille liikmeteks on Pythoni sõnastikud. Igal sõnaraamatul on võti nimega „võti”, mille väärtuseks on teie avalik SSH-võti. Nii saate need väärtused ükshaaval lisada failile authorised_keys. Nüüd saate SSH-i hõlpsasti oma serverisse siseneda igast arvutist, millel on keegi privaatsetest SSH-võtmetest, mis vastavad ühele meie äsja lisatud avalikule võtmele.
Edasine uurimine
Palju tööd API-ga hõlmab API dokumentide hoolikat kontrollimist rohkem kui koodiridade kirjutamine. GitHubi puhul on dokumentatsioon tööstuses üks parimaid. Kuid API-dokumentide lugemine ja Pythoni abil API-kõnede tegemine on iseseisva tegevusena üsna ebahuvitav.
Enne kui lähete kaugemale, soovitaksin teil välja mõelda üks ülesanne, mille soovite Pythoni abil oma GitHubi kontol täita. Seejärel proovige seda rakendada, lugedes ainult Pythoni, tema sõltuvate raamatukogude ja GitHubi pakutavaid ametlikke dokumente. See aitab teil omaks võtta ka tervislikuma mõtteviisi, kus saate aru, mis teie koodis toimub, ja parandate seda aja jooksul järk-järgult.
