API:Průvodce
Tato stránka je součástí dokumentace k API Action MediaWiki. |
V tomto návodu se dozvíte o MediaWiki Action API, jak jej používat, formát požadavku, jednoduchý dotaz a příklady projektů využívajících Action API.
Přehled rozhraní MediaWiki Action API
MediaWiki Action API je REST úplná webová služba, která uživatelům umožňuje provádět určité wiki-akce, např. vytváření stránek, ověřování, analyzování, vyhledávání atd. API:Hlavní stránka je dobrým výchozím bodem pro pochopení API.
Váš program odesílá požadavky do API, aby získal přístup k funkcím wiki. Například přihlášení na wiki, vytvoření a úpravu stránky, vyhledání názvu, vyhledání text obsahu nebo analýzu obsahu. Action API je k dispozici pro vývojáře třetích stran, vývojáře rozšíření Wikimedie a správce wiki stránek.
Na pravém postranním panelu této stránky je mnoho funkcí, které rozhraní API podporuje, seskupených podle kategorií. Před odesláním požadavků na wiki server si nejprve přečtěte stránky s přehledem, jako jsou formáty dat, chyby a varování a Action API FAQ.
Jak používat MediaWiki Action API
Můžete požádat o data ze strany klienta na server přes HTTP a získat odpověď zpět ve standardním formátu (obvykle JSON). Požadavek se skládá z koncového bodu a sady parametrů. Existují dva typy požadavků, které lze provést: GET a POST. U požadavku GET parametr v adrese URL obsahuje řetězec dotazu. U požadavku POST naformátujete parametry ve formátu JSON.
Formát požadavku
Všechny wikiny Wikimedie mají koncové body v tomto formátu http://example.org/w/api.php
. Chcete-li pracovat na hlavním webu MediaWiki nebo anglické Wikipedii, použijte související koncový bod. Například anglická Wikipedie https://en.wikipedia.org/w/api.php
. Pro testování nových účtů nebo testování úprav stránek použijte koncový bod testovací wiki https://test.wikipedia.org/w/api.php
.
Do řetězce dotazu v adrese URL přidejte parametr action
. Říká API, kterou akci má provést. Nejoblíbenější akcí je query
(adresa URL by obsahovala action=query
), což umožňuje načítání dat z wiki. Po parametru action
přidejte další parametr, který označí, který ze tří typů modulu dotazu chcete provést:
prop
- získá vlastnosti stráneklist
- získá seznam stránek odpovídajících určitému kritériumeta
- získá meta informace o wiki a o uživateli
Nakonec zahrňte parametr format
, který API říká, v jakém formátu má získat výsledky. Doporučený formát je JSON. API v minulosti podporovalo jiné výstupní formáty, ale obecně se nedoporučují.
Jednoduchý dotaz
Vezměme si příklad jednoduchého dotazu, abychom pochopili, jak by vypadal typický požadavek a odpověď GET v kontextu Action API.
Pojďme hledat název na wiki. Použijeme modul search
zdokumentovaný na API:Hledání .
Dotazování přes GET
Chcete-li vyhledat názvy stránek nebo obsah odpovídající Craig Noone
, bude adresa URL požadavku HTTP GET:
Vysvětlení každé části adresy URL:
http://en.wikipedia.org/w/api.php
je hlavní koncový bod. V tomto případě je to anglická Wikipedie.action=query
znamená načíst data z wiki.list=search
znamená získat seznam stránek odpovídajících kritériím.srsearch=Craig%20Noone
označuje název stránky nebo obsah, který se má hledat.%20
označuje znak mezery v adrese URL.format=json
označuje výstup JSON, což je doporučený výstupní formát.
Odpověď
Odpovědí je dokument ve formátu JSON se seznamem názvů stránek, které odpovídají Craig Noone:
{
"batchcomplete": "",
"continue": {
"sroffset": 10,
"continue": "-||"
},
"query": {
"searchinfo": {
"totalhits": 210
},
"search": [
{
"ns": 0,
"title": "Craig Noone",
"pageid": 18846922,
"size": 22548,
"wordcount": 1771,
"snippet": "<span class=\"searchmatch\">Craig</span> Stephen <span class=\"searchmatch\">Noone</span> (born 17 November 1987) is an English professional footballer who plays as a winger for Bolton Wanderers. Born in Kirkby, he has also",
"timestamp": "2018-11-02T22:25:45Z"
},
{
"ns": 0,
"title": "Noone",
"pageid": 32906333,
"size": 553,
"wordcount": 64,
"snippet": "<span class=\"searchmatch\">Noone</span> is a surname that may refer to: <span class=\"searchmatch\">Craig</span> <span class=\"searchmatch\">Noone</span> (born 1987), English football midfielder Jimmie <span class=\"searchmatch\">Noone</span> (1895–1944), American jazz clarinetist Kathleen",
"timestamp": "2015-08-16T05:16:17Z"
}
...
]
}
}
Příklady projektů využívajících Action API
Některé příklady projektů ve Wikimedii, které používají Action API:
- Wikipedia iOS App, jehož jednou z funkcí je vyhledávání wiki stránek v blízkosti vaší polohy.
- Roboti, kteří fungují na wiki. Pywikibot je robotický rámec napsaný v Pythonu, který je propojen s MediaWiki API, které používá mnoho vývojářů robotů.
- Použití API při vizualizaci dat získaných z wiki. Jako je tato [úhledná vizualizace na http://listen.hatnote.com/], která ukazuje úpravy provedené na Wikipedii v reálném čase.
Další poznámky
- Několik stránek používá MediaWiki. Všichni možná používají jinou verzi MediaWiki a zase API. Některé parametry modulu podporované v jedné verzi mohou být v jiných zastaralé nebo odstraněny. O tom byste se mohli dozvědět v dokumentaci každého modulu prostřednictvím API modulu nápovědy.
- Pokud chcete provádět mnoho volání API a možná provozovat velmi zaneprázdněné a aktivní roboty, promluvte si předem s administrátory wiki, aby vás neblokovali. Viz seznam administrátorů projektů Wikimedie. Přečtěte si více o tomto tématu na API:Etiketa .
- Všechny akce upravující data, jako je protokolování, úprava nebo přesun stránky a sledování nebo hlídání změn, by vyžadovaly tokeny. Abyste mohli pokračovat, budete muset získat tokeny prostřednictvím API: Tokeny .
Zdroje
- Použijte Special:APISandbox k experimentování s Action API. Můžete si pohrát s podporovanými akcemi, zadat hodnotu parametrů a odeslat požadavky do rozhraní API, abyste viděli výsledky na stejné stránce.
- Wikimedia výpisy, také s nimi můžete pracovat lokálně.
- Přečtěte si výukové programy: Úvod do API a Co je REST — Jednoduché vysvětlení pro začátečníky.
- Nápověda MediaWiki API poskytuje automaticky generovanou dokumentaci API všech podporovaných modulů.
- API:Hlavní stránka poskytuje přehled rozhraní Action API.
- Introduction to MediaWiki API od User:Roan_Kattouw_(WMF) na San Francisco Hackathon, 2012. Tento výukový průvodce je doplněn videem.
- GitHub: Ukázky MediaWiki API