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

From mediawiki.org
Jump to navigation Jump to search
This page is a translated version of the page API:Data formats and the translation is 100% complete.
Other languages:
Deutsch • ‎English • ‎Türkçe • ‎español • ‎français • ‎polski • ‎português do Brasil • ‎русский • ‎українська • ‎বাংলা • ‎中文 • ‎日本語 • ‎한국어

Вхідні дані

API отримує вхідні дані з параметрів, наданих в запиті HTTP у форматі application/x-www-form-urlencoded чи multipart/form-data. Кожен модуль і підмодуль має власний набір параметрів, які перелічені в документації та в action=help. Їх також можна отримати за допомогою action=paraminfo .

Кодування

Всі вхідні дані мають бути закодовані в UTF-8, у формі NFC.

MediaWiki намагатиметься перетворювати інші формати, що може призвести до помилок.

Параметри зі списком значень

Для параметрів, які отримують водночас кілька значень, ці значення зазвичай передаються розділеними вертикальною рискою (|), приміром, param=value1|value2. Якщо одне зі значень такого параметру містить вертикальну риску, застосуйте U+001F (Unit Separator) як розділювач та почніть це значення із U+001F, приміром, як param=%1Fvalue1%1Fvalue2.

Чи може параметр набувати переліку значень, явно вказано в документації щодо його модулю.

Булеві параметри

Якщо в запиті HTTP вказано будь-яке значення булевого параметру, воно вважається еквівалентним істині. Для значення хиби пропустіть параметр як такий, не згадуючи його взагалі. Найкращий спосіб передавання значення істина в запиті HTTP виглядає так: someParam=; знак = наприкінці гарантує, що браузер чи бібліотека HTTP не викине someParam як порожній.

Часові позначки

Параметри, які набувають значень часової позначки, приймають часову позначку в різних форматах:

Виводяться часові позначки завжди у форматі ISO 8601.

Вихід

Стандарт і формат виходу за замовчуванням у MediaWiki - це JSON. Будь-які інші формати не рекомендовані.

Формат виходу завжди має бути заданий за допомогою format=yourformat із yourformat і є одним із:

  • json: формат JSON (рекомендовано)
  • php: серіалізований PHP-формат. (deprecated)
  • xml: формат XML. (deprecated)
  • txt: формат PHP print_r() (removed in 1.27)
  • dbg: формат PHP var_export() (removed in 1.27)
  • yaml: формат YAML (removed in 1.27)
  • wddx: формат WDDX (removed in 1.26)
  • dump: формат PHP var_dump() (removed in 1.26)
  • none: Повертає порожню відповідь. 1.21+

Приклад

Отримати вихідні дані у JSON.

Відповідь

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

Якщо не вказано інше, кожен модуль дозволяє виводити дані у всіх загальних форматах. Для спрощення налагодження всі загальні формати мають альтернативи типу "pretty-print in HTML", записані із суфіксом fm, як-от jsonfm.

Параметри JSON

Наступні параметри можуть бути застосовані з format=json та format=jsonfm:

  • utf8: Закодовує більшість (але не всі) символи не-ASCII у UTF-8, замість заміни їх шістнадцятковими керівними послідовностями. Type: boolean.
  • ascii: Закодовує всі символи не-ASCII як шістнадцяткові керівні послідовності. Type: boolean.
  • formatversion: Форматування виводу. 1.25+
    • 1: Сумісний із попередніми формат застосовує ключ * для вузлів вмісту та кодує не-ASCII символи як шістнадцяткові керівні послідовності.
    • 2: Сучасний формат. Відповідь надається в зрозумілішому форматі, більшість не-ASCII символів закодовано в UTF-8. (рекомендовано)
  • callback: Функція, до якої буде передано результат. З міркувань безпеки всі специфічні для користувача дані будуть обмежені. Ось що заборонено для підтримки безпеки:
    • Не можна отримати талони, тому дії, які змінюють стан, недоступні.
    • Клієнт розглядається як анонімний (неавторизований) користувач, навіть якщо він був авторизований через action=login . Це значить, що модулі, яким потрібні додаткові дозволи, працюватимуть лише з тими дозволами, які надано анонімному користувачу.

Технічні примітки

  • Формати виводу XML та PHP не рекомендовані, але все ще застосовуються. Клієнти, написані на PHP, мають уникати формату PHP, оскільки він фундаментально не забезпечує безпеки. Він підтримується досі лише внаслідок його популярності.
  • Існує багато бібліотек та онлайн-перетворювачів для перетворення відповідей JSON в інші формати — зокрема, JSON-CSV перетворює на перелік розділених комою значень.
  • Модулі завантаження на кшталт Завантаження нових змін застосовують відмінний від стандартного формат виводу, як-от RSS чи Atom, як указано в їхньому параметрі feedformat. В таких випадках формат, указаний параметром format, застосовується лише при виникненні помилки.

Див. також