API:Tutorial/cs

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.

Procházejte ukázkové aplikace na Toolforge

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:Main page 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

Request format

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ánek  
• list – získá seznam stránek odpovídajících určitému kritériu
• meta – 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:

api.php?action=query&list=search&srsearch=Craig%20Noone&format=json [zkuste v ApiSandbox]

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:Main page 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