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 100% complete.
Other languages:
Deutsch • ‎English • ‎dansk • ‎español • ‎français • ‎português • ‎русский • ‎العربية • ‎中文 • ‎日本語 • ‎한국어
OOjs UI icon puzzle-ltr.svg 拡張機能: 開発 タグ拡張機能 パーサー関数 フック 特別ページ 外装 マジックワード API Content models

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

モジュールの作成と登録

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

actionモジュール
メインのactionパラメーターに値を送るモジュールは必ずApiBase をサブクラス化します。 登録にはAPIModulesキーを用いて、extension.jsonに記載すること。
書式のモジュール
メインのformatパラメーターに値を送るモジュールは必ずApiFormatBaseをサブクラス化します。 登録にはAPIFormatModulesキーを用いてextension.jsonに記載のこと。 拡張機能に書式モジュールが必要な場合は非常にまれです。
クエリの下位モジュール
proplistまたはmetaの値、action=queryの属性値を与えるモジュールは、必ず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ベースコードによって自動的に検証されます。

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

ご利用のモジュールがマスターデータベースにアクセスする場合、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:地域化 を参照してください。

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

コアモジュールの拡張

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

  • モジュールのパラメータ一覧を追加もしくは修正するにはAPIGetAllowedParams
  • モジュールのパラメータに関する説明の追加もしくは修正をするにはAPIGetParamDescription
  • モジュールの実装後 (ただし結果出力の前) の処理はAPIAfterExecute

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

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

拡張機能の試験

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