API:Edit/zh

From MediaWiki.org
Jump to navigation Jump to search
其他语言:Project:Language policy English  • Deutsch • español • français • 日本語 • русский • Tiếng Việt • 中文
MediaWiki版本: 1.13

需要以下MediaWiki选项设置为 true: $wgEnableAPI$wgEnableWriteAPI。見Manual:DefaultSettings.php。该模块由ApiEditPage.php实现。

编辑令牌[edit]

要有编辑令牌才可以编辑页面。这个令牌在所有页面中都一样,但是每次登录都会不同;它也会过期。获取编辑令牌的首选方法取决于MediaWiki版本:

目前所有较旧的方法都可使用,但不推荐。

如果你想防止编辑冲突(这是明智的),你也需要得到最近版本的时间戳。你可以通过下面的例子获得编辑令牌:

获取编辑令牌

当使用Edit API时,请将token参数传递于最后(或者最起码地,传递于text参数的后面)。这样,如果编辑被中断,令牌将不会被传递,编辑将失败。这是由mw.Api自动完成的。

未注册用户[edit]

对于未注册的用户,该令牌总是存在+\,但如果将来发生更改,您可能需要明确请求该令牌。

创建或编辑页面[edit]

edit动作(action=edit)用于创建或编辑页面。

参数[edit]

  • title: 要编辑的页面。不能和pageid连用。备注:如果$wgCapitalLinks为false, Article和article将不会被视为相同的页面,例如在Wiktionary中。
  • pageid: 要编辑页面的ID。不能和title连用。 1.20+
  • section
  • sectiontitle: 创建新章节的标题。如果为空,summary将会替代。 1.19+
  • text: 新页面(或者话题)的内容。
  • summary
  • tags: 要应用于此编辑的标签,它们必须已在Special:Tags中手动定义,并且用户必须能够应用它们(默认情况下,所有注册用户都可以)。 1.25+
  • minor: 如果设置,标记为小编辑。
  • notminor: 如果设置,即使您启用了“默认标记所有编辑为小编辑”,也不标记为小编辑。
  • bot: 如果设置,将编辑标记为机器人的编辑; 即使您作为机器人登陆,也必须设置本项才能将编辑标记为机器人编辑。
  • basetimestamp: 基本编辑的时间戳(通过prop=revisions&rvprop=timestamp获得)。用于检测编辑冲突,不设置将会忽视冲突。备注:如果您与当前用户发生冲突,编辑冲突将被忽略。
  • starttimestamp: 开始编辑页面时的时间戳(例如,当您获取当前修订版本的文本以开始编辑或检查页面是否存在时)。用于检测自您开始编辑以来页面是否已被删除,不设置将会忽视冲突。 1.14+
  • recreate: 忽略有关文章在此期间被删除的任何错误。
  • createonly: 如果存在该页面则不修改。
  • nocreate: 如果该页面不存在则抛出一个错误。
  • watch: 在监视列表添加此页。不建议使用。请使用watchlist参数 (在1.16版本弃用)
  • unwatch: 从监视列表移除此页。不建议使用。请使用watchlist参数 (在1.16版本弃用)
  • watchlist: 指定监视列表如何受此编辑影响。设置为watch,unwatch,preferences或nochange: (默认: preferences) 1.16+
    • watch: 在监视列表添加此页。
    • unwatch: 从监视列表移除此页。
    • preferences: 使用缺省设置。
    • nochange: 不要改变监视列表。
  • md5: text参数或连接后的prependtextappendtext参数的MD5散列值(十六进制)。如果设置了此参数且散列值不匹配,则编辑将被拒绝。这可以用来防范数据损坏。
  • prependtext: 将这个文本添加到页面开头。覆盖text。
  • appendtext
  • undo: 要撤销的编辑ID。覆盖textprependtextappendtext1.15+
  • undoafter: 撤销所有在undo及其之后的编辑,但不撤销这一次。如果不设置则只会撤销一个编辑。 1.15+
  • redirect: 自动分解重定向。 1.17+
  • contentformat: 用于输入文本的内容序列化格式。 可能的值: text/x-wiki(维基文本),text/javascript(javascript),text/css(css),text/plain(纯文本),application/json(json). 1.21+
  • contentmodel: 新内容的内容模型。 可能的值: wikitextjavascriptcsstextjson。此列表可能包含通过扩展注册的附加值;在Wikimedia维基上,还包含JsonZeroConfigScribuntoJsonSchema. 1.21+
  • token: 编辑令牌。它应该作为最后一个参数传递,或至少在text参数后发送,以防止由于某种原因而导致正文传输中断时发生错误的编辑,特别是在不使用md5参数的情况下。
  • captchaid: 上一个请求的验证码ID。尽管它在1.18版本的Edit API被移除,但编辑确认扩展(如Extension:ConfirmEdit)仍然可以将其自己的参数添加到Edit API。在Wikimedia维基上,它们仍然是captchaidcaptchaword,但不同的扩展使用不同的参数。 (在1.18版本移除)
  • captchaword: 验证码的答案。 (在1.18版本移除)


例子[edit]

备注: 在这个例子中,只是为了简单起见,所有参数都在GET请求中传递。然而,action = edit需要POST请求;GET请求将会产生一个错误。不要忘记设置Content-Type请求头为application/x-www-form-urlencoded。您收到的令牌将以+\结尾,这需要在传递之前进行URL编码(以让令牌以%2B%5C结尾)。

en:Talk:Main Page创建一个新章节

验证码和拓展错误[edit]

如果一次编辑请求需要验证码,你将会得到类似下面的:

<?xml version="1.0" encoding="utf-8"?>
<api>
  <edit result="Failure">
    <captcha type="math" mime="text/tex" id="509895952" question="36 + 4 = " />
  </edit>
</api>

具体的返回信息将由使用的验证码决定。在很多情况下,你不会得到一个数学验证码,而是一个指向一幅图片的连接(在url区域)。当你解决了验证码,重试发送该请求(在这个例子中应带着captchaid=509895952&captchaword=40)。

其他使用了APIEditBeforeSave的扩展可能会使用上述格式或通常的错误格式返回失败结果。

可能的错误[edit]

通常错误外:

Code Info
notitle Template:Int/zh
notext One of the text, appendtext, prependtext and undo parameters must be set
notoken token参数必须被设置。
invalidsection The section parameter must be set to an integer or 'new'
protectedtitle This title has been protected from creation
cantcreate You don't have permission to create new pages
cantcreate-anon Anonymous users can't create new pages
articleexists 您尝试创建的条目已刚刚被创建。
noimageredirect-anon 匿名用户不能创建图片重定向。
noimageredirect 您没有权限创建图片重定向。
spamdetected Your edit was refused because it contained a spam fragment: "wikitext"
filtered The filter callback function refused your edit
contenttoobig The content you supplied exceeds the article size limit of bytes bytes
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 Edit conflict detected
revwrongpage revid is not a revision of "pagename"
Thrown if an invalid revid is given for undo or undoafter
undofailure Undo failed due to conflicting intermediate edits
missingtitle (see above nocreate parameter)
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. Make sure the $wgEnableWriteAPI=true; statement is included in the wiki's LocalSettings.php file
badtoken Invalid token
missingparam One of the parameters title, pageid is required
invalidparammix The parameters title, pageid can not be used together
invalidtitle Bad title "title"
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
undofailure Undo failed due to conflicting intermediate edits
badmd5 The supplied MD5 hash was incorrect
hookaborted The modification you tried to make was aborted by an extension hook
parseerror Failed to parse the given text.
summaryrequired Summary required
blocked You have been blocked from editing
ratelimited You've exceeded your rate limit. Please wait some time and try again
unknownerror Unknown error: "retval"
nosuchsection There is no such section.
sectionsnotsupported Sections are not supported for this type of page.
editnotsupported Editing of this type of page is not supported using the text based edit API.
appendnotsupported This type of page can not be edited by appending or prepending text.
redirect-appendonly You have attempted to edit using the "redirect"-following mode, which must be used in conjuction with section=new, prependtext, or appendtext.
badformat The requested serialization format can not be applied to the page's content model
customcssprotected You're not allowed to edit custom CSS pages
customjsprotected You're not allowed to edit custom JavaScript pages
taggingnotallowed You don't have permission to set change tags

使用Ajax编辑[edit]

Below is sample code for editing a page via an Ajax request:

function addNewSection( summary, content, editToken ) {
    $.ajax({
        url: mw.util.wikiScript( 'api' ),
        data: {
            format: 'json',
            action: 'edit',
            title: mw.config.get( 'wgPageName' ),
            section: 'new',
            summary: summary,
            text: content,
            token: editToken
        },
        dataType: 'json',
        type: 'POST',
        success: function( data ) {
            if ( data && data.edit && data.edit.result == 'Success' ) {
                window.location.reload(); // reload page if edit was successful
            } else if ( data && data.error ) {
                alert( 'Error: API returned error code "' + data.error.code + '": ' + data.error.info );
            } else {
                alert( 'Error: Unknown result from API.' );
            }
        },
        error: function( xhr ) {
            alert( 'Error: Request failed.' );
        }
    });
}

大文本[edit]

当文本超过 8000 字时,使用 "multipart/form-data" as it does not require escaping and will be significantly smaller than its urlencoded counterpart。Multipart has roughly 160 bytes of overhead for each 参数,so for seven 参数 that's ~1.1kb overhead。 例子:

POST http://en.wikipedia.org/w/api.php HTTP/1.1
User-Agent: Bot Framework
Content-Type: multipart/form-data; boundary=---------------------------8ce61ec834cf268
Host: en.wikipedia.org
Cookie: <removed>
Content-Length: 1348
Accept-Encoding: gzip
Connection: Keep-Alive


-----------------------------8ce61ec834cf268
Content-Disposition: form-data; name="action"

edit
-----------------------------8ce61ec834cf268
Content-Disposition: form-data; name="title"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Title here
-----------------------------8ce61ec834cf268
Content-Disposition: form-data; name="text"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Text here
-----------------------------8ce61ec834cf268
Content-Disposition: form-data; name="summary"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Summary
-----------------------------8ce61ec834cf268
Content-Disposition: form-data; name="token"

1f287ba00a908e9622045e7b18ffa352+\
-----------------------------8ce61ec834cf268
Content-Disposition: form-data; name="assert"

user
-----------------------------8ce61ec834cf268
Content-Disposition: form-data; name="format"

xml
-----------------------------8ce61ec834cf268--