API:拡張機能

This page is a translated version of the page API:Extensions and the translation is 95% complete.

拡張機能:

このページは MediaWiki 操作 API の説明文書の一部です。

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

モジュールの作成と登録

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

actionモジュール: メインの action パラメーターに値を送るモジュールは必ずApiBase をサブクラス化します。登録には APIModules キーを用いて、extension.json に記載すること。
書式のモジュール: メインのformatパラメーターに値を送るモジュールは必ずApiFormatBaseをサブクラス化します。登録にはAPIFormatModulesキーを用いてextension.jsonに記載のこと。拡張機能に書式モジュールが必要な場合は非常にまれです。
クエリの下位モジュール: action=query に prop、list、meta のパラメーターの値を渡すモジュールは、必ず ApiQueryBase (ジェネレーターとして使用できない場合) または ApiQueryGeneratorBase (ジェネレーターとして使用可能な場合) をサブクラス化します。 APIPropModules、APIListModulesもしくはAPIMetaModulesのキーを用いて、必ずextension.jsonに記載します。

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

実装

接頭辞

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

パラメーター

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

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

	protected function getAllowedParams() {
		return [
			// 既定値のあるオプションのパラメータ
			'simple' => 'value',

			// 必須パラメータ
			'required' => [
				ApiBase::PARAM_TYPE => 'string',
				ApiBase::PARAM_REQUIRED => true,
			],

			// 一覧から複数値を受けるパラメータ
			'variable' => [
				// 値の既定セット
				ApiBase::PARAM_DFLT => 'foo|bar|baz',
				// 許容される値
				ApiBase::PARAM_TYPE => [ 'foo', 'bar', 'baz', 'quux', 'fred', 'blah' ],
				// 複数値を受けることがわかる
				ApiBase::PARAM_ISMULTI => true,
				// 標準の「値単位の」説明メッセージを使用してください
				ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
			],

			// 標準の「制限」パラメータ。一般的に、この標準から逸脱することは推奨されません。
			'limit' => [
				ApiBase::PARAM_DFLT => 10,
				ApiBase::PARAM_TYPE => 'limit',
				ApiBase::PARAM_MIN => 1,
				ApiBase::PARAM_MAX => ApiBase::LIMIT_BIG1,
				ApiBase::PARAM_MAX2 => ApiBase::LIMIT_BIG2,
			],
		];
	}

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

実行と出力

モジュールを実行するコードは execute() メソッドを実装します。一般的にこのコードは $this→extractRequestParams() を使用して入力パラメーターを取得し、出力を追加するためには $this→getResult() を使用してオブジェクト ApiResult を取得します。

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

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

キャッシュ

API のレスポンスは既定ではキャッシュの対象外です ('Cache-Control: private')! action モジュールにおいて $this→getMain()→setCacheMode() を呼び出すとキャッシュの実行を承認できます。その場合にも、キャッシュを実際に有効にするにはクライアントが maxage または smaxage パラメーターを渡す必要があります。 $this→getMain()→setCacheMaxAge() を呼ぶと強制キャッシュも可能です。

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

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

トークンの処理

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

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

マスターデータベースへのアクセス

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

エラーを返す

ApiBaseにはさまざまな点検のために、次の例のような複数の方式があります。

一連のパラメーターのうち正確に 1 つが指定されたことを保証する必要がある場合は、$this→requireOnlyOneParameter() を使用します。

If you need to assert that at most one of a set of parameters was supplied, use $this→requireMaxOneParameter().

If you need to assert that at least one of a set of parameters was supplied, use $this→requireAtLeastOneParameter().

If you need to assert that the user has certain rights, use $this→checkUserRightsAny().

If you need to assert that the user can take an action on a particular page, use $this→checkTitleUserPermissions().

If the user is blocked (and that matters to your module), pass the Block object to $this→dieBlocked().

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

エラーメッセージではなく警告を発するには、$this→addWarning() を使用し、廃止を予告するには $this→addDeprecation() を使用します。

説明文書

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

モジュールごとに apihelp-$path-summary メッセージを用意する必要があり、モジュールを1行で簡明に説明します。さらにヘルプテキストを設ける場合には apihelp-$path-extended-description を作成できます。パラメーターごとに apihelp-$path-param-$name メッセージを用意し、PARAM_HELP_MSG_PER_VALUE を用いるパラメーターにも値ごとに apihelp-$path-paramvalue-$name-$value を用意します。

API説明文書の詳細は API:地域化を参照してください。

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

コアモジュールの拡張

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

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

API機能を備えた拡張機能の一覧

API を追加/拡張する拡張機能の例はカテゴリ:API 拡張機能を参照してください。

拡張機能の試験

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

api.php?action=paraminfo&modules=myext [ApiSandbox で試用する]