API:Extensions/ja

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

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


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


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


 * クエリの下位モジュール
 * $propや$listまたは$metaの値、$actionの属性値を与えるモジュールは、必ず$ApiQueryBase（ジェネレータとして使用が不可な場合）か$ApiQueryGeneratorBase（同じく使用可能な場合）をサブクラス化します. 、 もしくは のキーを用いて、必ず に記載します.

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

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

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

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

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

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

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

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

キャッシュ
APIの反応は既定ではキャッシュの対象外です ('Cache-Control: private')! actionモジュールにおいてを呼び出すとキャッシュの実行を承認できます. その場合にも、クライアントが もしくは パラメータを容認してからでないとキャッシュできません. を呼ぶと強制キャッシュも可能です.

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

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

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

If you don't want to use a token that is part of core, but rather a custom token with your own permission checks, use the ApiQueryTokensRegisterTypes hook to register your token.

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

エラーを返す
にはさまざまな点検のために、次の例のような複数の方式があります.
 * パラメータセットのうちの1つが指定されたと主張するには、.
 * パラメータセットのうちの少なくとも1つが提供されたと主張するには、.
 * パラメータセットのうちの少なくとも1つが提供されたと主張するには、.
 * 利用者に特定の権利があると主張するには、.
 * 利用者に特定のページでアクションを行うことができると主張するには、.
 * 利用者がブロックを受けた (ことに加えご利用のモジュールに障害となる) 場合、 オブジェクトをにわたす.

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

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

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

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

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

WikiMedia.orgには、拡張機能が管理するその他のAPI説明文書がある場合もあります. 拡張機能のメインページで探すか、空間がさらに必要な場合には という名前のページ、あるいはその下位ページを検索してください (例：CentralAuth、MassMessageまたはStructuredDiscussionsが該当). MediaWikiコアにはAPIごとに、API名前空間が確保してあります.

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


 * モジュールのパラメータ一覧を追加もしくは修正するにはAPIGetAllowedParams
 * モジュールのパラメータに関する説明の追加もしくは修正をするにはAPIGetParamDescription
 * モジュールの実装後 (ただし結果出力の前) の処理はAPIAfterExecute
 * 、 及び モジュールに対しては APIQueryAfterExecuteを使用します
 * モジュールをジェネレータモードで実行したい場合は代わりにAPIQueryGeneratorAfterExecuteを使用します

API機能を備えた拡張機能の一覧
API機能を備えたり拡張したりする拡張機能の例はAPI extensionsをご参照ください.

拡張機能の試験

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