API:Extensions/ja

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

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


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


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


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

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

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

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

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

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

実行と出力
モジュールを実行するコードは メソッドを実装します. This code will generally use to get the input parameters, and will use  to get the  object to add any output to.

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

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

キャッシュ
API のレスポンスは既定ではキャッシュの対象外です ('Cache-Control: private')! actionモジュールにおいてを呼び出すとキャッシュの実行を承認できます. その場合にも、クライアントが もしくは パラメータを容認してからでないとキャッシュできません. を呼ぶと強制キャッシュも可能です. This still requires clients pass the  or   parameters to actually enable caching. You can force caching by also calling.

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

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

トークンの処理
程度に関わらずご利用の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 hook to register your token.

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

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


 * If you need to assert that exactly one of a set of parameters was supplied, use.
 * 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.

それでもなお、自分自身のエラーに対処する必要に迫られる事例にしばしば出会います. 通常の対処方法ではを呼び出しますが、代替手段としてエラー情報に関する を入手し、にわたすことができます. The usual way to do that is to call, although if you have a  with the error information you could pass it to  instead.

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

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

モジュールごとに メッセージを用意する必要があり、モジュールを1行で簡明に説明します. さらにヘルプ文を設ける場合には を作成することができます. パラメータごとに メッセージを用意し、 を用いるパラメータにも値ごとに を用意します. If additional help text is needed,  may be created as well. Each parameter will need a  message, and parameters using   will also need a   for each value.

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

WikiMedia.orgには、拡張機能が管理するその他のAPI説明文書がある場合もあります. 拡張機能のメインページで探すか、空間がさらに必要な場合には という名前のページ、あるいはその下位ページを検索してください (例：CentralAuth、MassMessageまたはStructuredDiscussionsが該当). MediaWikiコアにはAPIごとに、API名前空間が確保してあります. This should be located on the extension's main page or, if more space is required, on pages named  or subpages thereof (e.g., , or ). The API namespace is reserved for the API of MediaWiki core.

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


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

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

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