API:拡張機能

拡張機能:

このページは 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モジュールには) $hook1と (クエリの下位モジュールには) $hook2を用います。

Modules may also be registered conditionally using the ApiMain::moduleManager (for action and format modules) and ApiQuery::moduleManager (for query submodules) hooks.

実装

接頭辞

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

パラメーター

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

These are defined by implementing getAllowedParams().

The return value is an associative array where keys are the (unprefixed) parameter names and values are either the scalar default value for the parameter or an array defining the properties of the parameter using the PARAM_* constants defined by ApiBase.

サンプルには構文ならびに比較的よく見かける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地域化の仕組みが使われます。必要なメッセージは既定でモジュールの「パス」に基づいて命名されます。 For action and format modules, the path is the same as the module's name used during registration. For query submodules, it's the name prefixed with "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説明文書がある場合もあります。拡張機能のメインページで探すか、空間がさらに必要な場合には Extension:<ExtensionName>/API という名前のページ、またはその下位ページを検索してください (例: CentralAuth 、MassMessage 、StructuredDiscussions )。 MediaWiki コアでは、API 用に API 名前空間が予約されています。

コアモジュールの拡張

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

APIGetAllowedParams - モジュールのパラメーター一覧を追加/修正する場合
APIGetParamDescription - モジュールのパラメーターに関する説明を追加/修正する場合
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 で試用する]