API:Návod k použití

This page is a translated version of the page API:Tutorial and the translation is 100% complete.

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á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:Search .

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:Etiquette .
  • 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:Tokens .

Zdroje