API:拡張機能

From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page API:Extensions and the translation is 92% complete.
Other languages:
Deutsch • ‎English • ‎Türkçe • ‎dansk • ‎español • ‎français • ‎polski • ‎português • ‎русский • ‎العربية • ‎中文 • ‎日本語 • ‎한국어

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

モジュールの作成と登録

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

actionモジュール
メインのactionパラメーターに値を送るモジュールは必ずApiBase をサブクラス化します。 登録には APIModules キーを用いて、extension.json に記載すること。
書式のモジュール
メインのformatパラメーターに値を送るモジュールは必ずApiFormatBaseをサブクラス化します。 登録にはAPIFormatModulesキーを用いてextension.jsonに記載のこと。 拡張機能に書式モジュールが必要な場合は非常にまれです。
クエリの下位モジュール
action=queryproplistmeta のパラメーターの値を渡すモジュールは、必ず ApiQueryBase (ジェネレーターとして使用できない場合) または ApiQueryGeneratorBase (ジェネレーターとして使用可能な場合) をサブクラス化します。 APIPropModulesAPIListModulesもしくは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->extractRequestParameters() を使用して入力パラメーターを取得し、出力を追加するためには $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 ベースコードによって自動的に検証されます。

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 ApiQueryTokensRegisterTypes hook to register your token.

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

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

エラーを返す

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

それでもなお、自分自身のエラーに対処する必要に迫られる事例にしばしば出会います。 通常の対処方法では $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説明文書がある場合もあります。 拡張機能のメインページで探すか、空間がさらに必要な場合には Extension:<ExtensionName>/API という名前のページ、またはその下位ページを検索してください (例: CentralAuth MassMessage StructuredDiscussions )。 MediaWiki コアでは、API 用に API 名前空間が予約されています。

コアモジュールの拡張

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

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

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

拡張機能の試験

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