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

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

Outdated translations are marked like this.
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.

Encoding

All input should be valid UTF-8, in NFC form. MediaWiki will attempt to convert other formats but in some cases they might result in an error.

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

Некоторые параметры могут принимать несколько значений, разделённых вертикальной чертой (|). For example, to submit the three values red, green and blue for the parameter color, you'd put color=red|green|blue in the query. Принимает ли параметр список значений, указано явно в action=paraminfo и action=help. Документация не выделяет явно параметры, принимающие списки значений, но описания этих параметров обычно содержат фразы наподобие «Список ...» или «Разделённый вертикальными чертами список ...».

If you need to submit a list of values where some of the values contain a pipe character (which should be rare - most multivalue parameters are lists of page titles or usernames, neither of which can contain pipes), you can use the unit separator character instead: color=<US>r|ed<US>gr|een<US>bl|ue (where <US> stands for U+001F) will submit the three values r|ed, gr|een and bl|ue. (Note that there is an extra <US> at the beginning. This is mandatory to avoid ambiguity around submitting a single value containing a pipe.)

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

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

Boolean parameters work like HTML checkboxes: if the parameter is specified in the HTTP request, regardless of value, it is considered true. For a false value, omit the parameter entirely. The best way to specify a true parameter in an HTTP request is to use someParam=; the trailing = ensures the browser or HTTP library does not discard the "empty" someParam.

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

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

В выводе временные отметки всегда в формате 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 format (always use this one)
none Always return a blank response 1.21+
Deprecated, but still operational
php serialized PHP format
xml XML format
Форматы удалены в MediaWiki 1.26
wddx WDDX format
dump PHP var_dump() format
Formats removed in MediaWiki 1.27
txt PHP print_r() format
dbg PHP var_export() format
yaml YAML format

There are many conversion libraries and online converters to convert JSON responses to other formats—for example, JSON-CSV converts to Comma-Separated Values

JSON parameters

format=json and jsonfm accept the following additional parameters:

  • 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+

Callback restrictions

When using JSON in callback mode, a number of things are disabled for security:

  • Tokens cannot be obtained (so state-changing actions aren't possible)
  • The client is treated as an anonymous user (i.e. not logged in) for all purposes, even after logging in through action=login
    • This means that things that require additional rights, such as rcprop=patrolled, won't work unless anonymous users are allowed to use them

Примеры

JSON

it may be useful to add the '&indexpageids' parameter, to parse the json if the pageid ("736") is not known before the result.

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)