NanBox

维基百科 MediaWiki API 解析

使用开放的 API 做一个自己的小项目,是一个很好的学习方法。但好像开放的 API 选择并不多。这里给大家多一个选择,简单介绍一下维基百科使用的 MediaWiki API。

简介

先简单介绍几个容易混淆的概念。

Wiki

Wiki 是一种在网络上开放且可供多人协同创作的超文本系统。Wiki 站点可以由多人维护,不同人可以对同一个主题进行拓展和探讨。

MediaWiki

MediaWiki 是一个免费、开放的 Wiki 引擎,很多著名的 wiki 网站都采用这套系统。

Wikipedia

我们常说的维基百科,一般是指 Wikipedia,它是基于 MediaWiki 的一个网络百科全书。

但要理解的是,除了 Wikipedia,还有很多别的 Wiki 站点。从这个角度考虑的话,维基(Wiki)也有可能是指别的网站,不过 Wikipedia 太出名了,以至于很多人直接将 Wikipedia 等同于 Wiki。

文档

在了解到维基百科的 API 是开放的之后,我就找到了官方的 API 文档,但以我目前的水平,这个文档几乎完全看不懂。在网上找了很久,希望可以有一篇文章以中文看得懂的方式,告诉我这些 API 是怎么用的,但很可惜并没有。

没办法,自己对着官方文档琢磨了很久,勉强总结出一些比较常用的调用方法。希望本文可以让你对 MediaWiki 的内容获取有一个大概的了解,让你能用它做出自己的项目。

本文所有内容都来自以下官方文档,如果能看懂,就不用再往下看啦。

MediaWiki API

Wikipedia API

为了方便理解,下面的说明都会有例子,用的是「灰机wiki」的「冰与火之歌中文维基」站点,域名是 asoiaf.huijiwiki.com,并通过 api.php 访问。当然,只要是基于 MediaWiki 的 Wiki 站点,下面说明都是适用的。

action

接口中的 action 用来指定请求相应的动作,他的可取值非常非常多。我们这里只考虑内容的获取,不进行用户管理、内容编辑等操作,所以只要知道一个值就行了,所有接口都是 action = query。query 就是代表获取数据。

format

这个用来指定数据返回的格式,我们统一用 JSON 格式,即 format = json。

但我在使用过程中发现,返回的 JSON 数据很多都是用「*」号或者是数字作为字段名的,解析起来很麻烦。这种情况下可以尝试增加 formatversion = 2,让返回的数据更正常一些,便于解析。

list

在 action = query 的情况下,会增加一些可用的参数,其中 list 是比较常用的一个。list 的可选值也很多,下面是几个我认为比较常用的值。

allcategories

在对一个站点还不是很了解的情况下,我们可以先看一下它有哪些分类。list = allcategories 代表列举出所有分类:

http://asoiaf.huijiwiki.com/api.php?action=query&format=json&formatversion=2&list=allcategories&aclimit=50

其中,aclimit 指定了返回的条目数量,默认值是 10,不能超过 500。

当数据存在下一页的时候,返回的数据里会有 continue 字段,比如:

1
2
3
4
continue: {
accontinue: "Castle_Black",
continue: "-||"
}

要获取下一页,把 accontinue 这个参数带上就行:

http://asoiaf.huijiwiki.com/api.php?action=query&format=json&formatversion=2&list=allcategories&aclimit=50&accontinue=Castle_Black

categorymembers

现在我们知道有哪些分类了,接下来想看一下某个分类下有哪些内容,就要用到 categorymembers,它用于列出指定分类中的所有页面。分类名传入 cmtitle,需要包括「Category:」这个前缀。

假如我想看一下「史塔克家族」有哪些页面:

http://asoiaf.huijiwiki.com/api.php?action=query&format=json&formatversion=2&list=categorymembers&cmtitle=Category:史塔克家族&cmlimit=50

这里控制返回数量的是 cmlimit,获取下一页的是 cmcontinue。

random

要是我想给用户一种新鲜感,每次在首页随机展示一些内容,list = random 是你需要的,它用于随机返回一些内容:

http://asoiaf.huijiwiki.com/api.php?action=query&format=json&formatversion=2&list=random&rnlimit=50&rnnamespace=0

rnlimit 控制返回的数量,默认是 1。同理,获取下一页要用 rncontinue。后面也是类似的。

这里还有一个命名空间 NameSpace 的概念。当 rncontinue = 0 代表指定返回的是页面,rncontinue = 6 是文件,rncontinue = 14 是分类,别的我还没有用到过。

搜索功能肯定是少不了的,我们用 list = search,将关键字传给 srsearch 进行搜索。

搜索含有「史塔克」的页面:

http://asoiaf.huijiwiki.com/api.php?action=query&format=json&formatversion=2&list=search&srsearch=史塔克&srnamespace=0&srlimit=10

目前我用到的 list 取值就这些。下面讲一下另一个重要的参数。

prop

如果是要获取某个页面的相关数据,就涉及到 prop 这个参数。它用来指定要获取的数据类型,它的可选值也很多,下面也挑几个常用的说。

categories

这个用来获取页面所属的所有分类,比如艾德·史塔克属于史塔克家族,也属于国王之手:

http://asoiaf.huijiwiki.com/api.php?action=query&format=json&formatversion=2&prop=categories&titles=艾德·史塔克&cllimit=20

images

除了文字描述,图片也是内容里的一个重要信息,prop = images 用来获取指定页面的所有文件。虽然是 image,但是它能获取到各种文件,包括视频:

http://asoiaf.huijiwiki.com/api.php?action=query&format=json&formatversion=2&prop=images&titles=艾德·史塔克&imlimit=50

pageimages

prop = pageimages 也是用来获取页面图片的,按我的理解,它是用来获取页面封面的。比如我们获取「艾德·史塔克」的封面:

http://asoiaf.huijiwiki.com/api.php?action=query&format=json&formatversion=2&prop=pageimages&titles=艾德·史塔克&pithumbsize=500

pithumbsize 用来指定图片的尺寸,默认只有 50 px。另外要注意,不是每个页面都是有封面的。

revisions

接下来是最重要的获取页面内容了。revisions 文档解释是用来获取修订版本信息的,可以用来获取最新的页面数据。

我这样来获取「艾德·史塔克」的页面数据:

http://asoiaf.huijiwiki.com/api.php?action=query&format=json&formatversion=2&prop=revisions&titles=艾德·史塔克&rvprop=content&rvparse=true

rvprop = content 表示需要返回页面的文本内容。rvparse = true 表示将文本内容解析为 html,否则是纯文本内容。

除了 content,rvprop 还有很多可选值,同时需要多种内容,可以用「|」分隔。比如同时返回修订时间戳、修订的用户及修订内容,可以这样表示:rvprop=timestamp|user|content。

其实很多参数的取值都是支持使用「|」的,将多条数据一起返回。比如我们将上面提到的 prop 取值一次全部获取到,可以这样调用:

http://asoiaf.huijiwiki.com/api.php?action=query&format=json&formatversion=2&prop=categories|images|pageimages|revisions&titles=艾德·史塔克&rvprop=timestamp|user|content&rvparse=true

总结

上面介绍的这些只能算是接触到 MediaWiki API 的一点皮毛而已,但我还是花了些时间才总结出来的。想要有很深入的了解,还是要去研究一下官方文档。

我用冰与火中文维基的接口写了一个 Android App,叫「冰与火维基」,但还有一些没优化好的地方,感兴趣的可以在这里下载到。