Pomocník API MediaWiki
Toto je automaticky generovaná dokumentačná stránka MediaWiki Action API.
Všeobecné informácie
Stav: API MediaWiki je vyspelé a stabilné rozhranie, ktoré je aktívne podporované a vylepšované. Hoci sa tomu snažíme vyhýbať, občas môžeme potrebovať vykonať nekompatibilné zmeny; prihláste sa na odber emailovej konferencie mediawiki-api-announce, aby ste boli informovaní o aktualizáciách.
Chybné požiadavky: Keď sa do API pošlú chybné požiadavky, pošle sa HTTP hlavička s kľúčom „MediaWiki-API-Error“ a hodnota hlavičky aj vrátený chybový kód budú nastavené na rovnakú hodnotu. Ďalšie informácie nájdete na API: Chyby a upozornenia.
Testovanie: Na jednoduché testovanie požiadaviek API pozri Special:ApiSandbox.
Metódy požiadaviek
Požiadavky Action API môžu používať metódy GET a POST. Uprednostňujte metódu GET, ktorá umožňuje smerovať požiadavky na rýchlejšie replikačné servery a ukladať odpovede do vyrovnávacej pamäte, pokiaľ by dĺžka URL s parametrami neprekročila jej limit (bežne 8000 bajtov) alebo modul neprijíma iba požiadavky POST.
Parametre požiadaviek POST sa môžu posielať v dotazovej časti URL požiadavky (ako pri požiadavkách GET) aj v tele požiadavky POST a miešanie oboch spôsobov v jednej požiadavke je povolené. Určité parametre, ako napríklad heslá, sa musia posielať v tele požiadavky. Ak sa rovnaký parameter pošle ako súčasť URL aj v tele požiadavky, musí mať na oboch miestach rovnakú hodnotu.
Dátové typy
Vstup do MediaWiki by mal byť NFC-normalizované UTF-8. MediaWiki sa môže pokúsiť konvertovať iný vstup, ale môže to spôsobiť zlyhanie niektorých operácií (napríklad úprav s kontrolami MD5).
Parametre, ktoré prijímajú viacero hodnôt, sa bežne posielajú s hodnotami oddelenými znakom zvislej čiary, napr. param=value1|value2 alebo param=value1%7Cvalue2. Ak hodnota musí obsahovať znak zvislej čiary, použite ako oddeľovač U+001F (Unit Separator) a pred hodnotu vložte U+001F, napr. param=%1Fvalue1%1Fvalue2.
Niektoré typy parametrov v požiadavkách API vyžadujú ďalšie vysvetlenie:
- boolean
Logické (boolean) parametre fungujú ako HTML zaškrtávacie polia: ak je parameter zadaný, bez ohľadu na hodnotu sa považuje za pravdivý (true). Pre hodnotu nepravda (false) parameter úplne vynechajte.
- expiry
Hodnoty vypršania môžu byť relatívne (napr. 5 months alebo 2 weeks) alebo absolútne (napr. 2014-09-18T12:34:56Z). Ak vypršanie nemá nastať, použite infinite, indefinite, infinity alebo never.
- timestamp
Časové pečiatky možno zadať v niekoľkých formátoch, podrobnosti nájdete vo vstupných formátoch knižnice Timestamp zdokumentovaných na mediawiki.org. Odporúča sa dátum a čas podľa ISO 8601: 2001-01-15T14:56:00Z. Na zadanie aktuálneho času možno použiť reťazec now.
Limity
Väčšina modulov API môže prijať až 50 vstupov v parametroch s viacerými hodnotami a môže vrátiť až 500 výsledkov na jeden dotaz (50 výsledkov pre pomalé dotazy).
Pre používateľov s právom apihighlimits (Boti a Správcovia) sa limity zvyšujú na 500 vstupov a 5 000 výsledkov (500 výsledkov pre pomalé dotazy).
Šablónové parametre
Šablónové parametre podporujú prípady, keď modul API potrebuje hodnotu pre každú hodnotu nejakého iného parametra. Ak by napríklad existoval modul API na vyžiadanie ovocia, mohol by mať parameter fruits na určenie, ktoré ovocie sa žiada, a šablónový parameter {fruit}-quantity na určenie, koľko kusov každého ovocia sa žiada. Klient API, ktorý chce 1 jablko, 5 banánov a 20 jahôd, by potom mohol vytvoriť požiadavku ako fruits=apples|bananas|strawberries&apples-quantity=1&bananas-quantity=5&strawberries-quantity=20.
Hlavný modul
- Zdroj: MediaWiki
- Licencia: GPL-2.0-or-later
Specify the action to perform, the format of the response, and options that apply to all API modules.
- action
Ktorá akcia sa má vykonať. Tento parameter by sa mal posielať ako súčasť URL požiadavky (nie tela POST), aby sa uľahčilo ladenie, analytika a smerovanie alebo filtrovanie požiadaviek.
- acquiretempusername
- Získať meno dočasného používateľa a uložiť ho do aktuálnej relácie, ak je povolené vytváranie dočasných účtov a aktuálny používateľ je odhlásený. Ak už bolo nejaké meno uložené, vráti to isté meno.
- block
- Zablokovať používateľa.
- changeauthenticationdata
- Zmeniť autentifikačné údaje aktuálneho používateľa.
- changecontentmodel
- Zmeniť model obsahu stránky
- checktoken
- Skontrolovať platnosť tokenu z action=query&meta=tokens.
- clearhasmsg
- Vymaže príznak
hasmsgpre aktuálneho používateľa. - clientlogin
- Prihlásiť sa na wiki pomocou interaktívneho postupu.
- compare
- Získať rozdiel medzi dvoma stránkami.
- createaccount
- Vytvoriť nový používateľský účet.
- delete
- Vymazať stránku.
- edit
- Vytvárať a upravovať stránky.
- emailuser
- Poslať email používateľovi.
- embedvideo
- Get generated video embed code for given parameters.
- expandtemplates
- Expanduje všetky šablóny vo wikitexte.
- feedcontributions
- Vráti kanál príspevkov používateľa.
- feedrecentchanges
- Vráti kanál posledných zmien.
- feedwatchlist
- Vráti kanál zoznamu sledovaných.
- filerevert
- Vrátiť súbor na starú verziu.
- googleplusprofileinfo
- Makes a request to the Google+ api to find out some personal information about a given user.
- help
- Zobraziť pomocníka pre zadané moduly.
- imagerotate
- Otočiť jeden alebo viac obrázkov.
- import
- Importovať stránku z inej wiki alebo z XML súboru.
- jsonconfig
- Allows direct access to JsonConfig subsystem.
- languagesearch
- Vyhľadávať názvy jazykov v akomkoľvek písme.
- linkaccount
- Prepojiť účet od poskytovateľa tretej strany s aktuálnym používateľom.
- login
- Prihlásiť sa a získať autentifikačné cookies.
- logout
- Odhlásiť sa a vymazať údaje relácie.
- managetags
- Vykonávať úlohy správy súvisiace so značkami zmien.
- mergehistory
- Zlúčiť históriu stránok.
- move
- Presunúť stránku.
- opensearch
- Vyhľadávať na wiki pomocou protokolu OpenSearch.
- options
- Zmeniť nastavenia aktuálneho používateľa.
- paraminfo
- Získať informácie o moduloch API.
- parse
- Parsuje obsah a vráti výstup parsera.
- patrol
- Strážiť stránku alebo revíziu.
- protect
- Zmeniť úroveň ochrany stránky.
- purge
- Vyprázdniť vyrovnávaciu pamäť pre zadané názvy stránok.
- query
- Získavať dáta z MediaWiki a o MediaWiki.
- removeauthenticationdata
- Odstrániť autentifikačné údaje aktuálneho používateľa.
- resetpassword
- Poslať používateľovi email na obnovenie hesla.
- revisiondelete
- Vymazávať a obnovovať revízie.
- rollback
- Vrátiť poslednú úpravu stránky.
- rsd
- Exportovať schému RSD (Really Simple Discovery).
- setnotificationtimestamp
- Aktualizovať časovú pečiatku upozornení pre sledované stránky.
- setpagelanguage
- Zmeniť jazyk stránky.
- tag
- Pridávať alebo odstraňovať značky zmien z jednotlivých revízií alebo položiek záznamov.
- unblock
- Odblokovať používateľa.
- undelete
- Obnoviť revízie vymazanej stránky.
- unlinkaccount
- Odstrániť prepojený účet tretej strany od aktuálneho používateľa.
- upload
- Nahrať súbor alebo získať stav čakajúcich nahraní.
- userrights
- Zmeniť členstvo používateľa v skupinách.
- validatepassword
- Overiť heslo voči politikám hesiel wiki.
- watch
- Pridávať alebo odstraňovať stránky zo zoznamu sledovaných aktuálneho používateľa.
- cspreport
- Interné. Používajú prehliadače na hlásenie porušení pravidiel Content Security Policy. Tento modul by sa nemal nikdy používať, s výnimkou automatického použitia webovým prehliadačom kompatibilným s CSP.
- editcheckreferenceurl
- Interné. Check the status of a URL for use as a reference.
- sanitize-mapdata
- Interné. Performs data validation for Kartographer extension
- stashedit
- Interné. Pripraviť úpravu v zdieľanej vyrovnávacej pamäti.
- visualeditor
- Interné. Returns HTML5 for a page from the Parsoid service.
- visualeditoredit
- Interné. Save an HTML5 page to MediaWiki (converted to wikitext via the Parsoid service).
- Jedna z nasledujúcich hodnôt: acquiretempusername, block, changeauthenticationdata, changecontentmodel, checktoken, clearhasmsg, clientlogin, compare, createaccount, delete, edit, emailuser, embedvideo, expandtemplates, feedcontributions, feedrecentchanges, feedwatchlist, filerevert, googleplusprofileinfo, help, imagerotate, import, jsonconfig, languagesearch, linkaccount, login, logout, managetags, mergehistory, move, opensearch, options, paraminfo, parse, patrol, protect, purge, query, removeauthenticationdata, resetpassword, revisiondelete, rollback, rsd, setnotificationtimestamp, setpagelanguage, tag, unblock, undelete, unlinkaccount, upload, userrights, validatepassword, watch, cspreport, editcheckreferenceurl, sanitize-mapdata, stashedit, visualeditor, visualeditoredit
- Predvolené: help
- format
Formát výstupu.
- json
- Vypísať dáta vo formáte JSON.
- jsonfm
- Vypísať dáta vo formáte JSON (pekne naformátované v HTML).
- none
- Nevypísať nič.
- php
- Vypísať dáta v serializovanom formáte PHP.
- phpfm
- Vypísať dáta v serializovanom formáte PHP (pekne naformátované v HTML).
- rawfm
- Vypísať dáta vrátane ladiacich prvkov vo formáte JSON (pekne naformátované v HTML).
- xml
- Vypísať dáta vo formáte XML.
- xmlfm
- Vypísať dáta vo formáte XML (pekne naformátované v HTML).
- Jedna z nasledujúcich hodnôt: json, jsonfm, none, php, phpfm, rawfm, xml, xmlfm
- Predvolené: jsonfm
- maxlag
Maximálne oneskorenie (maxlag) možno použiť, keď je MediaWiki nainštalovaná na klastri s replikovanou databázou. Aby akcie nespôsobovali ďalšie replikačné oneskorenie, tento parameter môže prinútiť klienta čakať, kým replikačné oneskorenie neklesne pod zadanú hodnotu. V prípade nadmerného oneskorenia sa vráti chybový kód maxlag so správou ako Waiting for $host: $lag seconds lagged.
Ďalšie informácie nájdete na stránke Manuál: parameter maxlag.- Typ: celé číslo
- smaxage
Nastaviť HTTP hlavičku riadenia vyrovnávacej pamäte
s-maxagena tento počet sekúnd. Chyby sa nikdy neukladajú do vyrovnávacej pamäte.- Typ: celé číslo
- Hodnota nesmie byť menšia ako 0.
- Predvolené: 0
- maxage
Nastaviť HTTP hlavičku riadenia vyrovnávacej pamäte
max-agena tento počet sekúnd. Chyby sa nikdy neukladajú do vyrovnávacej pamäte.- Typ: celé číslo
- Hodnota nesmie byť menšia ako 0.
- Predvolené: 0
- assert
Overiť, že používateľ je prihlásený (prípadne aj ako dočasný používateľ), ak je nastavené na user, nie je prihlásený, ak je nastavené na anon, alebo má právo bota, ak je nastavené na bot.
- Jedna z nasledujúcich hodnôt: anon, bot, user
- assertuser
Overiť, že aktuálny používateľ je uvedený používateľ.
- Typ: používateľ, podľa ľubovoľného z používateľské meno a Dočasný používateľ
- requestid
Akákoľvek tu zadaná hodnota bude zahrnutá do odpovede. Môže sa použiť na rozlíšenie požiadaviek.
- servedby
Zahrnúť do výsledkov názov hostiteľa, ktorý obslúžil požiadavku.
- Typ: logická hodnota (boolean) (podrobnosti)
- curtimestamp
Zahrnúť do výsledku aktuálnu časovú pečiatku.
- Typ: logická hodnota (boolean) (podrobnosti)
- responselanginfo
Zahrnúť do výsledku jazyky použité pre uselang a errorlang.
- Typ: logická hodnota (boolean) (podrobnosti)
- origin
Pri prístupe k API pomocou AJAX požiadavky medzi doménami (CORS) nastavte tento parameter na pôvodnú doménu. Musí byť zahrnutý v každej predbežnej (pre-flight) požiadavke, a preto musí byť súčasťou URL požiadavky (nie tela POST).
Pri autentifikovaných požiadavkách sa musí presne zhodovať s jedným z pôvodov v hlavičke
Origin, takže musí byť nastavený napríklad na https://en.wikipedia.org alebo https://meta.wikimedia.org. Ak sa tento parameter nezhoduje s hlavičkouOrigin, vráti sa odpoveď 403. Ak sa tento parameter zhoduje s hlavičkouOrigina pôvod je povolený, nastavia sa hlavičkyAccess-Control-Allow-OriginaAccess-Control-Allow-Credentials.Pri neautentifikovaných požiadavkách zadajte hodnotu *. Tým sa nastaví hlavička
Access-Control-Allow-Origin, aleAccess-Control-Allow-Credentialsbudefalsea všetky údaje špecifické pre používateľa budú obmedzené.- crossorigin
Pri prístupe k API pomocou AJAX požiadavky medzi doménami (CORS) a použití poskytovateľa relácie, ktorý je bezpečný proti útokom CSRF (cross-site request forgery), ako je napríklad OAuth, použite tento parameter namiesto
origin=*, aby bola požiadavka autentifikovaná (t. j. nie odhlásená). Musí byť zahrnutý v každej predbežnej (pre-flight) požiadavke, a preto musí byť súčasťou URL požiadavky (nie tela POST).Upozorňujeme, že väčšina poskytovateľov relácií vrátane štandardných relácií založených na cookies nepodporuje autentifikované CORS a nemožno ich použiť s týmto parametrom.
- Typ: logická hodnota (boolean) (podrobnosti)
- uselang
Jazyk, ktorý sa má použiť na preklady správ. action=query&meta=siteinfo&siprop=languages vráti zoznam kódov jazykov. Môžete zadať user, aby sa použil jazyk z nastavení aktuálneho používateľa, alebo content, aby sa použil jazyk obsahu tejto wiki.
- Predvolené: user
- variant
Variant jazyka. Funguje len vtedy, ak základný jazyk podporuje konverziu variantov.
- errorformat
Formát, ktorý sa má použiť pre textový výstup upozornení a chýb
- plaintext
- Wikitext s odstránenými HTML značkami a nahradenými entitami.
- wikitext
- Neparsovaný wikitext.
- html
- HTML
- raw
- Kľúč správy a parametre.
- none
- Žiadny textový výstup, iba chybové kódy.
- bc
- Formát používaný pred MediaWiki 1.29. errorlang a errorsuselocal sa ignorujú.
- Jedna z nasledujúcich hodnôt: bc, html, none, plaintext, raw, wikitext
- Predvolené: bc
- errorlang
Jazyk, ktorý sa má použiť pre upozornenia a chyby. action=query&meta=siteinfo&siprop=languages vráti zoznam kódov jazykov. Zadajte content, aby sa použil jazyk obsahu tejto wiki, alebo uselang, aby sa použila rovnaká hodnota ako v parametri uselang.
- Predvolené: uselang
- errorsuselocal
Ak je zadané, chybové texty budú používať lokálne prispôsobené správy z menného priestoru MediaWiki.
- Typ: logická hodnota (boolean) (podrobnosti)
- Pomocník pre hlavný modul.
- api.php?action=help [otvoriť na pieskovisku]
- Celý pomocník na jednej stránke.
- api.php?action=help&recursivesubmodules=1&toc [otvoriť na pieskovisku]
Poďakovanie
Vývojári API:
- Yuri Astrakhan (tvorca, vedúci vývojár sep 2006 – sep 2007)
- Roan Kattouw (vedúci vývojár sep 2007 – 2009)
- Victor Vasiliev
- Bryan Tong Minh
- Sam Reed
- Brad Jorsch (vedúci vývojár 2013 – 2020)
Svoje komentáre, návrhy a otázky posielajte na mediawiki-api@lists.wikimedia.org alebo nahláste chybu na https://phabricator.wikimedia.org/.