API:回退

From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page API:Rollback and the translation is 66% complete.
Other languages:
Deutsch • ‎Deutsch (Sie-Form)‎ • ‎English • ‎Türkçe • ‎dansk • ‎español • ‎français • ‎polski • ‎русский • ‎سنڌي • ‎中文 • ‎日本語
MediaWiki版本: 1.12

POST request to revert the last series of edits made by one user to a given page.

此功能与历史界面中提供的rollback链接效果是一样的。

API文档


action=rollback

(main | rollback)
  • This module requires read rights.
  • This module requires write rights.
  • This module only accepts POST requests.
  • Source: MediaWiki
  • License: GPL-2.0-or-later

Undo the last edit to the page.

If the last user who edited the page made multiple edits in a row, they will all be rolled back.

Parameters:
title

Title of the page to roll back. Cannot be used together with pageid.

pageid

Page ID of the page to roll back. Cannot be used together with title.

Type: integer
tags

Tags to apply to the rollback.

Values (separate with | or alternative): possible vandalism, repeating characters
user

Name of the user whose edits are to be rolled back.

This parameter is required.
Type: user, by any of user name, IP, interwiki name (e.g. "prefix>ExampleName") and user ID (e.g. "#12345")
summary

Custom edit summary. If empty, default summary will be used.

Default: (empty)
markbot

Mark the reverted edits and the revert as bot edits.

Type: boolean (details)
watchlist

Unconditionally add or remove the page from the current user's watchlist, use preferences or do not change watch.

One of the following values: nochange, preferences, unwatch, watch
Default: preferences
token

A "rollback" token retrieved from action=query&meta=tokens

For compatibility, the token used in the web UI is also accepted.

This parameter is required.
Examples:
Roll back the last edits to page Main Page by user Example.
api.php?action=rollback&title=Main%20Page&user=Example&token=123ABC [open in sandbox]
Roll back the last edits to page Main Page by IP user 192.0.2.5 with summary Reverting vandalism, and mark those edits and the revert as bot edits.
api.php?action=rollback&title=Main%20Page&user=192.0.2.5&token=123ABC&summary=Reverting%20vandalism&markbot=1 [open in sandbox]

例子

发出任何POST请求都是一个多步骤的过程:

  1. 使用API:登录 中描述的方法之一登录。
  2. 获取CSRF令牌
  3. Send a POST request, with the CSRF token, to take action on a page and in this process gain editpage rights to the given page:
  4. GET a rollback token:

POST请求

Send a POST request, with a rollback token to revert a user's edits to the Sandbox page.

在本例中,所有的参数通过GET请求传递只是为了便于理解。实际上, action=rollback 需要以POST方式请求,以GET方式请求将报错。

回应

The Response section below is for the final POST request, to revert the edits to the Sandbox page.

{
    "rollback": {
        "title": "Sandbox",
        "pageid": 94542,
        "summary": "Reverted edits by [[Special:Contributions/41.190.3.231|41.190.3.231]] ([[User talk:41.190.3.231|talk]]) to last revision by [[User:Didicodes|Didicodes]]",
        "revid": 381084,
        "old_revid": 381083,
        "last_revid": 381070
    }
}

回应中的修订ID为:

  • revid - 回退创建的新修订版的ID。
  • old_revid - 正在回退的最新修订版的ID。回退之前,这是当前版本。
  • last_revid - 回退恢复的修订版本的ID。这是已回退的最新修订版本。

示例代码

Python

#!/usr/bin/python3

"""
    rollback.py

    MediaWiki API Demos
    Demo of `rollback` module: Sending post request to rollback the
    last edits made to a given page.

    MIT license
"""
import requests

S = requests.Session()

URL = "https://test.wikipedia.org/w/api.php"

# Step 1: Retrieve a login token
PARAMS_1 = {
    "action": "query",
    "meta": "tokens",
    "type": "login",
    "format": "json"
}

R = S.get(url=URL, params=PARAMS_1)
DATA = R.json()

LOGIN_TOKEN = DATA['query']['tokens']['logintoken']

# Step 2: Send a post request to login. 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_2 = {
    "action": "login",
    "lgname": "bot_user_name",
    "lgpassword": "bot_password",
    "lgtoken": LOGIN_TOKEN,
    "format": "json"
}

R = S.post(URL, data=PARAMS_2)

# Step 3: While logged in, retrieve a CSRF token
PARAMS_3 = {
    "action": "query",
    "meta": "tokens",
    "format": "json"
}

R = S.get(url=URL, params=PARAMS_3)
DATA = R.json()

CSRF_TOKEN = DATA["query"]["tokens"]["csrftoken"]

# Step 4: POST request to edit a page
PARAMS_4 = {
    "action": "edit",
    "title": "Sandbox",
    "token": CSRF_TOKEN,
    "format": "json",
    "appendtext": "Hello"
}

R = S.post(URL, data=PARAMS_4)

# Step 5: Retrieve a rollback token
PARAMS_5 = {
    "action": "query",
    "meta": "tokens",
    "type": "rollback",
    "format": "json"
}

R = S.get(url=URL, params=PARAMS_5)
DATA = R.json()

ROLLBACK_TOKEN = DATA['query']['tokens']['rollbacktoken']

# Step 5: POST request to rollback a page
PARAMS_6 = {
    "action": "rollback",
    "format": "json",
    "title": "Sandbox",
    "user": "bot_user_name",
    "token": ROLLBACK_TOKEN,
}

R = S.post(URL, data=PARAMS_6)
DATA = R.json()

print(DATA)

PHP

<?php

/*
    rollback.php

    MediaWiki API Demos
    Demo of `rollback` module: Sending post request to rollback the
    edits of a given page.
    MIT license
*/

$endPoint = "http://dev.wiki.local.wmftest.net:8080/w/api.php";

$login_Token = getLoginToken(); // Step 1
loginRequest( $login_Token ); // Step 2
$rollback_Token = getRollbackToken(); // Step 3
rollback( $rollback_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 rollback token
function getRollbackToken() {
	global $endPoint;

	$params3 = [
		"action" => "query",
		"meta" => "tokens",
		"type" => "rollback",
		"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"]["rollbacktoken"];
}

// Step 4: POST request to rollback a page
function rollback( $rollback_Token ) {
	global $endPoint;

	$params4 = [
		"action" => "rollback",
		"title" => "Sandbox",
		"user" => "10.0.2.2",
		"token" => $rollback_Token,
		"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

/*  
    rollback.js
 
    MediaWiki API Demos
    Demo of `rollback` module: Sending post request to rollback the
    edits of a given page.

    MIT license
*/

var request = require('request').defaults({jar: true}),
    url = "http://dev.wiki.local.wmftest.net:8080/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;
        }
        getRollbackToken();
    });
}

// Step 3: GET request to fetch Rollback token
function getRollbackToken() {
    var params_2 = {
        action: "query",
        meta: "tokens",
        type: "rollback",
        format: "json"
    };

    request.get({ url: url, qs: params_2 }, function(error, res, body) {
        if (error) {
            return;
        }
        var data = JSON.parse(body);
        rollback(data.query.tokens.rollbacktoken);
    });
}

// Step 4: POST request to rollback a page
function rollback(rollback_token) {
    var params_3 = {
        action: "rollback",
        title: "Sandbox",
        user: "10.0.2.2",
        token: rollback_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

/*
	rollback.js

	MediaWiki API Demos
	Demo of `rollback` module: Sending post request to rollback the
    last edits made to a given page.

	MIT License
*/

var params = {
		action: 'rollback',
		title: 'Sandbox',
		user: '10.0.2.2',
		format: 'json'
	},
	api = new mw.Api();

api.postWithToken( 'rollback', params ).done( function ( data ) {
	console.log( data );
} );

权限

Rollback requires both the editpage and the rollback right on the target page; currently, this means that OAuth consumers, bot passwords etc. require both the editpage and the rollback grant – rollback alone is not enough!

可能的错误

In addition to the usual stuff:

代码 信息
alreadyrolled 您尝试回退的页面已近被回退
missingparams One of the parameters "title" and "pageid" is required.
mustpostparams The rollback module requires a POST request.
notitle title参数必须被设置。
notoken token参数必须被设置。
nouser user参数必须被设置。
onlyauthor 您尝试回退的页面只有一个编辑者
permissiondenied The action you have requested is limited to users in one of the groups: Administrators, Rollbackers

参数历史

  • v1.24: 启用pageid
  • v1.27: 启用tags
  • v1.17: 启用watchlist

补充资料

  • 可选的是,回退与与被回退的编辑均可被标记为机器人操作,可在最近更改中默认不显示。

参见