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以降では、送られてきたトークンを送り返すことでログインを確認する、というステップが増えています. You can check this on any request using the  generic parameter.

ログインリクエストの構造
先ほどのリクエストで、ヘッダーにも 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 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.

エラー
Errors are returned in the result field. Possible values include:

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

例

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