API:Main page/zh
MediaWiki现有三种接口：
- MediaWiki API，提供对wiki功能、数据和元数据便利的访问，本文是API的概述。
- Special:Export页面，提供将wiki内容批量导出为XML的功能，请参阅meta.wikimedia.org上的导出功能帮助。
- 标准web界面（您现在应该就正在使用），请参阅Manual:Parameters to index.php以了解使用web界面的信息。
您可能在寻找用于内部扩展的接口，它使得PHP开发者向安装的MediaWiki添加新功能。
 |
该页面是 MediaWiki API 文档的一部份 |
| Language: | English • Deutsch • español • français • Bahasa Indonesia • 日本語 • 한국어 • русский • українська • 粵語 • 中文 • 中文（台灣） |
|---|
这是一个概述性的总览，请点击右边的导航查看更详细的信息。
如果您希望监视一个MediaWiki安装，或是创建一个机器人来自动维护它，您可以使用MediaWiki的web服务API。Web服务API提供了直接、高级的方式来访问MediaWiki里的数据。客户端程序向其可以自动登录、获取数据、提交修改等。它可以支持机器人，轻量级基于web的JavaScript客户端，如导航popups和LiveRC等，普通的应用程序，如vandal fighter，或是其他网站（Toolserver上的实用程序）。
新安装的MediaWiki中，此web服务默认启用，但管理员可以把它禁用。
Contents |
[edit] 简单例子
这个URL让英文维基百科的web服务API向您传送首页的内容：
http://en.wikipedia.org/w/api.php?format=xml&action=query&titles=Main%20Page&prop=revisions&rvprop=content
用任意编程语言向这个URL发送一个HTTP GET请求（或直接在浏览器中打开这个链接），您便可得到一个XML文档，其中包含“Main Page”页面中当前的wiki代码。这就是一个能运作的web服务API。
我们来分解这个URL，以展示它如何工作。
[edit] 接入点
http://en.wikipedia.org/w/api.php
这就是接入点，就像MediaWiki的web服务API的首页。这个URL是英文维基百科的API的基础URL，就像http://en.wikipedia.org/wiki/是其网站的基础URL。
如果您写一个使用英文维基百科的程序，每一个您需要构造的URL都以这个基础URL开头。如果您在其他MediaWiki系统上操作，您需要找到它的接入点，并相应地使用那个地址。所有Wikimedia的wiki的接入点都符合这个模式：
http://en.wikipedia.org/w/api.php # 英文维基百科API http://nl.wikipedia.org/w/api.php # 荷兰语维基百科API http://commons.wikimedia.org/w/api.php # 维基共享资源API
下面我们来看看URL的查询字符串中的参数。
[edit] 格式
format=xml
这告诉Wikimedia的web服务API我们希望数据以XML格式返回。这个API支持许多输出格式，包括JSON、WDDX、XML、YAML以及PHP的原生序列化格式。
[edit] 动作
action=query
这是“动作”。MediaWiki的web服务API支持超过50种动作，并在API参考中均有说明。在这个例子中，我们使用“query”来告诉API，我们希望获取一些数据。
“query”动作是API最重要的动作之一，并有它自己更多的文档。下面只是这个例子的一些解释。
[edit] 特定于动作的参数
titles=Main%20Page
示例URL的剩余部分包含“query”动作所需的参数。这里，我们告诉web服务API我们需要关于“Main Page”这一wiki页面的信息。（%20来自空格的百分号编码）您可以一次请求多个页面：详见query文档。
prop=revisions
这个参数告诉web服务API我们对这个页面的一个特定版本感兴趣。因为我们没有指定任何版本信息，API会给我们最新版本的信息——维基百科现在正使用的首页。
rvprop=content
最后，这个参数告诉web服务API我们需要这一页面的最新版本的内容。如果我们传入rvprop=content|user，我们便能得到最新版本的内容以及创建了这一最新版本的用户的名称。
再说一次，这只是一个例子。查询在这里有更详细的解释，同时API参考列出了所有可能的动作、所有rvprop的可能取值、以及更多其他内容。
[edit] 新手上路
在您开始使用MediaWiki的web服务API之前，请阅读这些文档：
- 常见问题解答。
- 关于输入和输出格式的页面
- 关于错误和警告的页面
- 您希望访问的wiki的方针，例如（对于维基媒体基金会的wiki）我们的使用条款。这些条款在您通过web服务API访问或者编辑时也适用，如果您使用您的web浏览器一样。
更多地，您需要根据您的需求阅读。右边的菜单链接到更详细的、特定于任务的文档。同时，下面提供了一些更一般性的指引。
[edit] 标识您的客户端
当您向MediaWiki的web服务API发送HTTP请求时，请确认指定了能辨识您的客户端的User-Agent头。不要使用您的客户端库提供的默认User-Agent头，而是使用一个包含您的客户端的名称和版本号的自定义头：例如“MyCuteBot/0.1”。
在Wikimedia的wiki上，如果您没有提供User-Agent头，或者您提供了一个空的或通用的，您的请求会失败，并得到HTTP 403错误。参见我们的User-Agent方针。其他MediaWiki应用中可能也有类似的方针。
如果您在基于浏览器的JavaScript中调用API，您不会被User-Agent头影响：浏览器总会使用它自己的。当前没有为基于浏览器的客户端提供标识自己的机制。
[edit] 登录
您的客户端可能需要登录MediaWiki，例如使用它自己的用户账户。详见登录手册页面。
[edit] 让您的请求可缓存
如果您的请求获取的数据可以被缓存一段时间，您应该动手缓存它，这样您就不需要一次又一次地请求相同数据。一些客户端可能可以自己缓存数据，但对于另一些（特别是JavaScript客户端），这并不可能。
根据HTTP规范，POST请求不能被缓存。因此，当您从web服务API读取数据的时候，您应该使用GET请求，而不是POST。
另外请注意，除非URL完全一致，否则该请求不能从缓存中提供。如果您对api.php?....titles=Foo|Bar|Hello请求，并缓存了结果，下一个对api.php?....titles=Hello|Bar|Hello|Foo的请求仍不能取自缓存——即使MediaWiki返回相同的数据！
您应该尝试标准化您发送给MediaWiki的web服务的URL，使得稍微不同的用户输入不会导致您浪费时间在不需要的HTTP请求上面。您可以通过移除重复和按字母顺序排序标题来标准化页面标题列表。类似的技巧也能用于其他数据上面。
[edit] 资源列表
页面右边的菜单栏链接到的页面有更多详细的、针对特定任务的文档。这里有和整个API相关的一些链接：
- 英文维基百科上的API沙盒使得交互地尝试不同的动作更容易。
- API参考包含自动生成的所有动作和参数的描述。
- Hook into Wikipedia information using PHP and the MediaWiki API（IBM developerWorks文章，2011年5月17日）
- 用户提醒和提问的邮件列表：API邮件列表
- 低流量的仅用于发布公告的邮件列表（这里的消息也会同步发送到mediawiki-api）：mediawiki-api-announce
- 查询和提交API的bug：Bugzilla（当提交新bug时，不要忘记设置Component=API）
- 在SVN中浏览API源代码
- 当前的MediaWiki数据库结构
- 在SVN中浏览当前的数据库结构
