API:Расширения

This page is a translated version of the page API:Extensions and the translation is 86% complete.

Outdated translations are marked like this.

Расширения:

Эта страница является частью документации по API действий MediaWiki.

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

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

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

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

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

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

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

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

api.php?action=paraminfo&modules=myext [попробуйте в ApiSandbox]