Pomoč za API MediaWiki

To je samodejno ustvarjena dokumentacijska stran za dejanja API-ja MediaWiki.

Splošne informacije

Stanje: MediaWiki API je zrel in stabilen vmesnik, ki se aktivno vzdržuje in izboljšuje. Čeprav se temu poskušamo izogniti, bomo morda morali občasno izvesti pomembne spremembe. Za obveščanje o posodobitvah se naročite na dopisni seznam mediawiki-api-announce.

Napačni zahtevki: Ko so API-ju poslani napačni zahtevki, bo poslana glava HTTP s ključem »MediaWiki-API-Error«, nato pa bosta vrednost glave in koda napake, poslani nazaj, nastavljeni na isto vrednost. Za več informacij glejte API:Napake in opozorila.

Metode zahtevka

Zahtevki API-ja za dejanja lahko uporabljajo metodi GET in POST. Raje uporabite metodo GET, ki omogoča usmerjanje zahetvkov na hitrejše replikacijske strežnike in shranjevanje odgovorov v predpomnilnik, razen če bi dolžina URL-ja s parametri presegala omejitev dolžine (običajno 8000 bajtov) ali če modul sprejema samo zahtevke POST.

Parametri za zahtevke POST se lahko pošljejo v poizvedbenem delu URL-ja zahtevka (kot pri zahtevkih GET) in v telesu zahtevka POST, dovoljena pa je tudi kombinacija obeh načinov v enem zahtevku. Nekateri parametri, kot so gesla, morajo biti poslani v telesu zahtevka. Če je isti parameter poslan kot del URL-ja in tudi v telesu zahtevka, mora imeti na obeh mestih enako vrednost.

Vrste podatkov

Vhodni podatki za MediaWiki morajo biti v NFC-normaliziranem UTF-8. MediaWiki lahko poskusi pretvoriti druge podatke, vendar lahko to povzroči, da nekatere operacije (npr. urejanja s preverjanji MDS) ne bodo uspele.

boolean

Boolovi parametri delujejo kot potrditvena polja HTML: Če je parameter določen, se ne glede na vrednost šteje za resničnega. Za vrednost »false« parameter v celoti izpustite.

expiry

Vrednosti časa preteka so lahko relativne (npr. 5 months ali 2 weeks ) ali absolutne (npr. 2014-09-18T12:34:56Z). Če ne želite določiti časa preteka, uporabite infinite , indefinite, infinity ali never.

timestamp

Časovne žige je mogoče določiti v več oblikah, za podrobnosti glejte vhodne oblike zapisa v knjižnici Timestamp, dokumentirane na mediawiki.org. Priporočen je datum in čas ISO 8601: 2001-01-15T14:56:00Z. Za določitev trenutnega časovnega žiga se lahko uporabi niz now.

Omejitve

Večina API-modulov lahko sprejme do 50 vhodov v večvrednostnih parametrih in lahko vrne do 500 rezultatov na poizvedbo (50 rezultatov za počasne poizvedbe).

Za uporabnike s pravico apihighlimits (Boti in Administratorji) so omejitve povečane na 500 vhodov in 5.000 zadetkov (500 zadetkov za počasne poizvedbe).

Parametri predloge

Dinamični parametri (parametri predloge) podpirajo primere, ko API-modul potrebuje vrednost za vsako vrednost nekega drugega parametra. Če bi na primer obstajal API-modul za zahtevo po sadju, bi lahko imel parameter sadje, ki določa, katero sadje se zahteva, in dinamični parameter {sadje}-količina, ki določa, koliko posameznega sadja naj se zahteva. API-odjemalec, ki želi 1 jabolko, 5 banan in 20 jagod, bi lahko nato podal zahtevek, kot je sadje=jabolka|banane|jagode&jabolka-količina=1&bananas-količina=5&jagode-količina=20.

Glavni modul

Specify the action to perform, the format of the response, and options that apply to all API modules.

Specifični parametri:
action

Katero dejanje izvesti. Ta parameter je treba poslati kot del URL-ja zahtevka (ne telesa POST) za lažjo uporabo pri odpravljanju napak, analitiki in usmerjanju ali filtriranju zahtevkov.

acquiretempusername
Pridobite začasno uporabniško ime in ga shranite v trenutno sejo, če je omogočeno ustvarjanje začasnega računa in je trenutni uporabnik odjavljen. Če je bilo ime že shranjeno, vrne isto ime.
block
Blokiraj uporabnika.
changeauthenticationdata
Sprememba avtentikacijskih podatkov za trenutnega uporabnika.
changecontentmodel
Sprememba vsebinskega modela strani
checktoken
Kontrola veljavnosti žetona iz action=query&meta=tokens.
clearhasmsg
Počisti zastavico hasmsg za trenutnega uporabnika.
clientlogin
Prijava v viki z uporabo interaktivnega toka.
compare
Ugotovitev razlike med dvema stranema.
createaccount
Ustvaritev novega uporabniškega računa.
delete
Izbriše stran.
edit
Ustvarjanje in urejanje strani.
emailuser
Pošiljanje e-pisma uporabniku.
expandtemplates
Razširi vse predloge v vikibesedilu.
feedcontributions
Vrnitev vira prispevkov uporabnika.
feedrecentchanges
Vrne vir zadnjih sprememb
feedwatchlist
Vrne vir nadzornega seznama.
filerevert
Vrnitev datoteke na staro različico.
help
Prikaz pomoči za navedene module.
imagerotate
Zasuk ene ali več slik.
import
Uvoz strani iz drugega vikija ali iz datoteke XML.
languagesearch
Poišče imena jezikov v kateri koli pisavi.
linkaccount
Povezava računa tretjega ponudnika s trenutnim uporabnikom.
login
Prijava in pridobitev avtentikacijskih piškotkov.
logout
Odjava in počiščenje podatkov seje.
managetags
Izvajanje nalog upravljanja v zvezi s spremembami oznak.
mergehistory
Združevanje zgodovine strani.
move
Prestavi stran.
opensearch
Iskanje po vikiju s protokolom OpenSearch.
options
Sprememba nastavitev trenutnega uporabnika.
paraminfo
Pridobitev informacij o modulih API-ja.
parse
Razčlemba vsebine in vrnitev izhoda razčlenjevalnika.
patrol
Patruljiranje strani ali redakcije.
protect
Sprememba ravni zaščite strani.
purge
Počisti predpomnilnik za dane naslove.
query
Pridobi podatke MediaWikija in o MediaWikiju.
removeauthenticationdata
Odstranitev avtentikacijskih podatkov za trenutnega uporabnika.
resetpassword
Pošiljanje e-pošte za ponastavitev gesla uporabniku.
revisiondelete
Izbriše in odizbriše redakcije.
rollback
Razveljavitev zadnjega urejanja strani.
rsd
Izvoz sheme RSD (Really Simple Discovery).
setnotificationtimestamp
Posodobitev časovnega žiga obvestila za opazovane strani.
setpagelanguage
Sprememba jezika strani.
tag
Dodajanje ali odstranjevanje oznak posameznih redakcij ali dnevniških vnosov.
unblock
Odblokiranje uporabnika.
undelete
Odizbris redakcij izbrisane strani.
unlinkaccount
Odstranitev povezanega računa tretje stranke s trenutnega uporabnika.
upload
Naložitev datoteke ali pridobitev statusa čakajočih nalaganj.
userrights
Sprememba članstva uporabnika v skupinah.
validatepassword
Preverba gesla glede na pravila vikija o geslih.
watch
Dodatek ali odstranitev strani z nadzornega seznama
webapp-manifest
Vrne manifest »webapp«.
cspreport
Interno. Ta modul uporabljajo brskalniki za poročanje o kršitvah pravilnika o varnosti vsebine. Ne smete ga nikoli uporabljati, razen če ga samodejno uporablja spletni brskalnik, združljiv s CSP.
editcheckreferenceurl
Interno. Check the status of a URL for use as a reference.
stashedit
Interno. Priprava urejanja v skupnem predpomnilniku.
visualeditor
Interno. Vrne HTML5 za stran iz storitve Parsoid.
visualeditoredit
Interno. Shrani stran HTML5 v MediaWiki (s storitvijo Parsoid pretvorjeno v vikibesedilo).
Ena od naslednjih vrednosti: acquiretempusername, block, changeauthenticationdata, changecontentmodel, checktoken, clearhasmsg, clientlogin, compare, createaccount, delete, edit, emailuser, expandtemplates, feedcontributions, feedrecentchanges, feedwatchlist, filerevert, help, imagerotate, import, 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, webapp-manifest, cspreport, editcheckreferenceurl, stashedit, visualeditor, visualeditoredit
Privzeto: help
format

Oblika izhoda.

json
Izhodni podatki v formatu JSON.
jsonfm
Izhodni podatki v formatu JSON (lep izpis v HTML-ju).
none
Brez izpisa.
php
Izhodni podatki v serializiranem formatu PHP.
phpfm
Izhodni podatki v serializiranem formatu PHP (lep izpis v HTML-ju).
rawfm
Izhodni podatki, vključno z elementi za odpravljanje napak, v formatu JSON (lep izpis v HTML-ju).
xml
Izhodni podatki v formatu XML.
xmlfm
Izhodni podatki v formatu XML (lep izpis v HTML-ju).
Ena od naslednjih vrednosti: json, jsonfm, none, php, phpfm, rawfm, xml, xmlfm
Privzeto: jsonfm
maxlag

Največja zakasnitev se lahko uporabi, če je MediaWiki nameščen v gruči z replicirano podatkovno zbirko. Če želite prihraniti dejanja, ki bi povzročila večjo zakasnitev replikacije spletnega mesta, lahko s tem parametrom odjemalec počaka, da je zakasnitev replikacije manjša od določene vrednosti. V primeru prevelike zakasnitve se vrne koda napake maxlag s sporočilom, kot je Waiting for $host: $lag seconds lagged.
Za več informacij glejte Manual: Maxlag parameter.

Vtipkajte: celo število
smaxage

Nastavite kontrolno glavo s-maxage predpomnenja HTTP na to število sekund. Napake se nikoli ne predpomnijo.

Vtipkajte: celo število
The Vrednost ne sme biti manjša od 0.
Privzeto: 0
maxage

Nastavite kontrolno glavo max-age predpomnenja HTTP na to število sekund. Napake se nikoli ne predpomnijo.

Vtipkajte: celo število
The Vrednost ne sme biti manjša od 0.
Privzeto: 0
assert

Preveri, da je uporabnik prijavljen (vključno z morebitno začasno prijavo), če je nastavljeno na user, da ni prijavljen, če je nastavljeno na anon, in da ima uporabniško pravico bota, če je nastavljeno na bot.

Ena od naslednjih vrednosti: anon, bot, user
assertuser

Preveri, ali je trenutni uporabnik poimenovani uporabnik.

Vrsta: uporabnik, ki ustreza čemur koli od uporabniško ime in Začasni uporabnik
requestid

V odgovor bo vključena vsaka tu navedena vrednost. Lahko se uporablja za razločevanje zahtevkov.

servedby

V rezultate vključi ime gostitelja, ki je posredoval zahtevek.

Tip: Boolov (podrobnosti)
curtimestamp

V rezultat vključi trenutni časovni žig.

Tip: Boolov (podrobnosti)
responselanginfo

V rezultat vključi jezike, ki se uporabljajo za uselang in errorlang.

Tip: Boolov (podrobnosti)
origin

Če do API-ja dostopate z meddomensko zahtevo AJAX (CORS), to nastavite na domeno izvora. To mora biti vključeno v vsak predpoletni zahtevek, zato mora biti del URL-ja zahtevka (in ne telesa POST).

Pri avtenticiranih zahtevkih se mora to natančno ujemati z enim od izvorov v glavi Origin, zato je to treba nastaviti na nekaj takega kot https://en.wikipedia.org ali https://meta.wikimedia.org. Če se ta parameter ne ujema z glavo Origin, bo vrnjen odgovor 403. Če se ta parameter ujema z glavo Origin in je izvor dovoljen, bosta nastavljeni glavi Access-Control-Allow-Origin in Access-Control-Allow-Credentials.

Za neavtenticirane zahtevke določite vrednost *. To bo povzročilo, da bo nastavljena glava Access-Control-Allow-Origin, vendar bo Access-Control-Allow-Credentials false in bodo vsi podatki, specifični za uporabnika, omejeni.

crossorigin

Pri dostopu do API-ja z uporabo meddomenske zahteve AJAX (CORS) in ponudnika seje, ki je varen pred napadi s ponarejanjem spletnih zahtev (CSRF) (kot je OAuth), uporabite to namesto origin=*, da bo zahtevek overjen (tj. ne odjavljen). To mora biti vključeno v kateri koli zahtevek pred pošiljanjem in mora biti zato del URL-ja zahtevka (ne telesa POST).

Upoštevajte, da večina ponudnikov sej, vključno s standardnimi sejami, ki temeljijo na piškotkih, ne podpira overjenih CORS in jih ni mogoče uporabiti s tem parametrom.

Tip: Boolov (podrobnosti)
uselang

Jezik, ki se uporablja za prevajanje sporočil. action=query&meta=siteinfo&siprop=languages vrne seznam jezikovnih oznak ali določi user za uporabo jezikovne preference trenutnega uporabnika ali določi content za uporabo jezika vsebine tega vikija.

Privzeto: user
variant

Različica jezika. Deluje le, če osnovni jezik podpira pretvorbo variant.

errorformat

Oblika, ki se uporablja za izpis besedila o opozorilih in napakah

plaintext
Vikibesedilo z odstranjenimi značkami HTML in zamenjanimi entitetami.
wikitext
Nerazčlenjeno vikibesedilo.
html
HTML
raw
Ključ in parametri sporočila.
none
Ni besedila, samo kode napak.
bc
Format, uporabljen pred MediaWiki 1.29., errorlang in errorsuselocal so prezrti.
Ena od naslednjih vrednosti: bc, html, none, plaintext, raw, wikitext
Privzeto: bc
errorlang

Jezik, ki se uporablja za opozorila in napake. action=query&meta=siteinfo&siprop=languages vrne seznam jezikovnih oznak. Določite content za uporabo jezika vsebine tega vikija ali uselang za uporabo iste vrednosti kot parameter uselang (preferenčni jezik uporabnika).

Privzeto: uselang
errorsuselocal

Če je podano, bodo besedila o napakah uporabljala lokalno prilagojena sporočila iz imenskega prostora MediaWiki.

Tip: Boolov (podrobnosti)

Zasluge

Razvijalci API-ja:

  • Jurij Astrahan (ustvarjalec, glavni razvijalec: september 2006–september 2007)
  • Roan Kattouw (glavni razvijalec: september 2007–2009)
  • Victor Vasiliev
  • Bryan Tong Minh
  • Sam Reed
  • Brad Jorsch (glavni razvijalec: 2013–2020)

Prosimo, da svoje komentarje, predloge in vprašanja pošljete na mediawiki-api@lists.wikimedia.org ali oddate poročilo o napaki na https://phabricator.wikimedia.org/.