Jak už bylo řečeno v lekci o JSON, hlavní výhoda formátu JSON je, že se na Internetu rozšířil nejvíc. Pojďme toho využít!
Spousta webových služeb poskytuje takzvané API (z application programming interface, programátorské rozhraní), přes které je možné s danou službou komunikovat programově. Místo klikání na tlačítka a čtení stránek „očima” dostaneme data ve formátu, kterým rozumí počítače – a v dnešní době to bude většinou formát JSON.
Z minulých lekcí bys měla mít založený účet na github.com, tak se zkusme zeptat Githubu, co o nás ví.
První, a mnohdy nejsložitější, krok k použití API je přihlášení. Počítače se totiž přihlašují jinak než lidi a problematika bezpečnosti a oprávnění by vydala na samostatný kurz. My to uděláme co nejjednodušeji, ať se rychle dostaneme k jádru věci:
token.txt.Pozor!
Vygenerovaný kód je heslo, které držitele opravňuje pracovat s Githubem pod tvým jménem! Drž ho v tajnosti. Kdyby se přece jen dostalo „ven”, na stránce Personal Accesss Tokens ho deaktivuj.
K práci s internetovými stránkami použijeme knihovnu Requests. V aktivovaném virtuálním prostředí si ji nainstaluj příkazem:
(env)$ python -m pip install requests
A potom v Pythonu zkus stáhnout nějakou stránku:
import requests
# stažení stránky
stranka = requests.get('https://github.com')
# ověření, že dotaz proběhl v pořádku
stranka.raise_for_status()
# vypsání obsahu
print(stranka.text)
Měl by se vypsat obsah stránky https://github.com – HTML kód, který se objeví když v prohlížeči dáš „Ukázat zdroj” (View Page Source, většinou Ctrl+U) a ze kterého prohlížeč umí vykreslit stránku.
Ale my nechceme obsah pro lidi. Podívejme se, co Github zpřístupňuje počítačům.
Zkus, co dělá tento kód:
import requests
with open('token.txt') as soubor:
token = soubor.read().strip()
headers = {'Authorization': 'token ' + token}
stranka = requests.get('https://api.github.com/user', headers=headers)
stranka.raise_for_status()
print(stranka.text)
Co se stalo? Tím, že jsi Githubu dala svůj token
(načtený ze souboru, předaný přes slovník headers),
poznal, že jde dotaz od tebe a vrátil nějaké informace
ve formátu JSON.
Zkus řetězec stranka.text převést z JSON na slovník
a vypsat trochu srozumitelněji:
data = json.loads(stranka.text)
print(json.dumps(data, ensure_ascii=True, indent=2))
Teď už je lépe vidět celý tvůj profil (možná včetně neveřejných informací – proto musíš svůj token udržovat v tajnosti).
S profilem, který máš v proměnné data,
se dá pracovat jako s každým jiným slovníkem.
Třeba adresu svého obrázku můžeš vypsat pomocí:
print(data['avatar_url'])
API Githubu toho umí mnohem víc. Třeba na adrese https://api.github.com/emojis na tebe čeká slovník s adresami malých obrázků. (Tenhle slovník funguje jako vyhledávací tabulka.) Celé API je zdokumentováno na adrese developer.github.com.
Pomocí webových API se dají informace nejen číst, ale i měnit.
Na stránce github.com/pyvec/naucse.python.cz/stargazers je seznam lidí, kteří „ohvězdičkovali” tyto učební ateriály. Je jich zatím málo; pojďme se k nim pomocí webového API přidat.
Napřed svému tokenu (na Githubu v nastavení
Personal Accesss Tokens)
přidej právo public_repo.
Od teď token střež obzvlášť pečlivě, protože se pomocí
něj dají informace na Githubu i měnit.
Chceme-li měnit informace, musíme knihovně Requests
říct, aby použila jinou „HTTP metodu” než GET.
Co to přesně jsou HTTP metody je na trochu delší povídání
(viz Wikipedia),
ale stručně řečeno, pomocí GET se většinou stahuje
obsah, pomocí POST se přidává nový,
PUT mění něco, co už na webu existuje
a DELETE něco maže.
Jakou metodu poujeme závisí na tom, co chceme udělat;
většinou to bude POST, PUT nebo DELETE.
Podle dokumentace Githubu
se přidání hvězdičky dělá pomocí PUT
dotazu na adresu /user/starred/:owner/:repo.
Za :owner a :repo
dosadíš vlastníka a jméno repozitáře
(v našem případě pyvec a naucse.python.cz)
a PUT metodu zvolíš tak, že zavoláš místo get funkci put:
import requests
with open('token.txt') as soubor:
token = soubor.read().strip()
headers = {'Authorization': 'token ' + token}
stranka = requests.put('https://api.github.com/user/starred/pyvec/naucse.python.cz', headers=headers)
stranka.raise_for_status()
Tenhle dotaz nevrátí žádný text, ale na github.com/pyvec/naucse.python.cz/stargazers se můžeš přesvědčit, že to funguje.
Chceš-li hvězdičku zase odstranit, použij metodu
DELETE na stejnou adresu.
(Ale nezapomeň tam pak ★ zase vrátit! ☺)
{
"data": {
"sessionMaterial": {
"id": "session-material:2018/pyladies-praha-podzim-ntk:dict:2",
"title": "Github API",
"html": "\n \n \n\n <h1>Webové API</h1>\n<p>Jak už bylo řečeno v <a href=\"/2018/pyladies-praha-podzim-ntk/intro/json/\">lekci o JSON</a>,\nhlavní výhoda formátu JSON je, že se na Internetu rozšířil nejvíc.\nPojďme toho využít!</p>\n<p>Spousta webových služeb poskytuje takzvané\n<em>API</em> (z <em>application programming interface</em>,\nprogramátorské rozhraní), přes které je možné s danou\nslužbou komunikovat programově.\nMísto klikání na tlačítka a čtení stránek „očima”\ndostaneme data ve formátu, kterým rozumí počítače –\na v dnešní době to bude většinou formát JSON.</p>\n<p>Z minulých lekcí bys měla mít založený účet na github.com,\ntak se zkusme zeptat Githubu, co o nás ví.</p>\n<h2>Autorizace</h2>\n<p>První, a mnohdy nejsložitější, krok k použití API\nje přihlášení. Počítače se totiž přihlašují jinak\nnež lidi a problematika bezpečnosti a oprávnění by vydala na samostatný kurz.\nMy to uděláme co nejjednodušeji, ať se rychle dostaneme k jádru věci:</p>\n<ul>\n<li>Přihlaš se na <a href=\"https://github.com\">github.com</a>.</li>\n<li>Jdi na <a href=\"https://github.com/settings/tokens\">nastavení Personal Accesss Tokens</a>.</li>\n<li>Vytvoř si nový token ("Generate new token"). Nezaškrtávej žádná oprávnění navíc.</li>\n<li>Zkopíruj si heslo, které takto dostaneš, do souboru <code>token.txt</code>.</li>\n</ul>\n<div class=\"admonition warning\"><p class=\"admonition-title\">Pozor!</p>\n<p>Vygenerovaný kód je heslo, které držitele\nopravňuje pracovat s Githubem pod tvým jménem!\nDrž ho v tajnosti. Kdyby se přece jen dostalo „ven”, na stránce\n<a href=\"https://github.com/settings/tokens\">Personal Accesss Tokens</a> ho deaktivuj.</p>\n</div><h2>Requests</h2>\n<p>K práci s internetovými stránkami použijeme knihovnu Requests.\nV aktivovaném virtuálním prostředí si ji nainstaluj příkazem:</p>\n<div class=\"highlight\"><pre><span></span><span class=\"gp\">(env)$ </span>python -m pip install requests\n</pre></div><p>A potom v Pythonu zkus stáhnout nějakou stránku:</p>\n<div class=\"highlight\"><pre><span></span><span class=\"kn\">import</span> <span class=\"nn\">requests</span>\n\n<span class=\"c1\"># stažení stránky</span>\n<span class=\"n\">stranka</span> <span class=\"o\">=</span> <span class=\"n\">requests</span><span class=\"o\">.</span><span class=\"n\">get</span><span class=\"p\">(</span><span class=\"s1\">'https://github.com'</span><span class=\"p\">)</span>\n\n<span class=\"c1\"># ověření, že dotaz proběhl v pořádku</span>\n<span class=\"n\">stranka</span><span class=\"o\">.</span><span class=\"n\">raise_for_status</span><span class=\"p\">()</span>\n\n<span class=\"c1\"># vypsání obsahu</span>\n<span class=\"k\">print</span><span class=\"p\">(</span><span class=\"n\">stranka</span><span class=\"o\">.</span><span class=\"n\">text</span><span class=\"p\">)</span>\n</pre></div><p>Měl by se vypsat obsah stránky\n<a href=\"https://github.com\">https://github.com</a> –\nHTML kód, který se objeví když v prohlížeči dáš\n„Ukázat zdroj” (<em>View Page Source</em>, většinou <kbd>Ctrl</kbd>+<kbd>U</kbd>)\na ze kterého prohlížeč umí vykreslit stránku.</p>\n<p>Ale my nechceme obsah pro lidi.\nPodívejme se, co Github zpřístupňuje počítačům.</p>\n<h2>Uživatelský účet</h2>\n<p>Zkus, co dělá tento kód:</p>\n<div class=\"highlight\"><pre><span></span><span class=\"kn\">import</span> <span class=\"nn\">requests</span>\n\n<span class=\"k\">with</span> <span class=\"nb\">open</span><span class=\"p\">(</span><span class=\"s1\">'token.txt'</span><span class=\"p\">)</span> <span class=\"k\">as</span> <span class=\"n\">soubor</span><span class=\"p\">:</span>\n <span class=\"n\">token</span> <span class=\"o\">=</span> <span class=\"n\">soubor</span><span class=\"o\">.</span><span class=\"n\">read</span><span class=\"p\">()</span><span class=\"o\">.</span><span class=\"n\">strip</span><span class=\"p\">()</span>\n\n<span class=\"n\">headers</span> <span class=\"o\">=</span> <span class=\"p\">{</span><span class=\"s1\">'Authorization'</span><span class=\"p\">:</span> <span class=\"s1\">'token '</span> <span class=\"o\">+</span> <span class=\"n\">token</span><span class=\"p\">}</span>\n\n<span class=\"n\">stranka</span> <span class=\"o\">=</span> <span class=\"n\">requests</span><span class=\"o\">.</span><span class=\"n\">get</span><span class=\"p\">(</span><span class=\"s1\">'https://api.github.com/user'</span><span class=\"p\">,</span> <span class=\"n\">headers</span><span class=\"o\">=</span><span class=\"n\">headers</span><span class=\"p\">)</span>\n<span class=\"n\">stranka</span><span class=\"o\">.</span><span class=\"n\">raise_for_status</span><span class=\"p\">()</span>\n<span class=\"k\">print</span><span class=\"p\">(</span><span class=\"n\">stranka</span><span class=\"o\">.</span><span class=\"n\">text</span><span class=\"p\">)</span>\n</pre></div><p>Co se stalo? Tím, že jsi Githubu dala svůj token\n(načtený ze souboru, předaný přes slovník <code>headers</code>),\npoznal, že jde dotaz od tebe a vrátil nějaké informace\nve formátu JSON.</p>\n<p>Zkus řetězec <code>stranka.text</code> převést z JSON na slovník\na vypsat trochu srozumitelněji:</p>\n<div class=\"highlight\"><pre><span></span><span class=\"n\">data</span> <span class=\"o\">=</span> <span class=\"n\">json</span><span class=\"o\">.</span><span class=\"n\">loads</span><span class=\"p\">(</span><span class=\"n\">stranka</span><span class=\"o\">.</span><span class=\"n\">text</span><span class=\"p\">)</span>\n\n<span class=\"k\">print</span><span class=\"p\">(</span><span class=\"n\">json</span><span class=\"o\">.</span><span class=\"n\">dumps</span><span class=\"p\">(</span><span class=\"n\">data</span><span class=\"p\">,</span> <span class=\"n\">ensure_ascii</span><span class=\"o\">=</span><span class=\"bp\">True</span><span class=\"p\">,</span> <span class=\"n\">indent</span><span class=\"o\">=</span><span class=\"mi\">2</span><span class=\"p\">))</span>\n</pre></div><p>Teď už je lépe vidět celý tvůj profil\n(možná včetně neveřejných informací – proto musíš svůj token\nudržovat v tajnosti).</p>\n<p>S profilem, který máš v proměnné <code>data</code>,\nse dá pracovat jako s každým jiným slovníkem.\nTřeba adresu svého obrázku můžeš vypsat pomocí:</p>\n<div class=\"highlight\"><pre><span></span><span class=\"k\">print</span><span class=\"p\">(</span><span class=\"n\">data</span><span class=\"p\">[</span><span class=\"s1\">'avatar_url'</span><span class=\"p\">])</span>\n</pre></div><h2>API Githubu</h2>\n<p>API Githubu toho umí mnohem víc. Třeba na adrese\n<a href=\"https://api.github.com/emojis\">https://api.github.com/emojis</a> na tebe čeká\nslovník s adresami malých obrázků.\n(Tenhle slovník funguje jako vyhledávací tabulka.)\nCelé API je zdokumentováno na adrese\n<a href=\"https://developer.github.com/v3/\">developer.github.com</a>.</p>\n<h2>Interakce</h2>\n<p>Pomocí webových API se dají informace nejen číst, ale i měnit.</p>\n<p>Na stránce\n<a href=\"https://github.com/pyvec/naucse.python.cz/stargazers\">github.com/pyvec/naucse.python.cz/stargazers</a>\nje seznam lidí, kteří „ohvězdičkovali” tyto učební ateriály.\nJe jich zatím málo; pojďme se k nim pomocí webového API přidat.</p>\n<p>Napřed svému tokenu (na Githubu v nastavení\n<a href=\"https://github.com/settings/tokens\">Personal Accesss Tokens</a>)\npřidej právo <code>public_repo</code>.\nOd teď token střež obzvlášť pečlivě, protože se pomocí\nněj dají informace na Githubu i měnit.</p>\n<p>Chceme-li měnit informace, musíme knihovně Requests\nříct, aby použila jinou „HTTP metodu” než <code>GET</code>.\nCo to přesně jsou HTTP metody je na trochu delší povídání\n(viz <a href=\"https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods\">Wikipedia</a>),\nale stručně řečeno, pomocí <code>GET</code> se většinou stahuje\nobsah, pomocí <code>POST</code> se přidává nový,\n<code>PUT</code> mění něco, co už na webu existuje\na <code>DELETE</code> něco maže.\nJakou metodu poujeme závisí na tom, co chceme udělat;\nvětšinou to bude <code>POST</code>, <code>PUT</code> nebo <code>DELETE</code>.</p>\n<p>Podle <a href=\"https://developer.github.com/v3/activity/starring/#star-a-repository\">dokumentace Githubu</a>\nse přidání hvězdičky dělá pomocí <code>PUT</code>\ndotazu na adresu <code>/user/starred/:owner/:repo</code>.\nZa <code>:owner</code> a <code>:repo</code>\ndosadíš vlastníka a jméno repozitáře\n(v našem případě <code>pyvec</code> a <code>naucse.python.cz</code>)\na <code>PUT</code> metodu zvolíš tak, že zavoláš místo <code>get</code> funkci <code>put</code>:</p>\n<div class=\"highlight\"><pre><span></span><span class=\"kn\">import</span> <span class=\"nn\">requests</span>\n\n<span class=\"k\">with</span> <span class=\"nb\">open</span><span class=\"p\">(</span><span class=\"s1\">'token.txt'</span><span class=\"p\">)</span> <span class=\"k\">as</span> <span class=\"n\">soubor</span><span class=\"p\">:</span>\n <span class=\"n\">token</span> <span class=\"o\">=</span> <span class=\"n\">soubor</span><span class=\"o\">.</span><span class=\"n\">read</span><span class=\"p\">()</span><span class=\"o\">.</span><span class=\"n\">strip</span><span class=\"p\">()</span>\n\n<span class=\"n\">headers</span> <span class=\"o\">=</span> <span class=\"p\">{</span><span class=\"s1\">'Authorization'</span><span class=\"p\">:</span> <span class=\"s1\">'token '</span> <span class=\"o\">+</span> <span class=\"n\">token</span><span class=\"p\">}</span>\n\n<span class=\"n\">stranka</span> <span class=\"o\">=</span> <span class=\"n\">requests</span><span class=\"o\">.</span><span class=\"n\">put</span><span class=\"p\">(</span><span class=\"s1\">'https://api.github.com/user/starred/pyvec/naucse.python.cz'</span><span class=\"p\">,</span> <span class=\"n\">headers</span><span class=\"o\">=</span><span class=\"n\">headers</span><span class=\"p\">)</span>\n<span class=\"n\">stranka</span><span class=\"o\">.</span><span class=\"n\">raise_for_status</span><span class=\"p\">()</span>\n</pre></div><p>Tenhle dotaz nevrátí žádný text, ale na\n<a href=\"https://github.com/pyvec/naucse.python.cz/stargazers\">github.com/pyvec/naucse.python.cz/stargazers</a>\nse můžeš přesvědčit, že to funguje.</p>\n<p>Chceš-li hvězdičku zase odstranit, použij metodu\n<code>DELETE</code> na stejnou adresu.\n(Ale nezapomeň tam pak ★ zase vrátit! ☺)</p>\n\n\n "
}
}
}