API:Extensions/ja

このドキュメントでは、MediaWiki 1.30またはそれ以降での、APIモジュールの作成を扱います.



モジュールの作成と登録
すべての API モジュールは のサブクラスですが、派生したベースクラスを使用するタイプのモジュールもあります. 登録の方法もまた、モジュールのタイプに依存します.


 * actionモジュール
 * メインの パラメーターに値を送るモジュールは必ずをサブクラス化します. 登録には   キーを用いて、  に記載すること.


 * 書式のモジュール
 * メインの パラメーターに値を送るモジュールは必ずをサブクラス化します. 登録には キーを用いて に記載のこと.  拡張機能に書式モジュールが必要な場合は非常にまれです.


 * クエリの下位モジュール
 * に 、 、  のパラメーターの値を渡すモジュールは、必ず  (ジェネレーターとして使用できない場合) または  (ジェネレーターとして使用可能な場合) をサブクラス化します.   、 もしくは のキーを用いて、必ず に記載します.

どの場合も、登録キーの値はモジュール名を備えたオブジェクト (つまり属性の値) をキーに用い、クラス名はその値とします. モジュールの登録は条件付で (actionとformatモジュールには) と (クエリの下位モジュールには) を用います.

接頭辞
ご利用のAPIモジュールのコンストラクタ関数では、を呼び出すときにオプションとしてモジュールのパラメーターに接頭辞を指定できます. (モジュールに関する説明文書を作成すると、この接頭辞が存在する場合にはモジュールの見出しにカッコ入りで表示されます. ) ご利用のモジュールがクエリ用下位モジュールである場合、クライアントに正しい動作をさせるため接頭辞が必要です. 接頭辞がないと、それぞれ固有のパラメーターを要する複数の下位モジュールを一度に作動させようとしてしまいます. action及びformatモジュールについては、接頭辞の付与はオプションです.

パラメーター
大半のモジュールにはパラメーターが必要です. これらは を実装することで定義されます. 戻り値は、キーに（接頭辞のない）パラメーター名を取り、値はパラメータのスカラー既定値か、もしくはが規定する 定数を用いてパラメータのプロパティを定義する配列のいずれかとなります.

サンプルには構文ならびに比較的よく見かける 定数を示します.

パラメータの説明文書はMediaWikiのi18nの仕組み（地域化）に従います. 詳細は#説明文書節を参照してください.



実行と出力
モジュールを実行するコードは メソッドを実装します. 一般的にこのコードは を使用して入力パラメーターを取得し、出力を追加するためには  を使用してオブジェクト  を取得します.

クエリ属性の下位モジュールには を用いて、操作するページ群のセットにアクセスします.

ジェネレーターとして使用可能なクエリ下位モジュールの場合も、 の実行が必要で、生成したページ名を入力する を渡します. この事例では一般的に、 を使用すべきではありません.

キャッシュ
API のレスポンスは既定ではキャッシュの対象外です ('Cache-Control: private')!

その場合にも、キャッシュを実際に有効にするにはクライアントが  または   パラメーターを渡す必要があります.

クエリ モジュールでは、これらのモジュールの呼び出しは禁止です. その代わりに、 を実装するとキャッシュできます.

いずれの場合にも、個人特定情報をさらさないようにご注意ください.



トークンの処理
程度に関わらずご利用のactionモジュールによりウィキに変更が加えられる場合は、トークンに類するものを備える必要があります. この処理を自動化するには  メソッドを実行すると、ご利用のモジュールに必要なトークンを返します. (おそらく  として 編集トークンを出力. ) するとクライアントが  パラメーターを要求する API に対して提供するトークンは、API ベースコードによって自動的に検証されます.

コアに含まれるトークンではなく、独自の権限チェックでカスタム トークンを使用したい場合は、そのトークンを フックを使用して登録します.



マスターデータベースへのアクセス
ご利用のモジュールがマスターデータベースにアクセスする場合、 値を返すために   メソッドを実装する必要があります.



エラーを返す
にはさまざまな点検のために、次の例のような複数の方式があります.


 * 一連のパラメーターのうち正確に 1 つが指定されたことを保証する必要がある場合は、 を使用します.
 * If you need to assert that at most one of a set of parameters was supplied, use.
 * If you need to assert that at least one of a set of parameters was supplied, use.
 * If you need to assert that the user has certain rights, use.
 * If you need to assert that the user can take an action on a particular page, use.
 * If the user is blocked (and that matters to your module), pass the  object to.

それでもなお、自分自身のエラーに対処する必要に迫られる事例にしばしば出会います. 通常の対処方法では を呼び出しますが、代替手段としてエラー情報に関する   を入手し、 に渡すことができます.

エラーメッセージではなく警告を発するには、 を使用し、廃止を予告するには を使用します.

説明文書
APIの説明文書にはMediaWikiのi18n地域化の仕組みが使われます. 必要なメッセージは既定でモジュールの「パス」に基づいて命名されます. actionとformatモジュールに対しては、パスはモジュールの登録時の名称が使われます. クエリの下位モジュールの接頭辞は「query+」が採用されます.

モジュールごとに  メッセージを用意する必要があり、モジュールを1行で簡明に説明します. さらにヘルプ テキストを設ける場合には  を作成できます. パラメーターごとに  メッセージを用意し、  を用いるパラメーターにも値ごとに   を用意します.

API説明文書の詳細は を参照してください.

拡張機能について、追加の API モジュールを mediawiki.org で 文書化することもできます. 拡張機能のメインページで探すか、空間がさらに必要な場合には  という名前のページ、またはその下位ページを検索してください (例: 、、). MediaWiki コアでは、API 用に API 名前空間が予約されています.



コアモジュールの拡張
MediaWiki 1.14以降、以下のフックを使うことで、コアモジュールの機能を拡張することができます：


 * - モジュールのパラメーター一覧を追加/修正する場合
 * - モジュールのパラメーターに関する説明を追加/修正する場合
 * - モジュールの実行後 (ただし結果出力の前) に何か処理をする場合
 * 、 、 モジュールには、 を使用します
 * モジュールをジェネレーター モードで実行したい場合は代わりに を呼び出します



API機能を備えた拡張機能の一覧
API を追加/拡張する拡張機能の例は を参照してください.



拡張機能の試験

 * [/api.php api.php] を開き、ご利用のモジュールに対して作成されたヘルプまたはクエリの下位モジュールへ移動します. ご利用の拡張機能のヘルプ情報が正しいかどうか、確認する必要があります.
 * で提供したサンプルURL群が「例」に表示されるので、クリックします.
 * クエリ文字列中のURLパラメータを除去したり文字列を一部削除して、拡張機能の反応を試します.
 * Special:ApiSandboxを開き、ご利用のAPIをインタラクティブに試用します.
 * ご利用の拡張機能に関するその他の情報は、次のリンク先を開いて確認します. $api