API:Úpravy
| Tato stránka je součástí dokumentace k API Action MediaWiki. |
| Verze MediaWiki: | ≥ 1.13 |
Požadavek POST pro úpravu stránky.
Dokumentace API
Příklad
Ukázkový kód v tomto příkladu je v Pythonu. Viz API:Edit/Editing with Ajax pro příklady a odpovědi v Ajax.
Požadavek POST
Provádění úprav a vlastně i jakýkoli požadavek POST je vícestupňový proces.
- 1. Přihlaste se jedním ze způsobů popsaných v API:Přihlášení. Všimněte si, že ačkoli je to nutné pro správné přiřazení úpravy jejímu autorovi, mnoho wikin umožňuje uživatelům úpravy bez registrace nebo přihlášení k účtu.
- 2. GET CSRF token:
- 3. Odešlete požadavek POST s tokenem CSRF, abyste provedli akci na stránce:
Sekce Response (odpověď) níže je pro poslední požadavek POST, aby se na stránce provedla akce. Zprostředkující odpovědi JSON na předchozí kroky naleznete na stránkách API:Přihlášení a API: Tokeny.
Všimněte si také, že tokeny v dotazech na této stránce jsou vzorové hodnoty. Skutečné tokeny jsou jedinečné pro každou relaci přihlášení a požadavek mezi weby. Jsou zahrnuty pouze jako ukázka, jak správně formátovat dotazy.
Odpověď
{
"edit": {
"result": "Success",
"pageid": 94542,
"title": "Wikipedia:Sandbox",
"contentmodel": "wikitext",
"oldrevid": 371705,
"newrevid": 371707,
"newtimestamp": "2018-12-18T16:59:42Z"
}
}
Ukázkový kód
Python
#!/usr/bin/python3
"""
edit.py
MediaWiki API Demos
Demo of `Edit` module: POST request to edit a page
MIT license
"""
import requests
S = requests.Session()
URL = "https://test.wikipedia.org/w/api.php"
# Step 1: GET request to fetch login token
PARAMS_0 = {
"action": "query",
"meta": "tokens",
"type": "login",
"format": "json"
}
R = S.get(url=URL, params=PARAMS_0)
DATA = R.json()
LOGIN_TOKEN = DATA['query']['tokens']['logintoken']
# Step 2: POST request to log in. Use of main account for login is not
# supported. Obtain credentials via Special:BotPasswords
# (https://www.mediawiki.org/wiki/Special:BotPasswords) for lgname & lgpassword
PARAMS_1 = {
"action": "login",
"lgname": "bot_user_name",
"lgpassword": "bot_password",
"lgtoken": LOGIN_TOKEN,
"format": "json"
}
R = S.post(URL, data=PARAMS_1)
# Step 3: GET request to fetch CSRF token
PARAMS_2 = {
"action": "query",
"meta": "tokens",
"format": "json"
}
R = S.get(url=URL, params=PARAMS_2)
DATA = R.json()
CSRF_TOKEN = DATA['query']['tokens']['csrftoken']
# Step 4: POST request to edit a page
PARAMS_3 = {
"action": "edit",
"title": "Project:Sandbox",
"token": CSRF_TOKEN,
"format": "json",
"appendtext": "Hello"
}
R = S.post(URL, data=PARAMS_3)
DATA = R.json()
print(DATA)
PHP
<?php
/*
edit.php
MediaWiki API Demos
Demo of `Edit` module: POST request to edit a page
MIT license
*/
$endPoint = "https://test.wikipedia.org/w/api.php";
$login_Token = getLoginToken(); // Step 1
loginRequest( $login_Token ); // Step 2
$csrf_Token = getCSRFToken(); // Step 3
editRequest($csrf_Token); // Step 4
// Step 1: GET request to fetch login token
function getLoginToken() {
global $endPoint;
$params1 = [
"action" => "query",
"meta" => "tokens",
"type" => "login",
"format" => "json"
];
$url = $endPoint . "?" . http_build_query( $params1 );
$ch = curl_init( $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );
$output = curl_exec( $ch );
curl_close( $ch );
$result = json_decode( $output, true );
return $result["query"]["tokens"]["logintoken"];
}
// Step 2: POST request to log in. Use of main account for login is not
// supported. Obtain credentials via Special:BotPasswords
// (https://www.mediawiki.org/wiki/Special:BotPasswords) for lgname & lgpassword
function loginRequest( $logintoken ) {
global $endPoint;
$params2 = [
"action" => "login",
"lgname" => "bot_user_name",
"lgpassword" => "bot_password",
"lgtoken" => $logintoken,
"format" => "json"
];
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $endPoint );
curl_setopt( $ch, CURLOPT_POST, true );
curl_setopt( $ch, CURLOPT_POSTFIELDS, http_build_query( $params2 ) );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );
$output = curl_exec( $ch );
curl_close( $ch );
}
// Step 3: GET request to fetch CSRF token
function getCSRFToken() {
global $endPoint;
$params3 = [
"action" => "query",
"meta" => "tokens",
"format" => "json"
];
$url = $endPoint . "?" . http_build_query( $params3 );
$ch = curl_init( $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );
$output = curl_exec( $ch );
curl_close( $ch );
$result = json_decode( $output, true );
return $result["query"]["tokens"]["csrftoken"];
}
// Step 4: POST request to edit a page
function editRequest( $csrftoken ) {
global $endPoint;
$params4 = [
"action" => "edit",
"title" => "Project:Sandbox",
"appendtext" => "Hello",
"token" => $csrftoken,
"format" => "json"
];
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $endPoint );
curl_setopt( $ch, CURLOPT_POST, true );
curl_setopt( $ch, CURLOPT_POSTFIELDS, http_build_query( $params4 ) );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );
$output = curl_exec( $ch );
curl_close( $ch );
echo ( $output );
}
JavaScript
/*
edit.js
MediaWiki API Demos
Demo of `Edit` module: POST request to edit a page
MIT license
*/
var request = require('request').defaults({jar: true}),
url = "https://test.wikipedia.org/w/api.php";
// Step 1: GET request to fetch login token
function getLoginToken() {
var params_0 = {
action: "query",
meta: "tokens",
type: "login",
format: "json"
};
request.get({ url: url, qs: params_0 }, function (error, res, body) {
if (error) {
return;
}
var data = JSON.parse(body);
loginRequest(data.query.tokens.logintoken);
});
}
// Step 2: POST request to log in.
// Use of main account for login is not
// supported. Obtain credentials via Special:BotPasswords
// (https://www.mediawiki.org/wiki/Special:BotPasswords) for lgname & lgpassword
function loginRequest(login_token) {
var params_1 = {
action: "login",
lgname: "bot_username",
lgpassword: "bot_password",
lgtoken: login_token,
format: "json"
};
request.post({ url: url, form: params_1 }, function (error, res, body) {
if (error) {
return;
}
getCsrfToken();
});
}
// Step 3: GET request to fetch CSRF token
function getCsrfToken() {
var params_2 = {
action: "query",
meta: "tokens",
format: "json"
};
request.get({ url: url, qs: params_2 }, function(error, res, body) {
if (error) {
return;
}
var data = JSON.parse(body);
editRequest(data.query.tokens.csrftoken);
});
}
// Step 4: POST request to edit a page
function editRequest(csrf_token) {
var params_3 = {
action: "edit",
title: "Project:Sandbox",
appendtext: "test edit",
token: csrf_token,
format: "json"
};
request.post({ url: url, form: params_3 }, function (error, res, body) {
if (error) {
return;
}
console.log(body);
});
}
// Start From Step 1
getLoginToken();
MediaWiki JS
/*
edit.js
MediaWiki API Demos
Demo of `Edit` module: POST request to edit a page
MIT License
*/
var params = {
action: 'edit',
title: 'Project:Sandbox',
appendtext: 'Hello',
format: 'json'
},
api = new mw.Api();
api.postWithToken( 'csrf', params ).done( function ( data ) {
console.log( data );
} );
Uživatelské případy
Úprava konfliktů
Ukázka Pythonu je základní implementací požadavku na úpravu od registrovaného uživatele. Ve scénářích reálného světa je třeba dbát na to, aby nedocházelo ke konfliktům úprav. K tomu dochází, když se dva nebo více uživatelů pokouší upravit stejnou stránku současně.
Konfliktům lze předejít načtením posledního časového razítka revize, když požadujeme token CSRF.
Přidání prop=info|revisions k žádosti o token CSRF v kroku 3 nám umožní přístup k časovému razítku poslední revize.
Toto časové razítko bude použito jako basetimestamp, když požádáme o úpravu.
Potřebujeme také přesný čas, kdy s úpravou začínáme.
To lze získat také přidáním curtimestamp k požadavku CSRF.
Tato hodnota bude sloužit jako náš starttimestamp.
Nakonec ve skutečném požadavku na úpravu nastavte parametry basetimestamp a starttimestamp takto:
api.php?
Velké úpravy
Požadavky POST obsahující velké množství textového obsahu (8000+ znaků) by měly být odeslány s Content-Type: multipart/form-data uvedeným v záhlaví.
Protože multipart/form-data nemusí přidávat znaky HTML escape (tj. procento kódování) pro mezery a interpunkci, množství předávaných dat bude následně mnohem menší než ekvivalent v procentech.
Stále však existuje určitá režie přidaná multipart/form-data - zhruba 160 bajtů na parametr.
U krátkých zpráv, které nevyžadují přidávání mnoha escape znaků, může být toto množství režie neefektivní a preferuje se procentuální kódování.[1]
Všimněte si, že v našem ukázkovém kódu Pythonu je požadavek standardně zakódován procenty.
Technickou diskusi o požadavcích typu content a POST naleznete ve webových dokumentech MDN.
Podívejte se na dokumentaci požadavků Pythonu, kde najdete informace o tom, jak předat multipart/form-data pomocí syntaxe podobné našemu ukázkovému kódu Pythonu.
CAPTCHA
Pokud wiki, na kterou cílíte, používá CAPTCHA, váš požadavek může vrátit chybu obsahující číslo ID a jednoduchý test, jako je otázka, matematický problém nebo URL k obrázku.
Chcete-li dokončit úpravu, musíte dokončit test a poté znovu zkusit svůj požadavek s ID a správnými odpověďmi připojenými k původnímu řetězci dotazu, například: captchaid=sampleId&captchaword=answer
Jiné systémy a rozšíření CAPTCHA mohou pro podobné použití používat jiné parametry. Obecně používejte názvy polí pro ID a testovací otázky jako parametry ve vašem druhém požadavku.
Možné chyby
| Kód | Popis |
|---|---|
| notitle | The title parameter must be set. |
| missingparam | At least one of the parameters text, appendtext a undo is required. |
| notoken | The token parameter must be set. |
| invalidsection | The section parameter must be a valid section ID or new. |
| protectedpage | Tato stránka byla zamčena, aby se předešlo jejímu editování. |
| cantcreate | Nemáte povoleno zakládat nové stránky. |
| cantcreate-anon | Anonymní uživatelé nemohou vytvářet nové stránky |
| articleexists | The page you tried to create has been created already. |
| noimageredirect-anon | Anonymous users can't create image redirects. |
| noimageredirect | You don't have permission to create image redirects. |
| spamdetected | Your edit was refused because it contained a spam fragment: Wikitext.
|
| abusefilter-warning | Tato akce byla automaticky identifikována jako škodlivá. |
| abusefilter-disallowed | Tato akce byla automaticky identifikována jako škodlivá, a proto zakázána. |
| contenttoobig | The content you supplied exceeds the page size limit of bytes kibibytes. Where bytes is the value of $wgMaxArticleSize. |
| noedit-anon | Anonymous users can't edit pages. |
| noedit | You don't have permission to edit pages. |
| pagedeleted | The page has been deleted since you fetched its timestamp. |
| emptypage | Creating new, empty pages is not allowed. |
| emptynewsection | Creating empty new sections is not possible. |
| editconflict | Editační konflikt. |
| revwrongpage | rrevid is not a revision of pagename. Vyhozeno, pokud je zadán neplatný revid pro undo nebo undoafter
|
| undofailure | Editace nemohla být zrušena kvůli konfliktu mezilehlých editací. |
| missingtitle | The page you specified doesn't exist. (viz výše nocreate parametr)
|
| mustbeposted | The edit module requires a POST request. |
| readapidenied | You need read permission to use this module. |
| writeapidenied | You're not allowed to edit this wiki through the API. |
| noapiwrite | Editing of this wiki through the API is disabled. |
| badtoken | Invalid CSRF token. |
| missingparam | The title, pageid parameter must be set. |
| invalidparammix | The parameters title, pageid can not be used together. |
| invalidtitle | Bad title "title". |
| invalid-content-data | Obsažená data jsou chybná dochází při pokusu o úpravu stránky JSON s nevyhovujícími daty nebo při pokusu o úpravu stránky MassMessageListContent |
| nosuchpageid | There is no page with ID pageid. |
| pagecannotexist | Namespace doesn't allow actual pages. |
| nosuchrevid | There is no revision with ID undo. |
| nosuchrevid | There is no revision with ID undoafter. |
| badmd5 | The supplied MD5 hash was incorrect. |
| hookaborted | Požadovaná úprava byla zamítnuta některým rozšířením. |
| parseerror | Content serialization failed: parseerror |
| summaryrequired | ⧼apierror-summaryrequired⧽ |
| blocked | Byla vám zablokována možnost editace. |
| ratelimited | You've exceeded your rate limit. Please wait some time and try again. |
| unknownerror | Unknown error: "retval". |
| nosuchsection | There is no section $1. |
| sectionsnotsupported | Sections are not supported for content model $1. |
| editnotsupported | Úpravy tohoto typu stránky nejsou podporovány pomocí textového rozhraní API. |
| appendnotsupported | Can't append to pages using content model $1. |
| redirect-appendonly | You have attempted to edit using the redirect-following mode, which must be used in conjunction with section=new, prependtext, or appendtext. |
| edit-invalidredirect | Cannot edit $1 while following redirects, as target $2 is not valid. |
| badformat | The requested format $1 is not supported for content model $2 used by $3. |
| customcssprotected | Nemáte povoleno editovat tuto stránku s CSS, protože obsahuje osobní nastavení jiného uživatele. |
| customjsprotected | Nemáte povoleno editovat tuto stránku s JavaScriptem, protože obsahuje osobní nastavení jiného uživatele. |
| taggingnotallowed | K nastavení značek změn nemáte oprávnění |
| badtags | Značku „Tag“ není dovoleno ručně přidávat. Následující značky není dovoleno ručně přidávat: Tag1, Tag2 |
| tpt-target-page | Tuto stránku nelze ručně aktualizovat.
Tato stránka je překladem stránky $1 a překlad lze aktualizovat pomocí [$2 nástroje pro překlad]. |
Historie parametrů
- v1.35: Představeno
baserevid - v1.25: Představeno
tags - v1.21: Představeno
contentformat,contentmodel - v1.20: Představeno
pageid - v1.19: Představeno
sectiontitle - v1.18: Zastaralé
captchaid,captchaword - v1.17: Představeno
redirect - v1.16: Zastaralé
watch,unwatch - v1.16: Představeno
watchlist - v1.15: Představeno
undo,undoafter - v1.14: Představeno
starttimestamp
Další poznámky
- Přihlášení není API striktně vyžadováno, ale je nutné pro správné přiřazení úpravy jejímu autorovi. Úspěšná úprava od uživatele, který není přihlášen, bude připsána jeho IP adrese.
- Roboti, kteří nejsou přihlášeni, mohou čelit omezením úprav a dalších požadavků na zápis. Pro více podrobností se podívejte na stránku Příručka:Vytvoření robota#Přihlášení.
- Uživatelům, kteří nejsou přihlášeni, bude vždy přidělen prázdný token CSRF,
+\. - Proces vyžádání tokenu se v různých verzích několikrát změnil. Další informace viz API: Tokeny.
- ResourceLoader poskytuje způsob přístupu k tokenům úprav při spouštění kódu na wiki stránce.
- Můžete použít stejný token CSRF pro všechny operace úprav na stejné wiki během jediné relace přihlášení.
- Je dobrým zvykem předat jakékoli tokeny v požadavku na konec řetězce dotazu nebo alespoň za textový parametr. Tímto způsobem, pokud je připojení přerušeno, token nebude předán a úprava se nezdaří. Pokud k vytváření požadavků používáte objekt mw.Api, provádí se to automaticky.
- Ačkoli
captchaidacaptchawordbyly technicky odstraněny z API:Edit od verze 1.18, Rozšíření:ConfirmEdit rozšiřuje API:Edit o práci s CAPTCHA. S nainstalovaným ConfirmEdit jsou tedy tyto parametry stále dostupné. ConfirmEdit je dodáván se software MediaWiki, v1.18+.
Související odkazy
- Nápověda:Editace - obsahuje užitečné odkazy na úpravu článků.
- Manual:Bot passwords - popisuje, jak se přihlásit pomocí zjednodušeného rozhraní při přístupu na wikiny prostřednictvím skriptu nebo aplikace, nikoli GUI.
- Manual:Creating a bot - více podrobností o používání robota k automatické úpravě stránek.
- ResourceLoader - poskytuje způsob přístupu k tokenům úprav při spuštění JavaScriptu na stránce MediaWiki.
- API: Tokeny - obsahuje další podrobnosti o používání tokenů k přihlášení nebo vytváření požadavků POST.
- API:Tokens (action) - zastaralé API, odlišné od API: Tokeny, pro vyžádání tokenů v dřívějších verzích MediaWiki.
- API:Compare - umožňuje rozlišovat mezi úpravami na stránce.
- API:Managetags - mění značky na stránce.
- API:Vracení zpět - vrátí řadu úprav.
- API:Filerevert - vrátí soubory do dřívějšího stavu.
- API:Revisiondelete - odstraní a obnoví revize stránky.