领头羊 API

先决条件¶

要使用排行榜 API，必须准备以下项目：

用于API调用的身份验证令牌（认证密钥）： Hive 控制台 > 应用中心 > 管理项目 > 游戏详情 > 基本信息 > 认证密钥
要使用的排行榜ID： Hive 控制台 > 排行榜 > 管理排名

请求 URL¶

服务器	URL
直播	api-leaderboard.withhive.com
沙盒	sandbox-api-leaderboard.withhive.com

响应代码¶

API的常见响应代码。

代码	值	描述
200	成功	-
400	错误请求	无效的 `leaderboardId` 或参数输入
401	未授权	请求消息的授权头缺失或其值无效
403	禁止	API 调用的认证令牌（认证密钥）无效
500	服务器内部错误	服务器内部出现问题

提交分数¶

在排行榜上存储分数。

请求 URL¶

实时 URL	https://api-leaderboard.withhive.com/leaderboards/{leaderboardId}/score
沙盒 URL	https://sandbox-api-leaderboard.withhive.com/leaderboards/{leaderboardId}/score
HTTP 方法	POST
内容类型	application/json

路径参数¶

字段名称	描述	类型	必需
leaderboardId	排行榜 ID	字符串	是

头部参数¶

字段名称	描述	类型	必需
授权	调用 API 的身份验证令牌（Bearer）	字符串	是

请求体¶

字段名称	描述	类型	必填
playerId	账户标识符	long	Y
score	这是要在排名中注册的分数。最多可以输入15位数字（999,999,999,999,999）。	integer	Y
achievementTimeUtc	记录分数的时间（基于UTC+0）。格式为`yyyy-MM-dd'T'HH:mm:ss.SSS`。	string	Y
extraData	这是playerid账户的附加信息（昵称、等级、国家等）。最多可以输入256个字符。	string	N

响应¶

如果是 200 OK，响应体是空的。

请求示例¶

curl --location 'https://sandbox-api-leaderboard.withhive.com/leaderboards/1/score'
 --header 'Content-Type: application/json'
 --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'
 --data '{
"playerId": 1000,
"score": 87,
"achievementTimeUtc": "2023-12-19T15:01:01.004",
"extraData": "Lv.14|User1|KR"
}'

删除分数（删除用户信息）¶

删除在排行榜上注册的用户信息。

请求 URL¶

直播 URL	https://api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/{playerId}
沙盒 URL	https://sandbox-api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/{playerId}
HTTP 方法	DELETE
内容类型	application/json

路径参数¶

字段名称	描述	类型	必需
leaderboardId	排行榜 ID	字符串	是
playerId	账户标识符	字符串	是

头部参数¶

字段名称	描述	类型	必需
Authorization	调用API的身份验证令牌（Bearer）	字符串	是

响应¶

如果是200 OK，响应体是空的。

请求示例¶

curl --location
--request DELETE 'https://sandbox-api-leaderboard.withhive.com/leaderboards/1/players/1004'
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'
--data ''

查询坦克：逐页查询¶

从顶部逐页查询排名。

请求 URL¶

实时 URL	https://api-leaderboard.withhive.com/leaderboards/{leaderboardId}/ranks
沙盒 URL	https://sandbox-api-leaderboard.withhive.com/leaderboards/{leaderboardId}/ranks
HTTP 方法	GET
内容类型	application/json

路径参数¶

字段名称	描述	类型	必需
leaderboardId	排行榜 ID	字符串	是

头部参数¶

字段名称	描述	类型	必需
授权	API 调用所需的身份验证令牌（Bearer）	字符串	是

查询参数¶

字段名称	描述	类型	必需
page	请求的页码。从1开始，默认是1。如果值为5，则仅查询第5页的内容。	整数	否
rowcount	每页显示的排名信息数量。最大100，默认是100。	整数	否
requesttimeutc	查询的基准时间（基于UTC+0）。默认是当前时间。格式为`yyyy-MM-dd'T'HH:mm:ss.SSS`。	字符串	否
playerid	如果存在playerid账户的排名信息，则查询该玩家的排名信息。	长整型	否

响应¶

字段名称	描述	类型
rankingList	排名数据列表	json 数组
rankingList[].rank	排名	整数
rankingList[].playerId	账户标识符	长整型
rankingList[].score	分数	长整型
rankingList[].achievementTimeUtc	分数注册时间（基于 UTC+0）。格式: `yyyy-MM-dd'T'HH:mm:ss.SSS`	字符串
rankingList[].extraData	账户的附加信息（昵称、等级、国家等）	字符串
playerRank	提供的 `playerid` 在查询参数中的用户排名信息（仅在查询参数中存在 `playerid` 信息时返回）	json
playerRank.rank	排名	整数
playerRank.playerId	账户标识符	长整型
playerRank.score	分数	长整型
playerRank.achievementTimeUtc	分数注册时间（基于 UTC+0），格式: `yyyy-MM-dd'T'HH:mm:ss.SSS`	字符串
playerRank.extraData	账户的附加信息（昵称、等级、国家等）	字符串

请求示例¶

curl --location 'https://sandbox-api-leaderboard.withhive.com/leaderboards/1/ranks?page=1&rowcount=100&playerid=1000&requesttimeutc=2023-12-19T15%3A01%3A01.004'
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'

响应示例¶

{
    "rankingList": [
        {
            "rank": 1,
            "playerId": 1001,
            "score": 89,
            "achievementTimeUtc": "2023-12-19T15:02:02.004",
            "extraData": "Lv.50|User1|KR"
        }, {
            "rank": 2,
            "playerId": 1000,
            "score": 87,
            "achievementTimeUtc": "2023-12-19T15:01:01.004",
            "extraData": "Lv.50|User14|KR"
        }
    ],
    "playerRank": {
        "rank": 2,
        "playerId": 1000,
        "score": 87,
        "achievementTimeUtc": "2023-12-19T15:01:01.004",
        "extraData": "Lv.50|User14|KR"
    }
}

如果在查询参数中未提供 playerid，则结果将不包括 playerRank。如果提供了，但该账户没有排名信息，则 playerRank 将以以下格式返回：

"playerRank": null

查询排名：查询特定用户排名信息¶

查询特定用户的排名信息。

请求 URL¶

实时 URL	https://api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/{playerId}/ranks
沙盒 URL	https://sandbox-api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/{playerId}/ranks
HTTP 方法	GET
内容类型	application/json

路径参数¶

字段名称	描述	类型	必需
leaderboardId	排行榜 ID	字符串	是
playerId	账户标识符	字符串	是

头部参数¶

字段名称	描述	类型	必需
授权	API 调用所需的身份验证令牌（Bearer）	字符串	Y

查询参数¶

字段名称	描述	类型	必需
requesttimeutc	查询的基准时间（基于 UTC+0），格式：`yyyy-MM-dd'T'HH:mm:ss.SSS`	字符串	否

响应¶

字段名称	描述	类型
playerRank.rank	排名	整数
playerRank.playerId	账户标识符	长整型
playerRank.score	分数	长整型
playerRank.achievementTimeUtc	分数注册时间（基于 UTC+0），格式：`yyyy-MM-dd'T'HH:mm:ss.SSS`	字符串
playerRank.extraData	账户的额外信息（昵称、等级、国家等）	字符串

请求示例¶

curl --location 'https://sandbox-api-leaderboard.withhive.com/leaderboards/1/players/1000/ranks?requesttimeutc=2023-12-19T15%3A01%3A01.004'
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'

响应示例¶

{
    "playerRank": {
        "rank": 2,
        "playerId": 1000,
        "score": 87,
        "achievementTimeUtc": "2023-12-19T15:01:01.004",
        "extraData": "Lv.50|User14|KR"
    }
}

查询排名：特定用户的排名信息¶

查询特定用户的排名信息。您可以获得特定用户周围前50名或后50名用户的排名信息。

请求 URL¶

实时 URL	https://api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/{playerId}/ranks
沙盒 URL	https://sandbox-api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/{playerId}/ranks
HTTP 方法	GET
内容类型	application/json

路径参数¶

字段名称	描述	类型	必需
leaderboardId	排行榜 ID	字符串	是
playerId	账户标识符	字符串	是

头部参数¶

字段名称	描述	类型	必需
Authorization	进行 API 调用所需的身份验证令牌 (Bearer)	字符串	Y

查询参数¶

字段名称	描述	类型	必需
nearby	`playerId` 周围的排名数量。最多 100 个。	整数	Y
requesttimeutc	查询的基准时间 (UTC+0)，格式：`yyyy-MM-dd'T'HH:mm:ss.SSS`	字符串	N

回复¶

字段名称	描述	类型
rankingList	排名数据列表	json 数组
rankingList[].rank	排名	整数
rankingList[].playerId	账户标识符	长整型
rankingList[].score	分数	长整型
rankingList[].achievementTimeUtc	分数注册时间（UTC+0），格式：`yyyy-MM-dd'T'HH:mm:ss.SSS`	字符串
rankingList[].extraData	账户的附加信息（昵称、等级、国家等）	字符串
playerRank	在路径参数中输入的 `playerid` 的用户排名信息	json
playerRank.rank	排名	整数
playerRank.playerId	账户标识符	长整型
playerRank.score	分数	长整型
playerRank.achievementTimeUtc	记录分数的时间（UTC+0），格式为 `yyyy-MM-dd'T'HH:mm:ss.SSS`	字符串
playerRank.extraData	账户的附加信息（昵称、等级、国家等）	字符串

请求示例¶

curl --location 'https://sandbox-api-leaderboard.withhive.com/leaderboards/1/players/1000/ranks?nearby=100&requesttimeutc=2023-12-19T15%3A01%3A01.004'
 --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'

响应示例¶

{
    "rankingList": [
        {
            "rank": 1,
            "playerId": 1001,
            "score": 89,
            "achievementTimeUtc": "2023-12-19T15:02:02.004",
            "extraData": "Lv.50|User1|KR"
        }, {
            "rank": 2,
            "playerId": 1000,
            "score": 87,
            "achievementTimeUtc": "2023-12-19T15:01:01.004",
            "extraData": "Lv.50|User2|KR"
        }, {
            "rank": 3,
            "playerId": 1002,
            "score": 70,
            "achievementTimeUtc": "2023-12-19T15:02:02.004",
            "extraData": "Lv.50|User3|KR"
        }
    ],
        "playerRank": {
            "rank": 2,
            "playerId": 1000,
            "score": 87,
            "achievementTimeUtc": "2023-12-19T15:01:01.004",
            "extraData": "Lv.50|User2|KR"
        }    
}

查询排行榜用户数量¶

查询在排行榜上注册的用户总数。

请求 URL¶

直播网址	https://api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/count
沙盒网址	https://sandbox-api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/count
HTTP 方法	GET
内容类型	application/json

路径参数¶

字段名称	描述	类型	必需
leaderboardId	排行榜ID	字符串	是

头部参数¶

字段名称	描述	类型	必需
授权	进行 API 调用所需的身份验证令牌 (Bearer)	字符串	Y

查询参数¶

字段名称	描述	类型	必填
requesttimeutc	查询的基准时间（UTC+0），如果未输入，则以当前时间为基础，格式：`yyyy-MM-dd'T'HH:mm:ss.SSS`	字符串	否

响应¶

字段名称	描述	类型
count	注册用户数量	整数

请求示例¶

curl --location 'https://sandbox-api-leaderboard.withhive.com/leaderboards/1/players/count?requesttimeutc=2023-12-19T15%3A01%3A01.004'
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ysjs'

响应示例¶

{
    "count": 3;
}