排行榜 API

先決條件¶

要使用排行榜 API，必須準備以下項目：

用於 API 調用的身份驗證令牌（證書金鑰）： Hive 控制台 > 應用中心 > 管理項目 > 遊戲詳情 > 基本信息 > 證書金鑰
要使用的排行榜 ID： Hive 控制台 > 排行榜 > 管理排名

請求網址¶

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

回應代碼¶

API 的常見響應代碼。

代碼	值	描述
200	成功	-
400	錯誤請求	無效的 `leaderboardId` 或參數輸入
401	未授權	請求消息的授權標頭缺失或其值無效
403	禁止	API 調用的身份驗證令牌（證書密鑰）無效
500	內部伺服器錯誤	伺服器內部出現問題

提交分數¶

在排行榜上存储分数。

請求 URL¶

實時網址	https://api-leaderboard.withhive.com/leaderboards/{leaderboardId}/score
沙盒網址	https://sandbox-api-leaderboard.withhive.com/leaderboards/{leaderboardId}/score
HTTP 方法	POST
內容類型	application/json

路徑參數¶

欄位名稱	描述	類型	必填
leaderboardId	排行榜 ID	字串	Y

標頭參數¶

欄位名稱	描述	類型	必填
授權	認證令牌以調用API（Bearer）	字串	Y

請求主體¶

欄位名稱	描述	類型	必填
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"
}'

刪除分數 (刪除用戶信息)¶

刪除登錄在排行榜上的用戶信息。

請求網址¶

實時網址	https://api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/{playerId}
沙盒網址	https://sandbox-api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/{playerId}
HTTP 方法	DELETE
內容類型	application/json

路徑參數¶

欄位名稱	描述	類型	必填
leaderboardId	排行榜 ID	字串	是
playerId	帳戶識別碼	字串	是

標頭參數¶

欄位名稱	描述	類型	必填
授權	用於調用 API 的身份驗證令牌 (Bearer)	字串	Y

回應¶

如果是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	字串	Y

標頭參數¶

欄位名稱	描述	類型	是否必填
授權	進行 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`	字串	N

回應¶

欄位名稱	描述	類型
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¶

直播網址	https://api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/{playerId}/ranks
沙盒網址	https://sandbox-api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/{playerId}/ranks
HTTP 方法	GET
內容類型	application/json

路徑參數¶

欄位名稱	描述	類型	必需
leaderboardId	排行榜 ID	字串	是
playerId	帳戶識別碼	字串	是

標頭參數¶

欄位名稱	描述	類型	必需
授權	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`	字串	N

回應¶

欄位名稱	描述	類型
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;
}