API:Login/zh

The MediaWiki API may require your application or client to provide authenticated user credentials to the API in order to complete an operation successfully. The standard way to become authenticated involves performing a login action request, constructing a cookie, and confirming the login by resubmitting the login action request with the confirmation token returned.

是否要登录
在以下情况下您的客户程序需要登录以进行操作：


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

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

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

应用程序专有的用户帐号
Rather than having your application log in as yourself, you may want to create a separate user account just for your application. This is especially important if your application:


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

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

Login gets several tokens that are needed by the server to recognize the logged-in user. In every call to api.php, the cookie set by this request must be passed. The cookies last for around a month and you should check that you need to log in based on detecting that you're not logged in (rather than logging once per session, for example). You can check this on any request using the  generic parameter.

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

登录请求的结构
POST的包体可以为空. 这个请求也会在HTTP头中包含一个Session Cookie（ ），您必须在第二次请求中返回这个Cookie如果你使用的框架没有自动进行这种操作. sessionid参数在MediaWiki 1.17及之后的版本中被加入.

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

确认令牌
如果请求的结果是  而不是  ,你可以跳过这个步骤. (这个额外的步骤添加自 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 while you plan your upgrade to 1.15.5. 来自MediaWiki 1.16版本以上的ApiLogin.php并不能兼容MediaWiki 1.15.3至1.16的版本.

构建cookies
A successful  request will set cookies needed to be considered logged in. 很多框架会自动处理Cookie（例如cURL中的cookiekar） 如果是这样的，那就直接享受框架所带来的便利. If not, the most reliable method is to parse them from the HTTP response's Set-Cookie headers.

If this is not possible either, it is possible to construct the appropriate cookies from the various values returned by the  call, but this is not recommended as the necessary cookies may be changed without warning (e.g. something as simple as changing  would require changes to your manual cookie creation code).

When CentralAuth is enabled, as on Wikimedia wikis, the example above will not only log you in to a single domain, but also provide you with three centralauth cookies in the Set-Cookie response headers. To use these, duplicate those cookies (i.e. cookies whose names are prefixed with "centralauth_") and set the domain field of the new cookies to the new domain you'd like to log in at. Once this is done, any GET/POST request to this new domain will (assuming that the user has a SUL/global account) be answered with a reply containing Set-Cookie headers/Cookies specific to that domain.

错误
错误会呈现在result域中. 可能的取值有:

流量控制
出于安全考虑，这个模块有流量限制. 默认情况下，300秒内最多登录5次. 但是每个维基可以有不同的设置. 当超过这个限制值时，你的登录会失败. 返回的 值是 ，返回的 值是：你需要等待的秒数.

例子

 * 用户登录PHP示例代码：
 * 登录的例子 (要求Snoopy)
 * 登录与导航示例 （仅使用file_get_contents函数）
 * 用PHP登录的例子(使用cURL) - 不需要Snoopy
 * Example login code in JS (using JQuery)
 * 用户登录Python示例代码