API:Login/zh

该页面是 MediaWiki API 文档的一部份

MediaWiki API

• 快速参考手册
• 常见问题解答
• 格式
• 错误报告
• 使用限制
• 身份认证
  • 登陆
  • 退出
• 查询
  • Meta信息
  • 属性
  • 列表
• 模版扩展与渲染
• 清空页面缓存
• 参数信息
• 编辑
  • 添加/编辑页面
  • 移动
  • 撤消修改
  • 删除
  • 恢复删除
  • 保护页面
  • 封禁用户
  • 关注页面
  • 发送电子邮件
  • 监视改动
  • 导入页面
  • 为用户分组
  • 上传文件
• 扩展现有API
• 内部调用
• 其他
• 代码组织
• 客户端代码

在使用MediaWiki的web服务API时，您可能需要让您的应用程序或客户端程序登录。这个过程由提交登录请求，构建一个cookie，再通过与返回的确认token一起重新提交登录请求来完成。

是否要登录

如果：

• 它需要获取某些信息或执行一项操作，而这种操作仅限一些有特定权限的用户执行；
• 它需要执行大的请求，这样的请求受到限制而变得低效，而为了消除限制就需要作为有特定权限的用户登录

那么，您的客户程序需要登录MediaWiki。

在允许匿名编辑的wiki上，不登录就通过API编辑是可能的，但我们强烈推荐您在编辑前登录。在非开放wiki上，使用任何API功能都需要登录。

如果您的客户端程序是用JavaScript编写的，它通常会作为运行它的用户的登录凭据执行操作。这种情况下，您就不需要通过web服务API登录了：您只需要保证用户已经通过web界面登录了。

应用程序专有的用户帐号

您可能希望为您的应用程序创建专有的用户帐号，而不是让您的应用程序以您自己的身份登录。如果您的应用程序：

• 执行自动编辑或其他大量操作；
• 执行大的或性能昂贵的请求

那么这非常重要。

如果您的应用程序拥有一个单独的帐号，那么它作出的修改就很容易被追踪，并且它的帐号可以被赋予特殊的权限（通常是"bot"用户组）。有些wiki有关于自动编辑的方针，和/或一个处理"bot"用户组的请求的过程。

登录之后，您会获得一些token。服务器依赖它们来识别已登录的用户。您必须在每一个对api.php的调用中传递由登录请求所设置的cookie。这些cookie可以保留约一个月。您应该通过检查您当前是否已登录来决定是否需要登录（而不是，例如，在每次会话中都登录一次）。

如何登录

如果您要通过API登录，您需要提交登录请求并构建一个cookie（许多应用程序框架会自动构建这个cookie）。在MediaWiki 1.15.3+中，您必须通过与返回的token一起再次提交登录请求来确认登录。

登录请求的结构

用POST方法提交请求（GET方法会导致错误）。

api.php ? action=login & lgname=Bob & lgpassword=secret

<?xml version="1.0" encoding="utf-8"?>
<api>
  <login
    result="NeedToken"
    token="b5780b6e2f27e20b450921d9461010b4"
    cookieprefix="enwiki"
    sessionid="17ab96bd8ffbe8ca58a78657a918558e"
  />
</api>

这个请求还会在HTTP头中返回一个会话cookie（Set-Cookie: enwiki_session=17ab96bd8ffbe8ca58a78657a918558e; path=/; domain=.wikipedia.com; HttpOnly）。您需要在接下来的请求中加入这个cookie（许多应用程序框架会自动处理cookie）。sessionid参数是在MediaWiki 1.17及之后的版本中加入的。注意如果MediaWiki返回的不是XML而是HTML，那么您需要提供一个format=xml参数。

如果您使用认证插件如Extension:LDAP Authentication，您可能需要加入请求参数lgdomain，包含您认证的域名。

Confirm token

If the response to the above query was Success instead of NeedToken, you can skip this step. (This extra step was added in MediaWiki 1.15.3.) In MediaWiki 1.15.4, first phase of login in ApiLogin.php is broken, so login/sessionid parameter is not returned, thus token confirmation is impossible. Apply ApiLogin.php file from MediaWiki 1.15.5 to your installation as a quick workaround, even better to upgrade to 1.15.5. ApiLogin.php from MediaWiki 1.16+ is incompatible with MediaWiki 1.15.3+.

Send a login request with POST, with confirmation token in body and the session cookie (e.g. enwiki_session) in header as returned from previous request.

api.php ? action=login & lgname=Bob & lgpassword=secret & lgtoken=b5780b6e2f27e20b450921d9461010b4

<?xml version="1.0" encoding="utf-8"?>
<api>
  <login
    result="Success"
    lguserid="12345"
    lgusername="Bob"
    lgtoken="4db760e273b413549a32ba4eb06d08db"
    cookieprefix="enwiki"
    sessionid="17ab96bd8ffbe8ca58a78657a918558e"
  />
</api>

Construct cookies

A successful action=login request will set session cookies. Many frameworks will handle these cookies automatically (such as the cookiejar in cURL); if not, you will have to create them yourself.

If your wiki is not using the CentralAuth extension, you can construct them from the data returned as follows:

In the example above, you'd set the following cookie from the first request and send it for the second request:

• enwiki_session = 17ab96bd8ffbe8ca58a78657a918558e (from the HTTP cookie enwiki_session)

Additionally, you have to set after logged in sucessfully:

• enwikiUserName = Bob (from the lgusername field)
• enwikiUserID = 12345 (from the lguserid field)
• enwikiToken = 4db760e273b413549a32ba4eb06d08db (from the lgtoken field)

Note that the enwiki part is different for every wiki, and is returned in the cookieprefix field.

When CentralAuth is enabled, as on Wikimedia wikis, the above method will only work on a single wiki. If you would like to use the advantages of Single-User-Login to be logged in on all wikis, the only usable option is to also parse the Set-Cookie: headers manually and create additional cookies, instead of just accepting the cookies that it sets (which only sets them for the single wiki)

CentralAuth SUL Login

• Login in as usual.
• From the headers (especially from the second reponse) accept the cookies that it wants to set (typically there are 6 cookies being set. For example on Wikimedia Commons: commonswiki_session, centralauth_User, centralauth_Token, centralauth_Session, commonswikiUserID and commonswikiUserName). This part is usually covered by frameworks such as cURL with a cookiejar.
• Now you have to parse the cookie by looking for the centralauth_ cookies and adding additional entries for all other wikis that centralauth covers in your setup.
  In the case of Wikimedia the cookie should be duplicated and added for following domains:
  • .wikipedia.org
  • .meta.wikimedia.org
  • .wiktionary.org
  • .wikibooks.org
  • .wikiquote.org
  • .wikisource.org
  • .commons.wikimedia.org
  • .wikinews.org
  • .wikiversity.org
  • .mediawiki.org
  • .species.wikimedia.org

Errors

Errors are returned in the result field. Possible values are:

• NoName
  • You didn't set the lgname parameter
• Illegal
  • You provided an illegal username
• NotExists
  • The username you provided doesn't exist
• EmptyPass
  • You didn't set the lgpassword parameter or you left it empty
• WrongPass
  • The password you provided is incorrect
• WrongPluginPass
  • Same as WrongPass, returned when an authentication plugin rather than MediaWiki itself rejected the password
• CreateBlocked
  • The wiki tried to automatically create a new account for you, but your IP address has been blocked from account creation
• Throttled
  • You've logged in too many times in a short time. See also throttling
• Blocked
  • User is blocked
• mustbeposted
  • The login module requires a POST request
• NeedToken
  • Either you did not provide the login token or the sessionid cookie. Request again with the token and cookie given in this response

Throttling

For security reasons, this module is throttled. By default, you get to login 5 times in 300 seconds, but this may vary from one wiki to another. When you exceed this limit, your login will fail (even if it's otherwise correct) with result="Throttled" and the number of seconds you need to wait in the wait field.

Examples

• Example login code in PHP (requires Snoopy)
• Example login code in PHP (using cURL) - no Snoopy required