API:Login/ja

MediaWikiのWebサービスAPIを使う場合、おそらくはアプリケーション・クライアントからログインする必要が出てくるでしょう. このためには、ログインクエリを送信する、Cookie を構築する、MediaWiki側から送られてきた確認トークンを送り返すなどの手順が必要となります.

ログインの必要性
以下のような場合には、MediaWikiにログインしてAPIを使う必要があります.


 * 特定の権限を持った利用者にしかできないことをしようとする場合
 * 膨大なリクエストを発行するため、リクエストの制限を上げたアカウントでないと実行が現実的でない場合

匿名での編集が可能なウィキの場合、ログインせずにAPIを使うこともできますが、できるだけログインして実行すべきです. プライベートウィキでは、どんなAPIを使うにもログインが必要です.

For the technical details concerning logging in, see the login manual page.

JavaScript を使用して、ブラウザー内で動かすようなクライアントを書く場合、ブラウザーでログインしておけば API を使う際に改めてログインしなくても、ログインしたアカウントとして API を使用できます.

アプリケーションごとのアカウント
アプリケーションを通常のアカウントでログインさせるのでなく、アプリケーションで使うため専用のアカウントを用意した方がいい場合があります. 特に以下の場合は専用アカウントが便利です:


 * 自動で編集を行うなど、大量の操作を行う場合
 * 巨大な、またはパフォーマンスが重要になるクエリを仕掛ける場合

アカウントを別に用意すれば、アプリケーション経由の編集を識別可能になりますし、そのアプリケーション単位の権限設定（「bot」フラグなど）も可能になります. ウィキによっては、自動編集を行う場合のルールを決めているところや、「bot」フラグの着脱ルールが決まっていることもあります.

ログイン時には、サーバ側から認証に必要なトークンの組が渡されます. api.phpを呼ぶ場合、そのトークンの組をCookieとしてリクエストごとに送信する必要があります. Cookieはおよそ1ヶ月ほど有効ですので、セッションのたびにログインするような実装ではなく、ログイントークンを保存しておいて、自身がログアウト状態かをチェックすることでログインの必要性を判断するようにシステムを組むほうがよいです.

ログイン方法
API経由でログインするには、まずログインクエリを送信して、Cookie を設定する必要があります（フレームワーク側で Cookie を処理してくれるものも多いです）. MediaWiki 1.15.3以降では、送られてきたトークンを送り返すことでログインを確認する、というステップが増えています.

ログインリクエストの構造
先ほどのリクエストで、ヘッダーにも Cookie が返されています（ ）. フレームワークで自動的に処理されない場合、続くリクエストにこの Cookie を含める必要があります. パラメーターはMediaWiki 1.17以降で追加されています.

認証にExtension:LDAP Authenticationのような拡張機能を使う場合、認証のためのドメインを与える引数として を使うことになる場合もあります.

確認トークン
先ほどのクエリで ではなく が返ってきたら、このステップは必要ありません（確認ステップは、MediaWiki 1.15.3以降で必要となります）. MediaWiki 1.15.4では、ApiLogin.phpの1段階目にバグがあり、必要なトークンが返ってこないため確認ステップを完了させられなくなっています. とりあえず対処するには、ApiLogin.phpファイルをMediaWiki 1.15.5のものに置き換える、という方法があります（なお、MediaWiki1.16以降のApiLogin.phpでは、互換性がないため動作しません）.

Handle cookies
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 $wgSessionName would require changes to your manual cookie creation code).

When CentralAuth is enabled, as on Wikimedia wikis, the above will only log you in to a single domain. If you would like to be logged in on all wikis without having to call  on each one, you will need to duplicate the cookies whose names are prefixed with "centralauth_" to the other domains covered by CentralAuth.

エラー
エラーが発生すると、 にエラーの種類が返ります. 戻り値の一部を以下に示します:
 * lgnameをセットせず、または空でリクエストした場合
 * 利用者名として不適当な値を指定した場合
 * 指定した利用者が存在しなかった場合
 * lgpasswordをセットせず、または空でリクエストした場合
 * パスワードが正しくなかった場合
 * MediaWiki自身でなく、拡張機能での認証に失敗した場合
 * アカウントを自動生成しようとしたものの、IPアドレスにアカウント作成のブロックがかかっていた場合
 * 短時間に多数のログインリクエストを行った場合. も参照のこと.
 * 利用者がブロックされていた場合
 * ログインリクエストをPOSTでなく、GETで行おうとした場合
 * ログイントークンと Cookie の両方が揃っていなかった場合. これは正常なログインの過程でも一度は発生します.
 * MediaWiki自身でなく、拡張機能での認証に失敗した場合
 * アカウントを自動生成しようとしたものの、IPアドレスにアカウント作成のブロックがかかっていた場合
 * 短時間に多数のログインリクエストを行った場合. も参照のこと.
 * 利用者がブロックされていた場合
 * ログインリクエストをPOSTでなく、GETで行おうとした場合
 * ログイントークンと Cookie の両方が揃っていなかった場合. これは正常なログインの過程でも一度は発生します.
 * 利用者がブロックされていた場合
 * ログインリクエストをPOSTでなく、GETで行おうとした場合
 * ログイントークンと Cookie の両方が揃っていなかった場合. これは正常なログインの過程でも一度は発生します.
 * ログイントークンと Cookie の両方が揃っていなかった場合. これは正常なログインの過程でも一度は発生します.
 * ログイントークンと Cookie の両方が揃っていなかった場合. これは正常なログインの過程でも一度は発生します.

速度制限
セキュリティ上の理由により、API経由のログインには速度制限があります. 標準では、5分間に5回までログインリクエストを行えますが、ウィキごとに設定変更もできます. 速度制限に引っかかった場合、 として（正しい入力でも）ログインは失敗し、制限解除までの時間が へと返されます.

例

 * PHPによるログインコード (Snoopyを使用)
 * PHPによるログインコード（cURLを使用） - Snoopyを使わない例
 * JavaScript+jQueryによるログインコード