API:Extensions/ru

Category:MediaWiki action API/ru

В этом документе описывается создание модуля 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→extractRequestParams() для получения входных параметров, а также $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.

Если вы не хотите использовать токен, который является частью ядра, а предпочитаете пользовательский токен с вашими собственными проверками разрешений, используйте хук ApiQueryTokensRegisterTypes для регистрации вашего токена.

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

Если ваш модуль обращается к главной базе данных, в нём следует реализовать метод 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. Она должна быть расположена на основной странице расширения, или если для неё нужно много места, на странице $1 или её подстраницах (например как у CentralAuth, MassMessage и StructuredDiscussions). Пространство имён API предназначено только для документации API ядра MediaWiki.

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

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

  • APIGetAllowedParams - позволяет изменять параметры модуля или добавлять новые
  • APIGetParamDescriptionMessages - позволяет добавлять или изменять описания параметров модуля
  • APIAfterExecute - позволяет выполнять какое-либо действие после исполнения модуля (но до выдачи результата)

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

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

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

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