API:Query/zh

From MediaWiki.org
Jump to: navigation, search
Tools clipart.png This page is part of the MediaWiki PHP action API documentation.
MediaWiki APIAPI:Main page



MediaWiki PHP 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 | edit source]

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

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 | edit source]

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

  • 指定标题，使用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=：
api.php?action=query&titles=贝塞尔曲线&redirects=&converttitles=&prop=revisions&rvprop=content&format=xml [https://zh.wikipedia.org/wiki/Special:ApiSandbox#action=query&titles=贝塞尔曲线&redirects=&converttitles=&prop=revisions&rvprop=content&format=xml [<translate> try in ApiSandbox</translate>]]
<translate>

Result</translate>

 
<?xml version="1.0" ?> 
<api>
	<query>
		<converted>
			<c from="贝塞尔曲线" to="貝塞爾曲線" /> 
		</converted>
		<redirects>
			<r from="貝塞爾曲線" to="貝茲曲線" /> 
		</redirects>
		<pages>
			<page pageid="550623" ns="0" title="貝茲曲線">
				<revisions>
					<rev contentformat="text/x-wiki" contentmodel="wikitext" xml:space="preserve">{{noteTA|G1=Math}}
[[File:Bezier curve.svg|thumb|300px|三次方貝茲曲線]] 在[[數學]]的[[數值分析]]領域中，'''貝茲曲線'''（{{lang-en|Bézier curve}}）
是[[電腦圖形學]]中相當重要的[[參數曲線]]。更高[[維度]]的廣泛化貝茲曲線就稱作[[貝茲曲面]]，其中[[貝茲三角]]是一種特殊的實例。貝茲曲線於1962
					</rev> 
				</revisions>
			</page>
		</pages>
	</query>
</api>


标题标准化[edit | edit source]

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

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

api.php?action=query&titles=Project:articleA|article_B [https://en.wikipedia.org/wiki/Special:ApiSandbox#action=query&titles=Project:articleA%7Carticle_B [<translate> try in ApiSandbox</translate>]]
<translate>

Result</translate>

 
<api>
  <query>
    <normalized>
      <n from="Project:articleA" to="Wikipedia:ArticleA" />
      <n from="article_B" to="Article B" />
    </normalized>
    <pages>
      <page ns="4" title="Wikipedia:ArticleA" missing="" />
      <page ns="0" title="Article B" missing="" />
    </pages>
  </query>
</api>

页面是否存在[edit | edit source]

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

检查三个标题是否存在（一个不存在、一个无效、一个存在），以JSON格式返回结果：

api.php?action=query&titles=Doesntexist|Main%20Page|Talk:&format=jsonfm [https://zh.wikipedia.org/wiki/Special:ApiSandbox#action=query&titles=Doesntexist%7CMain%20Page%7CTalk:&format=jsonfm [<translate> try in ApiSandbox</translate>]]
<translate>

Result</translate>

 
{
	"query": {
		"pages": {
			"-2": {
				"ns": 0,
				"title": "Thisdoesntexist",
				"missing": ""
			},
			"-1": {
				"title": "Talk:",
				"invalid": ""
			},
			"54": {
				"pageid": 54,
				"ns": 0,
				"title": "Main Page",
			}
		}
	}
}

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

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

处理重定向[edit | edit source]

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

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

api.php?action=query&titles=Main%20page&redirects [https://en.wikipedia.org/wiki/Special:ApiSandbox#action=query&titles=Main%20page&redirects [<translate> try in ApiSandbox</translate>]]
<translate>

Result</translate>

 
<api>
  <query>
    <redirects>
      <r from="Main page" to="Main Page" />
    </redirects>
    <pages>
      <page pageid="11105676" ns="0" title="Main Page" />
    </pages>
  </query>
</api>

相同的请求，但是去掉了"redirects"参数：

api.php?action=query&titles=Main%20page [https://en.wikipedia.org/wiki/Special:ApiSandbox#action=query&titles=Main%20page [<translate> try in ApiSandbox</translate>]]
<translate>

Result</translate>

 
<api>
  <query>
    <pages>
      <page pageid="217225" ns="0" title="Main page" />
    </pages>
  </query>
</api>

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

api.php?action=query&titles=Main%20page&prop=info [https://en.wikipedia.org/wiki/Special:ApiSandbox#action=query&titles=Main%20page&prop=info [<translate> try in ApiSandbox</translate>]]
<translate>

Result</translate>

 
<api>
  <query>
    <pages>
      <page pageid="217225" ns="0" title="Main page" touched="2007-06-29T11:22:39Z" lastrevid="78280008" counter="0" length="56" redirect="" />
    </pages>
  </query>
</api>

循环重定向[edit | edit source]

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

循环重定向下的行为：

api.php?action=query&titles=page1&redirects [https://en.wikipedia.org/wiki/Special:ApiSandbox#action=query&titles=page1&redirects [<translate> try in ApiSandbox</translate>]]
<translate>

Result</translate>

 
<?xml version="1.0" encoding="utf-8"?>
<api>
  <query>
    <normalized>
      <n from="page1" to="Page1" />
    </normalized>
    <redirects>
      <r from="Page1" to="Page2" />
      <r from="Page2" to="Page3" />
      <r from="Page3" to="Page1" />
    </redirects>
  </query>
</api>

数目限制[edit | edit source]

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

后续检索[edit | edit source]

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

使用query-continue来继续检索：

api.php?action=query&list=allcategories&acprefix=List%20of [https://en.wikipedia.org/wiki/Special:ApiSandbox#action=query&list=allcategories&acprefix=List%20of [<translate> try in ApiSandbox</translate>]]
<translate>

Result</translate>

 
<?xml version="1.0" encoding="utf-8"?>
<api>
  <query-continue>
    <allcategories acfrom="List of Baptist sub-denominations" />
  </query-continue>
  <query>
    <allcategories>
      <c>List of &quot;M&quot; series military vehicles</c>
      <c>List of Alternative Rock Groups</c>
      <c>List of Alumni of Philippine Science High School</c>
      <c>List of American artists</c>
      <c>List of Anglicans and Episcopalians</c>
      <c>List of Arizona Reptiles</c>
      <c>List of Artists by record label</c>
      <c>List of Australian Anglicans</c>
      <c>List of Bahá'ís</c>
      <c>List of Balliol College people</c>
    </allcategories>
  </query>
</api>

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

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

获取页面ID的列表[edit | edit source]

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

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

api.php?action=query&titles=Main%20Page|Fksdlfsdss|Talk:&indexpageids&format=jsonfm [https://en.wikipedia.org/wiki/Special:ApiSandbox#action=query&titles=Main%20Page%7CFksdlfsdss%7CTalk:&indexpageids&format=jsonfm [<translate> try in ApiSandbox</translate>]]
<translate>

Result</translate>

 
{
	"query": {
		"pageids": [
			"-2",
			"-1",
			"15580374"
		],
		"pages": {
			"-2": {
				"ns": 0,
				"title": "Fksdlfsdss",
				"missing": ""
			},
			"-1": {
				"title": "Talk:",
				"invalid": ""
			},
			"15580374": {
				"pageid": 15580374,
				"ns": 0,
				"title": "Main Page"
			}
		}
	}
}

导出页面[edit | edit source]

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

导出API的内容：

api.php?action=query&titles=API&export&exportnowrap [https://en.wikipedia.org/wiki/Special:ApiSandbox#action=query&titles=API&export&exportnowrap [<translate> try in ApiSandbox</translate>]]
<translate>

Result</translate>

 
<!-- TODO -->

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

api.php?action=query&generator=templates&titles=API&export [https://en.wikipedia.org/wiki/Special:ApiSandbox#action=query&generator=templates&titles=API&export [<translate> try in ApiSandbox</translate>]]
<translate>

Result</translate>

 
<?xml version="1.0"?>
<api>
  <query>
    <pages>
      <page pageid="16385" ns="10" title="Template:API Intro" />
      <page pageid="6458" ns="10" title="Template:Languages" />
      <page pageid="9631" ns="10" title="Template:Languages/Lang" />
    </pages>
    <export>
      <!-- XML dump here -->
    </export>
  </query>
</api>

参见导入页面

生成器[edit | edit source]

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

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

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

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

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

api.php?action=query&generator=allpages&gaplimit=3&gapfrom=Ba&prop=links|categories [https://en.wikipedia.org/wiki/Special:ApiSandbox#action=query&generator=allpages&gaplimit=3&gapfrom=Ba&prop=links%7Ccategories [<translate> try in ApiSandbox</translate>]]
<translate>

Result</translate>

 
<?xml version="1.0" encoding="utf-8"?>
<api>
  <query-continue>
    <allpages gapfrom="Ba&#039;ad Sneen (Song)" />
  </query-continue>
  <query>
    <pages>
      <page pageid="98178" ns="0" title="Ba">
        <links>
          <pl ns="0" title="BA" />
          <pl ns="4" title="Wikipedia:Redirect" />
          <pl ns="4" title="Wikipedia:Template messages/Redirect pages" />
          <pl ns="10" title="Template:R from alternative name" />
          <pl ns="10" title="Template:R from alternative spelling" />
          <pl ns="14" title="Category:Redirects from other capitalisations" />
        </links>
        <categories>
          <cl ns="14" title="Category:Redirects from other capitalisations" />
          <cl ns="14" title="Category:Unprintworthy redirects" />
        </categories>
      </page>
      <page pageid="14977970" ns="0" title="Ba&#039;">
        <links>
          <pl ns="0" title="Kirkwall Ba game" />
        </links>
      </page>
      <page pageid="10463369" ns="0" title="Ba&#039;Gamnan">
        <links>
          <pl ns="0" title="Characters of Final Fantasy XII" />
        </links>
      </page>
    </pages>
  </query>
</api>

生成器与重定向[edit | edit source]

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

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

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

在生成器中使用重定向：

api.php?action=query&generator=links&titles=Title&prop=links&redirects [https://en.wikipedia.org/wiki/Special:ApiSandbox#action=query&generator=links&titles=Title&prop=links&redirects [<translate> try in ApiSandbox</translate>]]
<translate>

Result</translate>

 
<?xml version="1.0" encoding="utf-8"?>
<api>
  <query>
    <pages>
      <page pageid="32" ns="0" title="TitleA">
        <links>
          <pl ns="0" title="TitleA1" />
          <pl ns="0" title="TitleA2" />
          <pl ns="0" title="TitleA3" />
        </links>
      </page>
      <page pageid="54" ns="0" title="TitleC">
        <links>
          <pl ns="0" title="TitleC1" />
          <pl ns="0" title="TitleC2" />
        </links>
      </page>
    </pages>
    <redirects>
      <r from="TitleB" to="TitleC" />
    </redirects>
  </query>
</api>

更多生成器示例[edit | edit source]

显示以“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 | edit source]

  • 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的生成器导致的。
Retrieved from "https://www.mediawiki.org/w/index.php?title=API:Query/zh&oldid=1315519"