Jump to content

API:Datové formáty

From mediawiki.org
This page is a translated version of the page API:Data formats and the translation is 100% complete.
Languages:

Vstup

API přijímá vstupní údaje prostřednictvím parametrů poskytnutých HTTP požadavkem ve formátu application/x-www-form-urlencoded nebo multipart/form-data. (unlike REST API, the Action API currently does not support application/json input format.) Každý modul a submodul má svou vlastní sadu parametrů, které jsou uvedeny v dokumentaci a v souboru action=help. Lze je také načíst pomocí funkce action=paraminfo .

Kódování

Veškerý vstup musí být platný UTF-8, ve formátu NFC. MediaWiki se pokusí převést jiné formáty, což může vést k chybě.

Vícehodnotové parametry

Parametry, které nabývají více hodnot, se obvykle odesílají oddělené svislou čárou (|), např. param=value1|value2. Pokud hodnota sama o sobě obsahuje znak svislé čáry, použijte jako oddělovač U+001F (oddělovač jednotek) a před hodnotu uveďte předponu U+001F, např. param=%1Fvalue1%1Fvalue2.

Zda parametr přijímá více hodnot, je explicitně uvedeno v dokumentaci k jeho modulu.

Booleovské parametry

Pokud je v HTTP požadavku zadán booleovský parametr, je považován za pravdivý bez ohledu na svou hodnotu. V případě hodnoty nepravdivý parametr zcela vynechejte. Nejlepší způsob, jak v HTTP požadavku zadat parametr s hodnotou true, je použít someParam=; koncový = zajišťuje, že prohlížeč nebo HTTP knihovna nezahodí „prázdný“ someParam.

Časová razítka

Parametry, které přijímají hodnoty časového razítka, akceptují více formátů časového razítka:

Časová razítka jsou vždy výstupem ve formátu ISO 8601.

Výstup

Standardní a výchozí výstupní formát v MediaWiki je JSON. Všechny ostatní formáty se nedoporučují.

Výstupní formát by měl být vždy specifikován pomocí format=yourformat, kde yourformat je jedna z následujících hodnot:

  • json: Formát JSON. (doporučeno)
  • php: Formát serializovaný v PHP. (zastaralé)
  • xml: Formát XML. (zastaralé)
  • txt: Formát PHP print_r(). (odstraněno od 1.27)
  • dbg: Formát PHP var_export(). (odstraněno od 1.27)
  • yaml: Formát YAML. (odstraněno od 1.27)
  • wddx: Formát WDDX. (odstraněno od 1.26)
  • dump: Formát PHP var_dump(). (odstraněno od 1.26)
  • none: Vrátí prázdnou odpověď. 1.21+

Příklad

Získejte výstup ve formátu JSON.
api.php?action=query&titles=Main%20page&format=json [zkuste v ApiSandbox]

Odpověď

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

Pokud není uvedeno jinak, všechny moduly umožňují výstup dat ve všech generických formátech. Pro zjednodušení ladění mají všechny generické formáty alternativy pro "přiměřený tisk v HTML" s příponou fm, např. jsonfm.


Parametry JSON

S format=json a format=jsonfm lze použít následující parametry:

  • utf8: Kóduje většinu (ale ne všechny) znaky mimo ASCII jako UTF-8 namísto jejich nahrazení hexadecimálními escape sekvencemi. Typ: boolean.
  • ascii: Kóduje všechny znaky mimo ASCII pomocí hexadecimálních escape sekvencí. Typ: boolean.
  • formatversion: Formátování výstupu. 1.25+
    • 1: Zpětně kompatibilní formát, používá klíče * pro uzly obsahu, kóduje znaky jiné než ASCII pomocí hexadecimálních escape sekvencí.
    • 2: Moderní formát. Vrací odpovědi v čistším formátu, kóduje většinu znaků mimo ASCII jako UTF-8. (doporučeno)
  • callback: Odpověď ve formátu JSON, zabalením výsledku do volání funkce JavaScript. Z bezpečnostních důvodů tyto odpovědi ignorují veškeré soubory cookie relace prohlížeče a odpovídají bez informací specifických pro aktuálně přihlášeného uživatele. To znamená, že následující funkce jsou z bezpečnostních důvodů deaktivovány:
    • Tokeny nelze získat, takže akce měnící stav nejsou možné.
    • Klient je pro všechny účely považován za anonymního uživatele (tj. nepřihlášeného), a to i po přihlášení přes action=login . To znamená, že moduly, které vyžadují další práva, nebudou fungovat, pokud cílová wiki neumožní jejich používání anonymním uživatelům.


Další poznámky

  • Výstupní formáty XML a PHP jsou zastaralé, ale stále se používají. Klienti napsaní v PHP by se měli vyvarovat používání formátu PHP, protože je v zásadě nejistý. Prozatím se udržuje pouze kvůli své popularitě.
  • Existuje mnoho konverzních knihoven a online převodníků pro převod JSON odpovědí do jiných formátů – například JSON-CSV převádí na Comma-Separated Values.
  • Moduly feedů, jako například Feed Recent Changes, přepíší standardní výstupní formát a místo něj použijí RSS nebo Atom, jak je specifikováno v jejich parametru feedformat. V těchto případech se formát zadaný v parametru format použije pouze v případě chyby.


Související odkazy


Retrieved from "https://www.mediawiki.org/w/index.php?title=API:Data_formats/cs&oldid=7918740"