API:Форматы данных

This page is a translated version of the page API:Data formats and the translation is 95% complete.

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

Ввод

API принимает входные данные через параметры, предоставляемые HTTP-запросом в формате application/x-www-form-urlencoded или multipart/form-data. (unlike REST API, the Action API currently does not support application/json input format.) Каждый модуль и подмодуль обладает собственным набором параметров, которые перечислены в документации и в action=help. Их также можно получить через action=paraminfo .

Кодировка

Все вводимые данные должны быть переданы в корректном коде UTF-8, в форме NFC. MediaWiki попытается преобразовать другие форматы. В ходе преобразования может возникнуть ошибка.

Параметры с списком значений

Параметры, которые принимают несколько значений, обычно передаются со значениями, разделенными символом вертикальной черты (|), например param=value1|value2. Если значение содержит в себе символ вертикальной черты, используйте U+001F (Unit Separator) в качестве разделителя и начните перечисление с U+001F, например param=%1Fvalue1%1Fvalue2.

Если параметр принимает несколько значений, это явно указано в документации к модулю.

Булевы параметры

Если в HTTP-запросе указан булевый параметр, он считается истинным независимо от его значения. Для ложного значения опустите параметр полностью. Лучший способ указать истинный параметр в HTTP-запросе — это использование someParam=; завершающий знак = не допускает отбрасывания «пустого» параметра браузером или HTTP-библиотекой.

Временные отметки

Параметры, принимающие временные отметки, способны принять несколько форматов временных отметок:

формат ISO 8601: 2008-08-23T18:05:46Z.
Внутренний формат временных отметок MediaWiki : 20080823180546.
Внутренний формат временных отметок MySQL: 2008-08-23 18:05:46.
Формат временных отметок Unix 1219514746 (время, прошедшее с 1 января 1970 года, в секундах).

Временные отметки в выходных данных всегда находятся в формате ISO 8601.

Выход

Стандартный формат и формат вывода по умолчанию в MediaWiki — JSON. Все остальные форматы не рекомендуется.

Выходной формат всегда должен указываться с помощью format=yourformat, где yourformat являются одним из следующих:

json: Формат JSON. (рекомендуемый)
php: Формат сериализованного PHP. (устарело)
xml: Формат XML (устарело)
txt: Формат PHP print_r(). (удалено в 1.27)
dbg: Формат PHP var_export(). (удалено в 1.27)
yaml: Формат YAML. (удалено в 1.27)
wddx: Формат WDDX. (удалено в 1.26)
dump: Формат PHP var_dump(). (удалено в 1.26)
none: Возвращает пустой ответ. 1.21+

Пример

Получить выходные данные в JSON.

api.php?action=query&titles=Main%20page&format=json [попробуйте в ApiSandbox]

Ответ

{
  "query": {
    "pages": {
      "217225": {
        "pageid": 217225,
        "ns": 0,
        "title": "Main page"
      }
    }
  }
}

Если не указано иное, все модули поддерживают вывод данных во всех обобщённых форматах. Для облегчения отладки, все обобщённые форматы имеют альтернативы с окончанием fm, в виде форматированного HTML, например jsonfm.

Параметры JSON

Следующие параметры могут использоваться с format=json и format=jsonfm:

utf8: Кодирует большинство (но не все) не-ASCII символов в UTF-8 вместо замены их на шестнадцатеричные escape-последовательности. Тип: boolean.
ascii: Кодирует все символы, отличные от ASCII, с помощью шестнадцатеричных escape-последовательностей. Тип: boolean.
formatversion: Формат вывода. 1.25+
- 1: Обратно совместимый формат, использует ключи * для узлов содержимого, кодирует символы, отличные от ASCII, используя шестнадцатеричные escape-последовательности.
- 2: Современный формат. Возвращает ответы в более чистом формате, кодирует большинство символов, отличных от ASCII, как UTF-8. (рекомендуемый)
callback: Response in the JSON format, by wrapping the result in a JavaScript function call. For security reasons, these responses ignore any browser session cookies and respond without information specific to a current logged-in user. This means the following features are disabled for safety:
- Токены не могут быть получены, поэтому выполнение изменяющих состояние действий невозможно.
- Клиент рассматривается как анонимный (не зашедший в свою учётную запись) пользователь, даже если произведён вход посредством action=login . Это означает, что модули, которым требуются дополнительные права, не будут работать, если анонимным пользователям не разрешено их использовать.

Дополнительная информация

Выходные форматы XML и PHP устарели, но все еще используются. Клиентам, написанным на PHP, следует избегать использования формата PHP, поскольку он фундаментально небезопасен. Он поддерживается на данный момент только ввиду его популярности.
Существует большое количество библиотек и онлайн-ресурсов для преобразования ответов в формате JSON в другие форматы, например, JSON-CSV преобразовывает JSON в CSV.
Модули лент, наподобие ленты свежих правок, переопределяют стандартный формат вывода, вместо этого используя RSS или Atom, как указано в их параметре feedformat. В этих случаях формат, указанный в параметре format используется только при возникновении ошибки.

См. также

API:Errors and warnings - Содержит форматы предупреждений и ошибок.

Maintained by MediaWiki Interfaces Team.
Live chat (IRC): #mediawiki-core ^{подключиться}
Issue tracker: Phabricator MediaWiki-Action-API (Report an issue)