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

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. For testing new accounts or test edits to pages, use the test wiki endpoint 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 $2 (adresa URL by obsahovala $3, což umožňuje načítání dat z wiki. Po parametru $4 přidejte další parametr, který označí, který ze tří typů modulu dotazu chcete provést: It tells the API which action to perform. The most popular action is query (the URL would contain action=query), which allows fetching data from a wiki. Following the action parameter, add another parameter to indicate which one of the three query module types you want to perform:

• 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í.

Request format

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 [$2 API modulu nápovědy]. They might all be running a different version of MediaWiki and in turn the API. Some module parameters supported in one version might be deprecated or removed in others. You could learn about that in each module's documentation via API help module.
• 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 $2. See list of Administrators of Wikimedia projects. Read more about this topic on 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