围绕osu!开发

本篇可能涉及到一些Web开发相关的知识,如果你有兴趣基于osu!的数据构建一款自己的应用,可以参考本篇!

5.1 osu! API

这是ppy在2013年7月公布的一组API。

文档:https://github.com/ppy/osu-api/wikiarrow-up-right

开始使用: 在 https://osu.ppy.sh/p/apiarrow-up-right 申请一个API KEY,信息随意填写。

限制:每分钟1200次,最高瞬时1400次。

共有的父URL:https://osu.ppy.sh/api/arrow-up-right

5.1.1谱面信息

/api/get_beatmaps

概览:返回通用的谱面信息。

URL:/api/get_beatmaps

参数:

k - api key (必须)

since - 返回在该日期之后ranked的所有谱面。必须是MySQL格式。

s - 指定一个谱面的SetID。(/s/xxxxx)

b - 指定一个谱面的Beatmap ID。(/b/xxxxx)

u - 指定一个用户名/用户数字id。

type - 指定u参数是数字id还是用户名。对于数字id,该参数值为id,而用户名则参数值为string。默认为智能识别,在纯数字用户名时可能出现问题。

m - 模式 (0 = osu!, 1 = Taiko, 2 = CtB, 3 = osu!mania). 默认返回所有模式的谱面。

a - 指定是否包括被转换的谱面(?) (0 = 不包括, 1 = 包括). 只在包含了m参数,并且不为0的情况下有效.被转换的谱面显示它们转换后的难度。默认为0。

h - 谱面哈希值。举个栗子,如果你尝试获取某个rep对应的谱面,而osr文件只包含谱面的哈希值。(例子:a5b99395a42bd55bc5eb1d2411cbdf8b). 默认情况下, 返回的谱面与Hash值无关。

limit - 返回值的数量. 默认值(同样是最大值)是500。

返回值:一个包含所有符合指定条件的、ranked谱面的JSON列表。每个难度一个列表。

5.1.2 玩家信息

/api/get_user

概览:返回用户信息。

URL:/api/get_user

参数:

k - api key (必须)

u - 指定一个用户名/用户数字id。

m - 模式(0 = osu!, 1 = Taiko, 2 = CtB, 3 = osu!mania).默认值为0。

type - 指定u参数是数字id还是用户名。对于数字id,该参数值为id,而用户名则参数值为string。默认为智能识别,在纯数字用户名时可能出现问题。

event_days - 打出最后成绩的日期(last event date),距离现在的最大天数。取值范围为1-31,默认值为1。 【实际使用时好像没有用。同时指定u参数和该参数,和直接指定u参数没有区别。单指定该参数没有返回。】

返回值: 包含用户信息的JSON列表。

5.1.3 按谱面获取成绩

/api/get_scores

概览:获取某张地图前100名的分数信息。

URL:/api/get_scores

参数:

k - api key (必须)

b - 指定一个谱面的Beatmap ID。(/b/xxxxx)(必须)

u - 指定一个要返回分数的用户名/用户数字id。

m - 模式 (0 = osu!, 1 = Taiko, 2 = CtB, 3 = osu!mania),默认为0。

mods -指定一个或者一些mod (具体枚举映射参见后文)

type - 指定u参数是数字id还是用户名。对于数字id,该参数值为id,而用户名则参数值为string。默认为智能识别,在纯数字用户名时可能出现问题。

limit - 返回值的数量. 默认值是50,最大值是100。

返回值:包含选定谱面前100分数信息的JSON列表。

5.1.4 玩家的BP

/api/get_user_best

获取指定玩家的BP

URL:/api/get_user_best

参数:

k - api key (必须)

u - 指定一个要返回分数的用户名/用户数字id。

m - 模式 (0 = osu!, 1 = Taiko, 2 = CtB, 3 = osu!mania),默认为0。

limit - 返回值的数量. 默认值是10,最大值是100。

type - 指定u参数是数字id还是用户名。对于数字id,该参数值为id,而用户名则参数值为string。默认为智能识别,在纯数字用户名时可能出现问题。

返回值:包含了指定用户的BP前10的JSON列表。

5.1.5 玩家最近的游戏记录

/api/get_user_recent

概览:获取玩家最近(24小时内)的10次游戏记录。

URL:/api/get_user_recent

参数:与获取BP一样,只不过limit的最大值是50。

返回值:包含玩家最近10次游戏记录的JSON列表。

字段与BP一致,不再赘述

5.1.6 MP房间信息

/api/get_match

概览:返回一把mp的历史记录。

URL:/api/get_match

参数: k - api key (必须)

mp - 房间id(必须)【也就是官网MP Link的参数】

返回值:包括房间信息和玩家成绩的JSON列表。

5.1.7 获取回放

/api/get_replay

概览

获取指定玩家在指定谱面的rep。

并发请求限制说明: 该请求对服务器负担较大,每分钟只允许10次查询。同样请注意该请求不是为批处理预设的。

URL:/api/get_replay

参数

k - api key (必须)

m - 模式 (0 = osu!, 1 = Taiko, 2 = CtB, 3 = osu!mania),默认为0。(必须)

b - 指定谱面id(注意!不是BeatmapSet ID,也就是说不是/s/xxxxx而是/b/xxxxx)(必须)

u - 指定玩家。(必须)

返回值:一个包含"content"值的JSON列表,该值中含有base-64加密的rep。

请注意,这段二进制数据用base-64解码后,并不是.osr文件的目录。这是LZMA流,在osu-wiki中可以参看定义:

The remaining data contains information about mouse movement and key presses in an wikipedia:LZMA stream (https://osu.ppy.sh/wiki/Osr_(file_format)#Formatarrow-up-right)

5.1.8 osu://协议

osu://mp//[]

加入某个mp房间的连接。前文搞错了一点,这个mpID和前文API用的id不同。如果存在密码,就加上密码参数。

osu://edit/[ (x,x,x,x...)]

(x为0-9的整数。) xx:xx:xxx 是某首歌的具体时间点。x,x,x,x,x 没有数量限制 ,是被选中的一些Object,例如滑条,note,转盘等。

通常用于mod,直接在编辑器中选中这些Object,按Ctrl+C复制,再复制到论坛里,就是这样的连接了。

osu://chan/#

加入osu!聊天频道的连接。(例如osu://chan/#italian)

osu://dl/

打开某个谱面的osu!Direct下载。

osu://spectate/ 围观某人。

注意:使用这些连接时,参数并不会包含<>!

举个栗子:[osu://spectate/7679162 点击围观]

将这个链接发送到osu!中任何频道(当然为了社区礼仪,建议发送到私聊或者#announce)再点击,就可以开始围观uid是7679162的人,只要他在线。也可以直接在浏览器访问osu://spectate/7679162这个链接。

5.2 osu! API v2

这是一些由kj415j45arrow-up-right新官网的web项目中arrow-up-right发掘的API,虽然随着新官网上线,但是并没有公布,功能也非常有限。

相比获取信息,API V2更有用的地方是OAuth,也就是玩家可以授权开发者的网站访问他的数据,而不需要直接输入osu!账号密码的机制。

共有的父URL:https://osu.ppy.sh/api/v2arrow-up-right

5.2.1 一次标准的鉴权+访问API流程

OAuth认证中,Client指用户和osu!官网之间的第三方网站。第三方网站可以以用户的身份访问osu!的数据,同时用户可以控制Client能访问的osu!数据内容的范围,而不至于需要向第三方网站提供密码。

如果你的项目不涉及其他玩家对你的授权,而只是你个人使用需要使用API V2返回的某些字段,也仍然需要创建Client。

你需要授权自己的Client访问自己的账户,获得Client访问账户用的access_token,进而以自己账户的身份来访问API V2;还需要编写定时任务,使用refresh_token来刷新自己的access_token。

创建OAuth Client

其中osu_session和X-CSRF-TOKEN可以在访问新官网后,在Cookie中找到。

只有第一次访问需要带osu_session,后续不需要。(这什么设定)

redirect参数指开发者服务器用于接收osu! 回调的接口,请认真填写。

返回:

请妥善保存secret和id,接下来的授权过程会用到。

引导用户授权

创建一个链接:

https://osu.ppy.sh/oauth/authorize?response_type=code&client_id={$client_id}&redirect_uri={$redirect_uri}&state={$state}&scope={$scope}

其中client_id和redirect_uri与创建Client时完全一致,state会在稍后回调时传回,而scope则可以控制Client要求访问用户内容的范围。

identify 将要求所有权限, friends.read则只能获取好友。 多个权限使用空格(%20)分割。

接受回调

用户点击后,你预先填写的地址将会收到回调:{$redirect_uri}?code={$code}&state={$state},其中code将会被用来鉴别点击了授权的用户。

至此,你已经可以使用access_token以用户的身份访问osu! API v2了。

附带Token

在请求头中添加Authorization: {$token_type} {$token}即可。

5.2.2 API V2

完整的列表参见:ppy/osu-web:/routes/web.php@line//APIarrow-up-right

网站开发者用于鉴别用户身份时,常用/me接口:

5.2.3 其他认证相关的接口

刷新Token

查询Client

返回:

修改Client

返回:

撤销Client

返回:

需要注意的是,撤销一个已经撤销的Client也会返回200,而撤销其他人的Client返回的是404而不是401。

5.3 osu!游戏更新信息接口

URL:https://osu.ppy.sh/web/check-updates.php?action=check&stream=stable40arrow-up-right

参数:stream可以切换为fallback、cutting edge(请自行抓包获取)。

返回内容:一个完整的、可直接运行的、不带本地化数据的osu! 客户端的每个文件的信息和下载地址。

如果你有一台流量充足、位于国外的服务器,可以使用此API定时爬取客户端,进而搭建客户端镜像。

最后更新于