API:Login/ja

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.

ログインすべきかどうか
あなたのクライアントを 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で行いますが、リクエストボディは空でも構いません. レスポンスとしてCookieをセットするためのHTTPヘッダ（ ）も返ってきますので、フレームワーク側で処理してくれない場合には自分でセットする必要があります. The sessionid parameter was added in MediaWiki 1.17 and later.

Extension:LDAP認証のようなプラグイン経由で認証する場合、 にドメイン名を渡す必要があることもあります.

確認トークン
上記のクエリを行った結果が ではなくて なら、確認ステップは不要です. （この確認ステップはMediaWiki 1.15.3で追加されました） MediaWiki 1.15.4では、ApiLogin.phpの1段階目にバグがあり、login/sessionidパラメータが返って来ないため、トークンでの確認を行うことができません. バージョンアップする、あるいはApiLogin.phpだけMediaWiki 1.15.5のものに差し替える、というのが対処法となります. なお、MediaWiki 1.16以上のApiLogin.phpはMediaWiki 1.15.3と整合せず、動作しません.

Cookie の処理
のリクエストに成功すると、ログイン状態として認識させるためのクッキーが設定されます. cURLでのcookiejarのように、多くのフレームワークではクッキーが自動処理されます. 自動処理できるなら、ぜひそれをフル活用してください. 自動処理のない環境であれば、いちばん確実な方法はHTTPのSet-Cookieレスポンスヘッダを解析することです.

どちらもできない状況であれば、 のレスポンス本文に含まれる値からクッキーを組み立てることもできなくはないですが、クッキーの組み立て方が予告なしに変わりうる（が変わったというような、ちょっとしたことでもクッキー生成のコードを変更する必要が生じる）ため、おすすめはできません.

WikimediaでのようにCentralAuthが有効な場合、上のようにログインすると、1つのドメインにログインするだけでなく、centralauth用のクッキー3つもSet-Cookieで返されます. 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