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 42% complete.
Outdated translations are marked like this.
Other languages:
English • ‎español • ‎français • ‎polski • ‎português do Brasil • ‎русский • ‎বাংলা • ‎中文 • ‎日本語 • ‎한국어

输入

API是通过询问字符串以提供该参数,或者是以application/x-www-form-urlencodedmultipart/form-data形式进行的HTTP请求。

每个模块(以及每个$query的子模块)都会有自己一组的参数,它们都列于文档中以及action=help的模块内。它们也可以通过action=paraminfo 为重新检索。

编码

所有输入在UTF-8,以及NFC的表格里应当是有效的。 MediaWiki将会尝试转换为其他的格式,这或许会导致程序上的错误。

多值参数

Parameters that take multiple values are normally submitted with the values separated using the pipe character (|), e.g. param=value1|value2. If a value contains the pipe character in itself, use U+001F (Unit Separator) as the separator and prefix the value with U+001F, e.g. param=%1Fvalue1%1Fvalue2.

Whether a parameter accepts multiple values is listed explicitly in its module documentation.

Boolean parameters

If a boolean parameter is specified in an HTTP request, it is considered true regardless of its value. 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.

时间戳

Parameters that take timestamp values accept multiple timestamp formats:

时间戳总是输出ISO 8601格式。

输出

The standard and default output format in MediaWiki is JSON. All other formats are discouraged.

The output format should always be specified using format=yourformat with yourformat being one of the following:

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

Example

Get the output in JSON.

Response

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

Unless specified, all modules allow data output in all generic formats. To simplify debugging, all generic formats have "pretty-print in HTML" alternatives with an fm suffix, e.g. jsonfm.

JSON参数

The following parameters can be used with format=json and format=jsonfm:

  • utf8: Encodes most (but not all) non-ASCII characters as UTF-8 instead of replacing them with hexadecimal escape sequences. 类型: boolean.
  • ascii: Encodes all non-ASCII characters using hexadecimal escape sequences. 类型: boolean.
  • formatversion: The output formatting. 1.25+
    • 1: Backwards-compatible format, uses * keys for content nodes, encodes non-ASCII characters using hexadecimal escape sequences.
    • 2: Modern format. Returns responses in a cleaner format, encodes most non-ASCII characters as UTF-8. (recommended)
  • callback: The function in which the result will be wrapped. For safety, all user-specific data will be restricted. 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 modules which require additional rights won't work unless anonymous users are allowed to use them.

Additional notes

  • XML and PHP output formats are deprecated but still in use. Clients written in PHP should avoid using the PHP format because it is fundamentally insecure. It is maintained for now only due to its popularity.
  • There are many conversion libraries and online converters to convert JSON responses to other formats—for example, JSON-CSV converts to Comma-Separated Values.
  • Feed modules like Feed Recent Changes override the standard output format, instead using RSS or Atom, as specified by their feedformat parameter. In those cases, the format specified in the format parameter is only used if there's an error.

See also