API:Login/ja

From MediaWiki.org
Jump to: navigation, search
Tools clipart.png このページは MediaWiki API 説明文書の一部です。
言語: English  • Deutsch • español • français • 日本語 • русский • 中文 • 中文（繁體）‎
MediaWiki API

Quick overview:

v · d · e

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

Contents

ログインの必要性[edit]

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

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

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

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

アプリケーションごとのアカウント[edit]

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

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

には、専用アカウントが特に便利です。

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

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

ログイン方法[edit]

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

ログインリクエストの構造[edit]

api.php?action=login&lgname=Bob&lgpassword=secret
結果
The following content has been placed in a collapsed box for improved usability. 
<?xml version="1.0" encoding="utf-8"?>
<api>
  <login
    result="NeedToken"
    token="b5780b6e2f27e20b450921d9461010b4"
    cookieprefix="enwiki"
    sessionid="17ab96bd8ffbe8ca58a78657a918558e"
  />
</api>
The above content has been placed in a collapsed box for improved usability.

先ほどのリクエストで、ヘッダにもクッキーが返されています（Set-Cookie: enwiki_session=17ab96bd8ffbe8ca58a78657a918558e; path=/; domain=.wikipedia.org; HttpOnly）。フレームワークで自動的に処理されない場合、続くリクエストにこのクッキーを含める必要があります。sessionidパラメーターはMediaWiki 1.17以降で追加されています。なお、リクエストの結果がHTMLとして返ってきてしまうばあい、引数にformat=xml（あるいは他の適当なもの）を指定する必要があります。

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

確認トークン[edit]

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


api.php?action=login&lgname=Bob&lgpassword=secret&lgtoken=b5780b6e2f27e20b450921d9461010b4
結果
The following content has been placed in a collapsed box for improved usability. 
<?xml version="1.0" encoding="utf-8"?>
<api>
  <login
    result="Success"
    lguserid="12345"
    lgusername="Bob"
    lgtoken="4db760e273b413549a32ba4eb06d08db"
    cookieprefix="enwiki"
    sessionid="17ab96bd8ffbe8ca58a78657a918558e"
  />
</api>
The above content has been placed in a collapsed box for improved usability.

クッキーの作成[edit]

action=loginが成功すると、クッキーが生成されます。cURLのcookiejarのように、フレームワーク側で処理してくれる場合も多いですが、そうでない場合はプログラム側で管理が必要となります。

もちろん、Set-Cookie:ヘッダをパースしてクッキーを組み立てても構いませんが、CentralAuthのないウィキでは、レスポンスボディからクッキーを作ることができます。

具体例をあげてみると、上の例では2度目のリクエストの際に以下のようなクッキーをセットすることとなります。
  • enwiki_session = 17ab96bd8ffbe8ca58a78657a918558e (レスポンスのsession値)
そして、ログイン後には以下のようなクッキーが必要となります。
  • enwikiUserName = Bob (lgusername値)
  • enwikiUserID = 12345 (lguserid値)
  • enwikiToken = 4db760e273b413549a32ba4eb06d08db (lgtoken値)
なお、enwikiの部分はウィキごとに異なってきます（cookieprefixの値を使います）。

ウィキメディア・プロジェクトのようにCentralAuthが有効な場合、上のような方法や、クッキーをそのまま受け入れるだけの方法では、1つのウィキにしかログインできません。SULを適用したい場合は、次の節にあるように、Set-Cookie:を自前でパースして、必要なクッキーを生成する必要があります。


CentralAuth SUL ログイン[edit]

  1. ふつうにログインします。
  2. レスポンスヘッダーのSet-Cookie:として、通常ログイン用のクッキー以外にSUL用のクッキーも返ってきます（通常、単独のウィキに必要なクッキー3つとSUL用のクッキーが3つ、合わせて6つの値になっています。例えばウィキメディア・コモンズでは、commonswiki_session, centralauth_User, centralauth_Token, centralauth_Session, commonswikiUserID, commonswikiUserNameのようになっており、太字のものがSUL用の値です）。
  3. あとはクッキーの中から、centralauth_で始まるものを抜き出して、他のドメインにも同じクッキーを適用させるだけです。

例えば、ウィキメディア・プロジェクトでは、以下のドメインに対して同じクッキーをセットします。

    • .wikipedia.org
    • .meta.wikimedia.org
    • .wiktionary.org
    • .wikibooks.org
    • .wikiquote.org
    • .wikisource.org
    • .commons.wikimedia.org
    • .wikinews.org
    • .wikiversity.org
    • .mediawiki.org
    • .wikidata.org
    • .species.wikimedia.org
    • .incubator.wikimedia.org
    • .wikivoyage.org

エラー[edit]

エラーが起きると、resultに起きたエラーの種類が返ります。返り値は以下のようになっています。

  • NoName
    • lgnameをセットせず、あるいは空でリクエストした場合
  • Illegal
    • 利用者名として不適当な値を指定した場合
  • NotExists
    • 指定した利用者が存在しなかった場合
  • EmptyPass
    • lgpasswordをセットせず、あるいは空でリクエストした場合
  • WrongPass
    • パスワードが正しくなかった場合
  • WrongPluginPass
    • MediaWiki自身でなく、拡張機能での認証に失敗した場合
  • CreateBlocked
    • アカウントを自動生成しようとしたものの、IPアドレスにアカウント作成のブロックがかかっていた場合
  • Throttled
    • 短時間に多数のログインリクエストを行った場合。#速度制限も参照のこと。
  • Blocked
    • 利用者がブロックされていた場合
  • mustbeposted
    • ログインリクエストをPOSTでなく、GETで行おうとした場合
  • NeedToken
    • ログイントークンとクッキーの両方が揃っていなかった場合。これは正常なログインの過程でも一度は発生します。

速度制限[edit]

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

例[edit]

Retrieved from "http://www.mediawiki.org/w/index.php?title=API:Login/ja&oldid=689689"