API:Query/zh

From MediaWiki.org
Jump to: navigation, search
本页是MediaWiki action API文档的一部分。

MediaWiki action API

v · d · e

action=query模块允许您检索各种类型的数据,它不严格地基于现在已经过时的模块Query API。 action=query也被用于检查编辑等操作所需的权限.

action=query模块由许多子模块(称为查询模块)构成,每个查询模块都具有不同的功能。下面是三个查询模块:

查询模块可以自由联合。因此,您可以用如下方式在一个请求中同时调用6个查询模块:prop=info|revisions&list=backlinks|embeddedin|imagelinks&meta=userinfo

除了通过各种查询模块实现功能,action=query模块也有一些自有的功能。

查询示例[edit]

在正式开始之前,我们先来看一个获取页面信息的简单示例:

api.php?action=query&prop=revisions&rvprop=content&format=xml&titles=MediaWiki

它的意思是查询(“action=query”)维基百科的MediaWiki条目("title=MediaWiki")的最新修订("prop=revisions")的内容("rvprop=content"),并以XML格式返回("format=xml")。

另外,您也可以用action=raw作为index.php的参数,用以获取页面的内容: index.php?title=MediaWiki&action=raw

如果你想要获取页面的HTML格式,而非MediaWiki格式,要使用Parse动作(如api.php?action=parse&page=CNR%20Media&format=xml)。

指定页面[edit]

您可以用多种方式指定需要查询的页面:

  • 指定标题,使用titles参数,例如:titles=Foo|Bar|Main_Page
  • 指定页面ID,使用pageids参数,例如:pageids=123|456|75915
  • 指定修订版本号,使用revids参数,例如:revids=478198|54872|54894545
    • 注:使用revids参数时,多数的模块会使用这个修订版本ID所属的页面。只有prop=revisions模块使用这个修订版本本身。
  • 使用生成器

titles参数指定页面会面临多种问题,下面几个小节告诉你这些问题,以及如何解决。

由于中文维基百科特有的繁简和地区词问题,请求api.php?action=query&titles=贝塞尔曲线可能无法找到贝塞尔曲线条目,因为该条目的名称是繁体字的貝塞爾曲線。所以,向中文维基发出请求时,一般加上converttitles=参数,令Mediawiki进行繁简转换匹配现有条目名称。


例:查询贝塞尔曲线,辅以converttitles=redirects=


标题标准化[edit]

指定标题进行查询时,如果给定的标题不规范,会被自动转换为规范格式,这包括将首字母转为大写,将下划线替换为空格等等。无论使用什么查询模块,标题标准化都是自动完成的。但是,页面标题中的所有行末换行符(\n)都会导致模块的异常行为,所以必须先将他们去除。

首字母大写, 本地化, "_" => " ", "Project" => "Wikipedia", ...:

页面是否存在[edit]

不存在的或无效的页面仍然在<pages>段中列出,但是它们具有missing=""或者invalid=""的键值。在支持数字形式的数组索引的输出格式(比如JSON或者序列化PHP)中,不存在的和无效的标题会有一个独有的负数页面ID。查询模块会直接忽略不存在的和无效的标题,因为无法对它们做出任何有意义的操作。

检查三个标题是否存在(一个不存在、一个无效、一个存在),以JSON格式返回结果:

在Special:和Media:命名空间中的标题[edit]

目前,在Special:和Media:命名空间下的标题不能被查询。如果一个这样的标题出现在titles=中或者被生成器交送给某个模块,将会生成一个警告

处理重定向[edit]

页面重定向可以被自动处理,因而重定向之后的标题将会代替给定的标题返回。下面的例子不太有实用价值,因为它没有使用任何查询模块,但是它显示了redirects参数是如何工作的。标题标准化和重定向都会被执行。如果有二次重定向,每次重定向都会被执行。如果出现了循环重定向,'pages'节点下面可能不会列出任何页面(参见循环重定向)。重定向参数不能和revids=参数或者生成revid的生成器一起使用,否则会产生一个警告,并且不会执行对特定revid的重定向。

使用"redirects"参数。"Main page"是对"Main Page"一个重定向:

相同的请求,但是去掉了"redirects"参数:

没有"redirects"参数时,您可以使用prop=info来获取重定向状态:

循环重定向[edit]

假设有Page1 → Page2 → Page3 → Page1 (产生了循环重定向)。另外本例中使用了一个非标准化的标题'page1'。

循环重定向下的行为:

数目限制[edit]

关于数目限制的详细内容请参见这里

后续检索[edit]

很多时候,您可能无法在一次请求中获得所有返回结果。这时您可以提供一个query-continue值来继续检索。

使用query-continue来继续检索:

此时,您可以使用acfrom=List%20of%20Baptist%20sub-denominations来获得下面的10个分类。

当使用一个生成器时,您可能会获得两个query-continue值,一个是用于生成器的,另一个是用于“正常模式”的。在这种情况下,你需要首先执行“正常模式”的后续查询,直到它完成后,才可以继续使用生成器查询。您不应该将这两个query-continue参数同时设置。

获取页面ID的列表[edit]

利用indexpageids参数,你可以获得一个页面ID组成的列表,它被包括在<pageids>元素中。这点对于那些使用数字来做数组索引的数据格式(比如JSON)尤其有用。

获得一个包含页面ID的列表:

导出页面[edit]

您可以使用export参数从API中导出页面。如果设置了export参数,所有<pages>中的页面的内容将会以XML的形式包含在返回结果中。export参数只有在指定标题时才有效(使用生成器titlespageids或者revids)。请注意导出的XML会按请求中要求的格式给出;如果要求的格式是XML,<与>之类的字符会被转义成&lt;与&gt;的形式。如果也设置了exportnowrap参数,则只有相应的导出XML(未被包裹在API结果里)被返回。

导出API的内容:

导出所有在API中使用的模版:

参见导入页面

生成器[edit]

使用生成器,您可以使用一个列表的输出来代替查询中的titles参数。这个列表的输出必须是一组页面。这组页面的标题已经自动代替了titlespageid或者revids参数。其他查询模块将会把生成器如同titles参数一样处理。一次查询中只允许一个生成器。如果列表模块返回的并非页面列表,那么它就不能用作生成器。某些属性模块可以被当作生成器使用。

提交给生成器的参数必须以字母g开头。例如,使用generator=backlinks时,要用gbltitle代替bltitle

另外需要注意的是生成器只能传递“真实”的查询的页面标题,而不能给出关于生成器自己的任何信息。比如,gcmprop这样的参数并不能产生任何效果。

使用list=allpages作为生成器[edit]

在主命名空间以"Ba"开头的前三个页面中获取链接和类目:

生成器与重定向[edit]

在这里我们使用prop=links作为生成器。这个查询会在所有页面中查找所有符合标题“Title”的链接。此例中,假设页面Title具有指向TitleA和TitleB的链接,TitleB是对于TitleC的一个重定向,TitleA链接到TitleA1,TitleA2和TitleA3,而TitleC链接到TitleC1和TitleC2。因为设置了redirects参数,重定向被自动执行了。

查询将会按照以下的步骤执行:

  1. 执行titles中所规定的标题的重定向
  2. 对于所有在titles中的标题,获取相应的标题列表
  3. 在标题列表中执行页面重定向
  4. 对重定向后的标题列表执行prop=links的查询

在生成器中使用重定向:

更多生成器示例[edit]

显示以“T”开头的4个页面的信息:
http://en.wikipedia.org/w/api.php?action=query&generator=allpages&gaplimit=4&gapfrom=T&prop=info
显示以“Re”开头的前两个非重定向页面的信息:
http://en.wikipedia.org/w/api.php?action=query&generator=allpages&gaplimit=2&gapfilterredir=nonredirects&gapfrom=Re&prop=revisions&rvprop=content

可能的警告[edit]

  • No support for special pages has been implemented.(不支持特殊页面。)
    • 当请求包含在Special:或Media:命名空间中的主题时产生。
  • Redirect resolution cannot be used together with the revids= parameter. Any redirects the revids= point to have not been resolved.(重定向不能与revids=参数一起使用。)
    • 注意,此警告也可能是由一个生成revids的生成器导致的。