API:Login/ja

MediaWiki のウェブ サービスを使用する際、あなたのアプリケーションまたはクライアントをログインさせる必要がある場合があるでしょう. ログインには、ログイン クエリを送信する、Cookie を構築する、返された確認トークンを付加したログイン リクエストを再送信することでログインを確認する、という処理が必要になります.

ログインすべきかどうか
あなたのクライアントを MediaWiki にログインさせる必要があるのは以下の場合でしょう:


 * 特定の権限を持つ利用者に制限された情報を取得したり、制限された操作を実行する必要がある
 * 膨大なリクエストを発行するため、リクエストごとの制限を緩和したアカウント以外での実行が現実的ではない場合

匿名で編集できるウィキでは、ログインしなくても API 経由で編集できますが、ログインすることを強く推奨します. 非公開のウィキでは、あらゆる API 機能についてログインが必須です.

あなたのクライアントが JavaScript で書かれている場合は、通常、そのクライアントを実行している利用者の認証情報を使用して動作します. この場合、ウェブ サービス API を使用してログインする必要はなく、利用者がウェブ インターフェイスを使用してログイン済みである必要があるのみです.

アプリケーション固有の利用者アカウント
アプリケーションをあなたのアカウントでログインさせるのでなく、アプリケーションで使用する利用者アカウントを別に作成した方がいい場合があります. これは、アプリケーションが以下の場合に特に重要です:


 * 編集やその他の一括操作を自動的に実行する.
 * 巨大な、またはパフォーマンスに影響を与えるクエリを実行する.

別にアカウントを用意しておけば、アプリケーション経由で行った編集を簡単に見分けられますし、特殊な権限 (通常は「Bot」利用者グループ) をアプリケーションのアカウントに対して付与することもできます. ウィキによっては、自動的な編集について方針を決めている場合、また「Bot」権限の付与申請について規定がある場合もあります.

ログインすると、ログイン済み利用者を識別するのに必要ないくつかのトークンが、サーバー側から渡されます. 最初のリクエストの時に受け取ったCookieが、api.phpへのリクエストのたびに必要となります. ログインクッキーの有効期間は1ヶ月ほどありますので、（毎回ログインするような実装にはせず）すでにログインしているかチェックの上でログインを試みるのが適当でしょう. You can check this on any request using the  generic parameter.

ログイン方法
API経由でログインするには、ログインクエリの送信と、Cookieの設定が必要になります（フレームワーク側でCookieを組み立ててくれる環境も多いですが）. MediaWiki 1.15.3以上では、確認のために、1度目のリクエストで返ってきたトークンを使って再リクエストを行う必要があります.

ログイン リクエストの構造
ログインリクエストはPOSTで行いますが、リクエストボディは空でも構いません. This request will also return a session cookie in the HTTP header that you have to return for the second request if your framework does not do this automatically. The sessionid parameter was added in MediaWiki 1.17 and later.

You might need to add the query parameter, containing your domain name for authentication, if you're using an authentication plug-in like Extension:LDAP Authentication.

Confirm token
If the response to the above query was  instead of , 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 while you plan your upgrade to 1.15.5. ApiLogin.php from MediaWiki 1.16+ is incompatible with MediaWiki 1.15.3+.

Cookie の処理
A successful  request will set cookies needed to be considered logged in. Many frameworks will handle these cookies automatically (such as the cookiejar in cURL). If so, by all means take advantage of this. 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フィールドに返されますが、取りうる値は以下のようになっています.

速度制限
セキュリティ上の理由で、このモジュールには速度制限があります. デフォルトでは5分間に5回のログインが可能ですが、ウィキごとに設定が変更可能です. 上限に達してしまった場合、（たとえ正当なID、パスワードだったとしても） としてログインに失敗し、 フィールドに制限解除までの秒数が入ります.

例

 * PHPでのログインコードの例:
 * Example login (requires Snoopy)
 * Example login and navigate (using only file_get_contents)
 * Example login (using cURL) - no Snoopy required
 * Example login code in JS (using JQuery)
 * Example login code in Python