虎牙开放平台文档

排行榜服务能力

使用说明

该组件提供了一套完整的排行榜能力，使开发者直接使用小程序SDK就可实现一个简单的排行榜。该组件提供的接口，请通过SDK接口 [SDK接口-通用上行](/miniapp/dev/sdk/hyExt.backend.commonOperate)

通用业务状态码说明

参数名称	备注
0	成功
1	参数错误
2	调用失败
3	服务器异常
4	未登录
5	没有权限
6	操作对象不存在
7	重复操作
8	榜单不存在
9	榜单项不存在

1. 重置榜单项分数接口

1.1 接口调用说明

key参数：rankCapability.setRankItemScore

1.2 param参数，是用json格式提交

参数名称	类型	备注
rankName	string	必填，排行榜名称，只能使用数字字母及"+","-",'_', '.'，但是特殊字符不能连续使用，不能超过50个字符
rankItemKey	string	必填，字符串类型，排行榜榜单项名称，通常为用户unionId，不能超过50个字符
rankItemValue	string	选填，排行榜榜单项具体内容，大小不能超过1K
rankItemScore	long	必填，排行榜榜单项分数

1.3 HTTP响应

参数名称	类型	备注
status	int	业务状态码通用业务状态码说明
msg	string	响应描述
data	string	json格式，响应数据

1.4 data数据说明

字段名称	类型	备注
extUuid	string	小程序ID
rankName	string	排行榜名称
rankItemKey	string	排行榜榜单项名称

2.更新榜单项分数接口

2.1 接口调用说明

key参数：rankCapability.incrRankItemScore

2.2 param参数，是用json格式提交

参数名称	类型	备注
rankName	string	必填，排行榜名称，只能使用数字字母及"+","-",'_', '.'，但是特殊字符不能连续使用，不能超过50个字符
rankItemKey	string	必填，字符串类型，排行榜榜单项名称，通常为用户unionId，不能超过50个字符
rankItemValue	string	选填，排行榜榜单项具体内容，大小不能超过1K
incrScore	long	必填，增加的分数，可为负数

2.3 HTTP响应

参数名称	类型	备注
status	int	业务状态码通用业务状态码说明
msg	string	响应描述
data	string	json格式，响应数据

2.4 data数据说明

字段名称	类型	备注
extUuid	string	小程序ID
rankName	string	排行榜名称
rankItemKey	string	排行榜榜单项名称
rankItemScore	long	修改后的最新分数

3. 删除某个榜单项接口

3.1 接口调用说明

key参数：rankCapability.delRankItem

3.2 param参数，是用json格式提交

参数名称	类型	备注
rankName	string	必填，排行榜名称，只能使用数字字母及"+","-",'_', '.'，但是特殊字符不能连续使用，不能超过50个字符
rankItemKey	string	必填，字符串类型，排行榜榜单项名称，通常为用户unionId，不能超过50个字符

3.3 HTTP响应

参数名称	类型	备注
status	int	业务状态码通用业务状态码说明
msg	string	响应描述
data	string	json格式，响应数据

3.4 data数据说明

字段名称	类型	备注
extUuid	string	小程序ID
rankName	string	排行榜名称

4. 查询某个榜单项信息(排名及分数)接口

4.1 接口调用说明

key参数：rankCapability.queryRankItem

4.2 param参数，是用json格式提交

参数名称	类型	备注
rankName	string	必填，排行榜名称，只能使用数字字母及"+","-",'_', '.'，但是特殊字符不能连续使用，不能超过50个字符
rankItemKey	string	必填，字符串类型，排行榜榜单项名称，通常为用户unionId，不能超过50个字符
orderType	int	选填，是否按分数值从小到大排序, 1-从小到大 2-从大到小，默认（从大到小）

4.3 HTTP响应

参数名称	类型	备注
status	int	业务状态码通用业务状态码说明
msg	string	响应描述
data	string	json格式，响应数据

4.4 data数据说明

{
	extUuid : 字符串类型，小程序ID
	rankName : 字符串类型，排行榜名称
	rankItemInfo : {
		rankItemKey : 字符串类型，排行榜榜单项名称
		rankItemValue : 字符串类型，排行榜榜单项具体内容
		rankItemScore : 长整型，分数
		rankItemRank : 长整型，排名
	}
}

5.查询榜单排名区间接口

5.1 接口调用说明

key参数：rankCapability.queryRankRange

5.2 param参数，是用json格式提交

参数名称	类型	备注
rankName	string	必填，排行榜名称，只能使用数字字母及"+","-",'_', '.'，但是特殊字符不能连续使用，不能超过50个字符
startIndex	int	必填，排名区间起始值(含)，第一个元素 index=0
pageSize	int	选填，分页大小，最大20，默认10
orderType	bool	选填，是否按分数值从小到大排序, 1-从小到大 2-从大到小，默认（从大到小）

5.3 HTTP响应

参数名称	类型	备注
status	int	业务状态码通用业务状态码说明
msg	string	响应描述
data	string	json格式，响应数据

5.4 data数据说明

{
	extUuid : 字符串类型，小程序ID
	rankName : 字符串类型，排行榜名称
	rankSize : 长整型，榜单大小
	rankItemList : [{
		rankItemKey : 字符串类型，排行榜榜单项名称
		rankItemValue : 字符串类型，排行榜榜单项具体内容
		rankItemScore : 长整型，分数
		rankItemRank : 长整型，排名
	}]
}

6. 查询榜单大小接口

6.1 接口调用说明

key参数：rankCapability.queryRankSize

6.2 param参数，是用json格式提交

参数名称	类型	备注
rankName	string	必填，排行榜名称，只能使用数字字母及"+","-",'_', '.'，但是特殊字符不能连续使用，不能超过50个字符

6.3 HTTP响应

参数名称	类型	备注
status	int	业务状态码通用业务状态码说明
msg	string	响应描述
data	string	json格式，响应数据

6.4 data数据说明

字段名称	类型	备注
extUuid	string	小程序ID
rankName	string	排行榜名称
rankSize	long	榜单大小

7. 更新榜单项value接口

7.1 接口调用说明

key参数：rankCapability.updateRankItemValue

7.2 param参数，是用json格式提交

参数名称	类型	备注
rankName	string	必填，排行榜名称，只能使用数字字母及"+","-",'_', '.'，但是特殊字符不能连续使用，不能超过50个字符
rankItemKey	string	必填，字符串类型，排行榜榜单项名称，通常为用户unionId，不能超过50个字符
newRankItemValue	string	必填，排行榜榜单项具体内容，大小不能超过1K

7.3 HTTP响应

参数名称	类型	备注
status	int	业务状态码通用业务状态码说明
msg	string	响应描述
data	string	json格式，响应数据

7.4 data数据说明

字段名称	类型	备注
extUuid	string	小程序ID
rankName	string	排行榜名称

案例

竞技场

以竞技场小程序为例，简单说明一下排行榜能力的使用。

主播点击开始一轮，生成轮次ID（业务方自身逻辑），用轮次ID拼成该轮次的排行榜名称rankName为giftRank_轮次ID，使用for循环依次调用更新榜单项分数接口初始化榜单，将房间内各个主播添加到榜单中，其中rankItemKey设为主播unionId，rankItemValue设为由主播昵称和头像组成的json字符串，incrScore设为0。
监听该轮次中各主播的礼物消息，调用更新榜单项分数接口更新对应主播的分数，在竞技场小程序中，分数即为礼物的金豆数（1RMB=1000金豆），需要转换为金豆的原因是排行榜中score只接受长整型，不接受浮点数。
场次结束后调用查询榜单排名区间接口来获取结果
是否需要初始化榜单需要根据业务需要来确定，竞技场小程序需要初始化榜单是因为观众需要在场次开始时就看到所有房间内的成员。对于类似观众送礼价值排行榜之类的需求可以不初始化榜单，监听到送礼消息才调用更新榜单项分数接口更新对应观众的送礼金豆数。当不需要初始化榜单时，可通过判断响应中的status的值是否为8（榜单不存在）或者9（榜单项不存在）来区分特殊的错误信息，参考通用业务状态码说明。

排行榜