领头羊 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
路径参数
| 字段名称 | 描述 | 类型 | 必需 |
| 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
路径参数
| 字段名称 | 描述 | 类型 | 必需 |
| 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
路径参数
| 字段名称 | 描述 | 类型 | 必需 |
| 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 将以以下格式返回：
查询排名：查询特定用户排名信息
查询特定用户的排名信息。
请求 URL
路径参数
| 字段名称 | 描述 | 类型 | 必需 |
| 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
路径参数
| 字段名称 | 描述 | 类型 | 必需 |
| 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
路径参数
| 字段名称 | 描述 | 类型 | 必需 |
| 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'
响应示例