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 • ‎português • ‎русский • ‎العربية • ‎ไทย • ‎中文 • ‎日本語 • ‎한국어
Gnome-preferences-other.svg Расширения: Разработка Теги расширений Руководство:Функции парсера Прерывания Служебные страницы Стили оформления (skins) Руководство:Волшебные слова API Content models

В этом документе описывается создание модуля API в расширении для MediaWiki 1.30 или более поздних версий.

Создание и регистрация модуля

Все модули API являются подклассами ApiBase , но некоторые типы модулей наследуют от производного класса. Также от типа модуля зависит метод регистрации.

модули действий (action)
Модули, предоставляющие значение для основного параметра action, должны быть подклассами ApiBase . Их нужно зарегистрировать в extension.json, используя ключ APIModules.
модули форматов (format)
Модули, предоставляющие значение для основного параметра format, должны быть подклассами ApiFormatBase. Их нужно зарегистрировать в extension.json, используя ключ APIFormatModules. Необходимость модуля формата в расширении встречается очень редко.
подмодули запросов (query)
Модули, предоставляющие значения для параметров prop, list или meta к действию action=query, должны быть подклассами ApiQueryBase (если модули не могут использоваться в качестве генераторов) или ApiQueryGeneratorBase (если модули могут использоваться в качестве генераторов). Их нужно зарегистрировать в extension.json используя ключ APIPropModules, APIListModules или APIMetaModules.

Во всех случаях значение ключа регистрации — объект, где ключ — название модуля, а значение — название класса. Модули также могут быть зарегистрированы условно, если использовать хуки ApiMain::moduleManager (для модулей действий и форматов) и ApiQuery::moduleManager (для подмодулей запросов).

Реализация

Префикс

Когда вы вызываете parent::__construct() в конструкторе вашего модуля API, вы можете также указать префикс для параметров вашего модуля. (В генерируемой документации модуля этот префикс, если он присутствует, будет указан в круглых скобках в заголовке модуля.) Если ваш модуль — подмодуль запроса (query), префикс обязателен, так как клиент в одном запросе может вызвать несколько подмодулей, каждый со своими параметрами. В случае с модулями действия или форматирования префикс необязателен.

Параметры

Большинство модулей требуют параметры. Они определяются путём реализации 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» (предел объёма выдаваемой информации). От этого стандарта обычно не следует отклоняться.
            '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,
            ],
        ];
    }

Параметры документируются с использованием i18n механизма MediaWiki. Подробности в разделе #Documentation.

Выполнение и вывод

Код, реализующий модуль, размещается в методе execute(). Такой код, как правило, использует $this->extractRequestParameters() для получения входных параметров, а также $this->getResult() для получения объекта ApiResult, в который будет добавлен вывод.

Подмодули запроса типа prop должны использовать $this->getPageSet() для получения списка обрабатываемых страниц.

Подмодули запроса, которые могут быть использованы в качестве генераторов, также должны реализовать метод executeGenerator(), которому передаётся объект ApiPageSet, пополняемый генерируемыми страницами. В этом случае ApiResult обычно не следует использовать.

Кэширование

По умолчанию ответы API указываются как не подлежащие кэшированию ('Cache-Control: private')! В случае с модулями действий кэширование можно разрешить, вызвав $this->getMain()->setCacheMode(). При этом от клиентов нужно будет передать параметр maxage или smaxage, чтобы кэширование было включено. Принудительно включить кэширование можно, вызвав $this->getMain()->setCacheMaxAge().

В случае с модулями запроса не вызывайте эти методы. Вместо этого кэширование можно разрешить, реализовав getCacheMode().

И в том, и в другом случае важно убедиться, что приватные данные не разглашаются.

Обработка токенов

Если ваш модуль действия как-либо изменяет вики, ему следует требовать какой-либо токен. Чтобы это обрабатывалось автоматически, реализуйте метод needsToken(), возвращая из него тип необходимого токена (скорее всего это токен редактирования 'csrf'). В этом случае базовый код API автоматически проведёт проверку токена, предоставленого клиентом в параметре token запроса к API.

Доступ к главной базе данных

Если ваш модуль обращается к главной базе данных, в нём следует реализовать метод isWriteMode(), чтобы он возвращал true.

Возврат ошибок

ApiBase включает несколько методов для разного рода проверки вводимых данных, например:

  • Если вам нужно удостовериться, что из набора параметров указан ровно один, используйте $this->requireOnlyOneParameter().
  • Если вам нужно удостовериться, что из набора параметров указано не более одного, используйте $this->requireMaxOneParameter().
  • Если вам нужно удостовериться, что из набора параметров указано не менее одного, используйте $this->requireAtLeastOneParameter().
  • Если вам нужно удостовериться, что у участника есть определённые права, используйте $this->checkUserRightsAny().
  • Если вам нужно удостовериться, что участник может выполнить действие на заданной странице, используйте $this->checkTitleUserPermissions().
  • Если участник заблокирован (и для вашего модуля это важно), передайте объект Block методу $this->dieBlocked().

Вам нередко придётся сталкиваться с необходимостью вызвать ошибку самостоятельно. Обычно это делается путём вызова $this->dieWithError(), но если у вас есть значение StatusValue с информацией об ошибке, вы можете передать его $this->dieStatus(), а не вызывать указанный выше метод.

Если вам нужно вернуть предупреждение, а не ошибку, используйте $this->addWarning() или $this->addDeprecation(), если вы сообщаете об устаревании использованных клиентом возможностей.

Документация

API документируется посредством встроенного в MediaWiki механизма i18n. Необходимые сообщения обычно имеют имена по умолчанию, основанные на «пути» модуля. В случае с модулями действий и форматов путь такой же, как использованное при регистрации название модуля. В случае с подмодулями запросов путь — название модуля с префиксом «query+».

Каждому модулю потребуется сообщение apihelp-$path-summary, в котором следует указать однострочное описание модуля. Также может быть создано сообщение с расширенным описанием, apihelp-$path-extended-description. Каждому параметру потребуется сообщение apihelp-$path-param-$name, а параметры, использующие PARAM_HELP_MSG_PER_VALUE, должны обладать сообщением apihelp-$path-paramvalue-$name-$value для каждого значения параметра.

Больше информации о документировании API указано на странице API:Локализация .

Расширения также могут размещать дополнительную документацию по API на MediaWiki.org. Она должна быть расположена на основной странице расширения, или если для неё нужно много места, на странице Extension:<Название расширения>/API или её подстраницах (например как у CentralAuth, MassMessage и StructuredDiscussions). Пространство имён API предназначено только для документации API ядра MediaWiki.

Расширение встроенных в ядро модулей

Начиная с MediaWiki 1.14, функциональные возможности встроенных в ядро модулей могут быть расширены с использованием следующих хуков:

  • APIGetAllowedParams позволяет изменять параметры модуля или добавлять новые
  • APIGetParamDescription позволяет добавлять или изменять описания параметров модуля
  • APIAfterExecute позволяет выполнять какое-либо действие после исполнения модуля (но до выдачи результата)
    • Используйте APIQueryAfterExecute для модулей prop=, list= и meta=
      • Если модуль запущен в режиме генератора, вместо этого хука будет вызван APIQueryGeneratorAfterExecute

Список расширений с функциями для API

Категория API extensions содержит примеры расширений, дополняющих или расширяющих API.

Тестирование своего расширения

  • Перейдите на страницу api.php и найдите автоматически сгенерированную документацию по вашему модулю или подмодулю query. Справочная информация по вашему расширению должна быть сгенерирована правильно.
    • Примеры URL, которые вы привели в вызовах getExamplesMessages(), должны появиться в списке «Примеры». Попробуйте перейти по этим ссылкам.
    • Поэкспериментируйте, убирая некоторые параметры URL и/или внося намеренные ошибки в них, и посмотрите, как ваше расширение отреагирует на такой ввод.
  • Перейдите на Special:ApiSandbox и исследуйте свой API в интерактивном режиме.
  • Перейдите по ссылке , чтобы получить дополнительную информацию о своём расширении.