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

From MediaWiki.org
Jump to: navigation, search
This page is a translated version of the page API:Data formats and the translation is 100% complete.

Other languages:
বাংলা • ‎Deutsch • ‎English • ‎español • ‎français • ‎日本語 • ‎한국어 • ‎polski • ‎română • ‎русский • ‎українська • ‎中文
Эта страница является частью документации по MediaWiki action API.

API действий MediaWiki

v · d · e

Ввод

API принимает ввод через параметры, предоставленные строкой запроса, или через данные POST в форматах application/x-www-form-urlencoded или multipart/form-data. Каждый модуль (и каждый подмодуль action=query) обладает собственным набором параметров, который указан в документации и в action=help, и получить его можно через action=paraminfo.

Кодировка

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

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

Некоторые параметры могут принимать несколько значений, разделённых вертикальной чертой (|). Например, чтобы указать для параметра color три значение red, green и blue, в запросе нужно написать color=red|green|blue. Принимает ли параметр список значений, указано явно в action=paraminfo и action=help. Документация не выделяет явно параметры, принимающие списки значений, но описания этих параметров обычно содержат фразы наподобие «Список ...» или «Разделённый вертикальными чертами список ...».

Если нужно отправить список значений, некоторые из которых содержат символ вертикальной черты (такое должно встречаться редко, так как большинство параметров с множеством значений — списки названий страниц или имён участников, а ни те, ни другие не могут содержать символ вертикальной черты), следует использовать символ разделителя элементов: color=<US>r|ed<US>gr|een<US>bl|ue (где <US> означает U+001F) отправит три значения, а именно r|ed, gr|een и bl|ue. (Обратите внимание, что в самом начале тоже присутствует символ <US>. Это обязательно нужно для того, чтобы избежать неоднозначность при отправке одного значения, содержащего символ вертикальной черты.)

Булевы значения

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

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

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

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

Выход

API движка MediaWiki исторически поддерживал большое количество различных форматов, но это привело к значительному усложнению дальнейшей разработки. Мы бы хотели оставить в качестве стандарта только один формат JSON. На данный момент MediaWiki не рекомендует к использованию, но всё ещё поддерживает два дополнительных обобщённых формата вывода (XML и PHP). Всегда следует указывать формат с параметром запроса format и значением в нижнем регистре. Модули лент, наподобие ленты свежих правок, переопределяют стандартный формат вывода, вместо этого используя RSS или Atom, как указано в их параметре feedformat. В этих случаях формат, указанный в параметре format используется только при возникновении ошибки. Все форматы, кроме JSON, отмечены как устаревшие. XML и PHP всё ещё поддерживаются, но все остальные удалены в MediaWiki 1.26 или 1.27; см. таблицу ниже. Всем новым пользователи API следует использовать JSON. Клиентам, написанным на PHP, следует избегать использования формата PHP, поскольку он фундаментально небезопасен. Он поддерживается на данный момент только ввиду его популярности.

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

Использовавшийся по умолчанию в более ранних версиях MediaWiki формат xmlfm в MediaWiki 1.25 был заменён на jsonfm.

Обратите внимание, что, хотя все форматы с HTML-форматированием используют отступы и разделяют синтаксические элементы новыми линиями, обычные форматы этого не делают.

Формат Описание
json Формат JSON (всегда использовать именно его)
none Всегда возвращать пустой ответ 1.21+
Не рекомендуются к использованию, но всё ещё рабочие
php Формат сериализованного PHP
xml Формат XML
Форматы удалены в MediaWiki 1.26
wddx Формат WDDX
dump Формат PHP var_dump()
Форматы, удалённые в MediaWiki 1.27
txt Формат PHP print_r()
dbg Формат PHP var_export()
yaml Формат YAML

Существует большое количество библиотек и онлайн-ресурсов для преобразования ответов в формате JSON в другие форматы, например, JSON-CSV преобразовывает JSON в CSV

Параметры JSON

Форматы format=json и jsonfm принимают следующие параметры:

  • callback: If specified, wraps the output into a given function call. For safety, all user-specific data will be restricted.
  • utf8: If specified, encodes most (but not all) non-ASCII characters as UTF-8 instead of replacing them with hexadecimal escape sequences.
  • formatversion Specify formatversion=2 for to get json (and php) format responses in a cleaner format. This also encodes most non-ASCII characters as UTF-8. MW 1.25+

Ограничения обратного вызова

При использовании JSON в режиме обратного вызова, в целях безопасности отключены следующие возможности:

  • Токены не могут быть получены, поэтому невозможно выполнение изменяющих состояние действий
  • Клиент рассматривается как анонимный (не зашедший в свою учётную запись) пользователь, даже если произведён вход посредством action=login
    • Это означает, что действия, для выполнения которых нужны дополнительные права, например rcprop=patrolled, не будут выполняться, если анонимным пользователям не разрешено их выполнять.

Примеры

JSON

Может быть полезным добавить параметр '&indexpageids', чтобы обработать JSON ответ, если идентификатор страницы, pageid (в данном случае "736"), не известен заранее.

JSON utf8 content on a French page, remove the utf8= parameter to see the difference

XML

PHP (serialized format, with line breaks added for readability. Use PHP's unserialize() function to recover data.)

PHP (var_export format)