API:Login/zh

這個MediaWiki API可能會請求应用程序或客户端程序提供经过身份验证的用户的凭据以用來讓API完成一個成功的操作. As of MediaWiki 1.27, there are two API actions used to authenticate:  and.

Bots and other non-interactive applications should generally use owner-only OAuth consumers when available to authenticate as it is more secure, however bot passwords can be used with the  action as described on this page.

Interactive applications such as custom editors or patrolling applications that provide a service without intending to fully replace the website should generally also use OAuth for authenticating the tool, as it is easier and more secure, however the  action can be used if that is unavailable.

Interactive applications such as mobile apps that aim to completely replace access to the web-based user interface should use the  action to authenticate.

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


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

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

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

If your client is using OAuth or a similar mechanism, it will not need to explicitly log in as all OAuth requests are already authenticated.

应用程序专有的用户帐号
相比让你的应用使用你的个人账户来登陆，你可能更希望去建立一个被分离出的单独的用户帐户让你的应用使用. 如果你的应用具有下述行为，那么这将是尤为重要的


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

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

How to check if you're logged in
The login mechanism typically uses cookies to track the logged-in status of a session. Clients should check directly if they are logged in, rather than attempting to determine the status by examining the cookies or by blindly logging in whether or not it is required.

The recommended way to ensure that requests are logged in is to use the assert=user parameter accepted on all API calls. When this parameter is provided and the user is not logged in, an assertuserfailed error will be returned.

To directly check which user (if any) you are currently logged in as, use the query module.

如何登录
In MediaWiki versions before 1.27, only the  action is available and should be used by all clients needing to login. As of 1.27, the  action should only be used in combination with bot passwords, and   should be used by interactive applications.

Note that logging in and remaining logged in requires correct HTTP cookie handling by your client on all requests. Typically your framework or HTTP request library will handle this for you.

The action
To successfully log in, a login token must first be retrieved. In MediaWiki 1.27 and later, this token should be fetched using a query with. For older versions, a POST to the  action is required instead.

Other fields might be included in the response, however these are deprecated and should be ignored if present.

Once the token has been fetched, the login may proceed.

Other fields might be included in the response, however these are deprecated and should be ignored if present.

The result field in the output indicates whether the login was successful. Non-successful results include:


 * NeedToken if the lgtoken parameter was not provided or no session was active (e.g. your cookie handling is broken).
 * WrongToken if the supplied token was not a valid token.
 * Failed (since 1.27) if the login failed. A reason field will exist in the response containing and explanation of the failure.
 * Aborted (since 1.27) if the login using the main account password (rather than a bot password) cannot proceed because user interaction is required. The  action should be used instead.
 * NoName (before 1.27) if no lgname was provided.
 * Illegal (before 1.27) if the lgname is not a valid user name.
 * NotExists (before 1.27) if supplied user does not exist.
 * EmptyPass (before 1.27) if the supplied password is empty.
 * WrongPass or WrongPluginPass (before 1.27) if the password is incorrect.
 * CreateBlocked (before 1.27) if auto-creation of the account is required but is not possible.
 * Throttled (before 1.27) if login attempts from your IP have been throttled.
 * Blocked (before 1.27) if the user being logged in to is blocked and blocks prevent login on the wiki.
 * Aborted (before 1.27) if the login was aborted by an extension without further detail. A reason field may be present.

The action
This action implements an interactive login process, which might include CAPTCHAs, interactions with third-party authentication services, two-factor authentication, and more. As such, the specific fields required may vary depending on the configuration of the wiki. A description of the fields needed should be fetched from the query.

On a wiki without any special authentication extensions, the fields needed might include username, password , and optionally rememberMe , so the login request would look something like this:

On the other hand, a wiki with a CAPTCHA extension, an extension for authentication using OpenID Connect, and a two-factor authentication extension might have a more complicated authentication process.

The client would be expected to redirect the user's browser to the provided redirecttarget. The OpenID provider would authenticate, and redirect to Special:OpenIDConnectReturn on the wiki, which would validate the OpenID response and then redirect to the loginreturnurl provided in the first POST to the API with the code and state parameters added. The client gets control of the process back at this point and makes its next API request.

Now the client needs to ask the user to check their two-factor authentication app for the current code, and submit that back to the server to continue the authentication process.

The authentication process has finally succeeded.

If at any point authentication fails, a response with status FAIL will be returned, along with a message to display to the user.

In certain cases it's possible to receive a RESTART response, for example if the OpenID Connect extension had no mapping for the OpenID account to any local user. In this case the client might restart the login process from the beginning or might switch to account creation, in either case passing the loginpreservestate or createpreservestate parameter to preserve some state.