Phenquestions
Lidé na GitHubu a vývojáři třetích stran nemohou bez společné rozhraní zvládnout veškerou tuto složitost. Toto společné rozhraní nazýváme GitHub API. Každý nástroj GitHub, jako je cli, webové uživatelské rozhraní atd., Používá toto jedno běžné rozhraní ke správě zdrojů (prostředky jsou entity jako úložiště, klíče ssh atd.).
V tomto tutoriálu se naučíme několik základních informací o tom, jak se rozhraní s API pomocí GitHub API v3 a Python3. Nejnovější v4 rozhraní GitHub API vyžaduje, abyste se seznámili s GraphQL, což má za následek strmější křivku učení. Zůstanu tedy jen u verze tři, která je stále aktivní a velmi populární.
Jak mluvit s webovým API
Webová rozhraní API vám umožňují používat všechny služby nabízené webovou aplikací, jako je GitHub, programově pomocí jazyka podle vašeho výběru. Například zde použijeme Python pro náš případ použití. Technicky můžete dělat vše, co děláte na GitHubu pomocí API, ale omezíme se pouze na čtení veřejně přístupných informací.
Váš program Python bude mluvit s API stejným způsobem jako váš prohlížeč mluví s webem. To znamená, většinou prostřednictvím požadavků HTTPS. Tyto požadavky budou obsahovat různé „části“, počínaje metodou požadavku [GET, POST, PUT, DELETE], samotnou adresou URL, řetězcem dotazu, hlavičkou HTTP a tělem nebo nákladem. Většina z nich je volitelná. Budeme však muset poskytnout metodu požadavku a adresu URL, na kterou provádíme požadavek.
Co to je a jak jsou zastoupeny v požadavku HTTPS, uvidíme pomalu, když začneme psát skripty Pythonu pro interakci s GitHubem.
Příklad
Přidání klíčů SSH na nově vytvořený server je vždy neohrabaný proces. Pojďme napsat skript Pythonu, který načte vaše veřejné klíče SSH z GitHubu a přidá jej do souboru authorized_keys na libovolném serveru Linux nebo Unix, kde tento skript spustíte. Pokud nevíte, jak generovat nebo používat klíče SSH, je zde vynikající článek o tom, jak to přesně udělat. Předpokládám, že jste vytvořili a přidali své vlastní veřejné klíče SSH do svého účtu GitHub.
Velmi jednoduchá a naivní implementace Pythonu k dosažení výše popsaného úkolu je uvedena níže:
požadavky na importimport os
# Získání vstupu uživatele
unix_user = input ("Zadejte své uživatelské jméno pro Unix:")
github_user = input ("Zadejte své uživatelské jméno GitHub:")
# Ujistěte se .ssh adresář existuje a otevírá se soubor authorized_keys
ssh_dir = '/ home /' + unix_user + '/.ssh / '
pokud ne os.cesta.existuje (ssh_dir):
os.makedirs (ssh_dir)
authorized_keys_file = open (ssh_dir + 'authorized_keys', 'a')
# Odeslání požadavku na API GiHub a uložení odpovědi do proměnné s názvem „odpověď“
api_root = "https: // api.github.com "
request_header = 'Accept': 'application / vnd.github.v3 + json '
odpověď = požadavky.get (api_root + '/ users /' + github_user + '/ keys', headers = request_header)
## Zpracování odpovědi a připojení klíčů do souboru authorized_keys
pro odpověď.json ():
authorized_keys_file.write (i ['key'] + '\ n')
Pojďme ignorovat manipulaci se soubory Pythonu a různé podrobnosti a podívejme se přísně na požadavek a odpověď. Nejprve jsme importovali požadavky modulu importu požadavků tato knihovna nám umožňuje velmi snadno volat API. Tato knihovna je také jedním z nejlepších příkladů projektu open source provedeného správně. Zde je oficiální stránka pro případ, že byste se chtěli podrobněji podívat na dokumenty.
Dále nastavíme proměnnou api_root.
api_root = "https: // api.github.com "Toto je běžný podřetězec ve všech adresách URL, na které budeme volat API. Takže místo psaní „https: // api.github.com “pokaždé, když potřebujeme přístup k rozhraní https: // api.github.com / users nebo https: // api.github.com / uživatelé /api_root + '/ users /' nebo api_root + '/ uživatelé / jak je ukázáno ve fragmentu kódu.
Dále jsme nastavili záhlaví v našem požadavku HTTPS, což naznačuje, že odpovědi jsou určeny pro API verze 3 a měly by být ve formátu JSON. GitHub by tyto informace v hlavičce respektoval.
1. ZÍSKAT požadavek
Takže teď, když máme naši adresu URL a (volitelnou) informaci o záhlaví uloženou v různých proměnných, je čas podat žádost.
odpověď = požadavky.get (api_root + '/ users /' + github_user + '/ keys', headers = request_header)Požadavek je typu „get“, protože čteme veřejně dostupné informace z GitHubu. Pokud byste něco psali pod svým uživatelským účtem GitHub, použili byste POST. Podobně jsou jiné metody určeny pro další funkce, jako je DELETE pro odstranění prostředků, jako jsou úložiště.
2. Koncový bod API
Koncový bod API, o který se snažíme, je:
https: // api.github.com / uživatelé /Každý prostředek GitHub má svůj vlastní koncový bod API. Vaše požadavky na GET, PUT, DELETE atd. Jsou poté provedeny proti koncovému bodu, který jste zadali. V závislosti na úrovni přístupu, kterou máte, vám GitHub poté buď umožní projít tímto požadavkem, nebo ho zamítne.
Většina organizací a uživatelů na GitHubu nastavuje obrovské množství čitelných a veřejných informací. Například můj uživatelský účet GitHub má několik veřejných úložišť a veřejných klíčů SSH, ke kterým může kdokoli číst přístup (i bez uživatelského účtu GitHub). Pokud chcete mít podrobnější kontrolu nad svým osobním účtem, můžete vygenerovat „Token osobního přístupu“ pro čtení a zápis privilegovaných informací uložených ve vašem osobním účtu GitHub. Pokud píšete aplikaci třetí strany, kterou mají používat jiní uživatelé než vy, pak by vaše aplikace vyžadovala token OAuth uvedeného uživatele.
Ale jak vidíte, lze získat spoustu užitečných informací bez vytváření jakéhokoli tokenu.
3. Odezva
Odpověď je vrácena ze serveru GitHub API a je uložena v proměnné s názvem response. Celá odpověď mohla být přečtena několika způsoby, jak je zdokumentováno zde. Výslovně jsme požádali o obsah typu JSON z GitHubu, takže požadavek zpracujeme, jako by to byl JSON. K tomu voláme metodu json () z modulu požadavků, která ji dekóduje do nativních objektů Pythonu, jako jsou slovníky a seznamy.
Můžete vidět klíče, které jsou připojeny k souboru authorized_keys v této smyčce for:
pro odpověď.json ():authorized_keys_file.write (i ['key'] + '\ n')
Pokud odpověď vytisknete.objekt json (), všimnete si, že se jedná o seznam Pythonu, jehož členy jsou slovníky Pythonu. Každý slovník má klíč s názvem „klíč“ s vaším veřejným klíčem SSH jako hodnotou tohoto klíče. Tyto hodnoty tedy můžete postupně přidávat do svého souboru authorized_keys. A nyní můžete snadno SSH na svůj server z libovolného počítače, který má k dispozici někdo ze soukromých klíčů SSH odpovídající jednomu z veřejných klíčů, které jsme právě připojili.
Další zkoumání
Hodně práce s API vyžaduje pečlivou kontrolu samotné dokumentace API, než psaní řádků kódu. V případě GitHub je dokumentace jednou z nejlepších v oboru. Čtení dokumentů API a volání API pomocí Pythonu je ale jako samostatná aktivita docela nezajímavé.
Než půjdete dál, doporučil bych vám přijít s jedním úkolem, který byste chtěli provést pomocí Pythonu na vašem účtu GitHub. Pak to zkuste implementovat čtením pouze oficiálních dokumentací poskytovaných Pythonem, jeho závislými knihovnami a GitHubem. To vám také pomůže osvojit si zdravější myšlení, kde pochopíte, co se ve vašem kódu děje, a postupně ho vylepšovat.
