API กระดานผู้นำ

ข้อกำหนดเบื้องต้น¶

ในการใช้ API ของ Leaderboard จำเป็นต้องเตรียมรายการต่อไปนี้:

โทเค็นการตรวจสอบสิทธิ์ (คีย์รับรอง) สำหรับการเรียก 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	รหัสลีดเดอร์บอร์ด	สตริง	ใช่

พารามิเตอร์หัวเรื่อง¶

ชื่อฟิลด์	คำอธิบาย	ประเภท	จำเป็น
Authorization	โทเค็นการตรวจสอบสิทธิ์สำหรับการเรียก API (Bearer)	string	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"
}'

ลบคะแนน (ลบข้อมูลผู้ใช้)¶

ลบข้อมูลผู้ใช้ที่ลงทะเบียนในกระดานคะแนน

URL การร้องขอ¶

ลิงก์สด	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 ของกระดานคะแนน	string	Y
playerId	ตัวระบุบัญชี	string	Y

พารามิเตอร์ส่วนหัว¶

ชื่อฟิลด์	คำอธิบาย	ประเภท	จำเป็น
Authorization	โทเค็นการตรวจสอบสิทธิ์สำหรับการเรียก API (Bearer)	string	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 ที่ร้องขอ¶

ลิงก์สด	https://api-leaderboard.withhive.com/leaderboards/{leaderboardId}/ranks
ลิงก์แซนด์บ็อกซ์	https://sandbox-api-leaderboard.withhive.com/leaderboards/{leaderboardId}/ranks
วิธีการ HTTP	GET
ประเภทเนื้อหา	application/json

พารามิเตอร์เส้นทาง¶

ชื่อฟิลด์	คำอธิบาย	ประเภท	จำเป็น
leaderboardId	รหัสลีดเดอร์บอร์ด	สตริง	ใช่

พารามิเตอร์หัว¶

ชื่อฟิลด์	คำอธิบาย	ประเภท	จำเป็น
Authorization	โทเค็นการตรวจสอบสิทธิ์ที่จำเป็นสำหรับการเรียก API (Bearer)	string	Y

พารามิเตอร์การค้นหา¶

ชื่อฟิลด์	คำอธิบาย	ประเภท	จำเป็น
page	หมายเลขหน้าที่ร้องขอ เริ่มจาก 1 ค่าเริ่มต้นคือ 1 หากค่าเป็น 5 จะมีการสอบถามเฉพาะเนื้อหาของหน้าที่ 5	จำนวนเต็ม	ไม่
rowcount	จำนวนข้อมูลการจัดอันดับที่จะแสดงต่อหน้า สูงสุด 100 ค่าเริ่มต้นคือ 100	จำนวนเต็ม	ไม่
requesttimeutc	เวลาพื้นฐานสำหรับการสอบถาม (ตาม UTC+0) ค่าเริ่มต้นคือเวลาปัจจุบัน รูปแบบคือ `yyyy-MM-dd'T'HH:mm:ss.SSS`	สตริง	ไม่
playerid	หากมีข้อมูลการจัดอันดับสำหรับบัญชี playerid จะมีการสอบถามข้อมูลการจัดอันดับของผู้เล่นนั้นด้วย	ยาว	ไม่

การตอบกลับ¶

ชื่อฟิลด์	คำอธิบาย	ประเภท
rankingList	รายการข้อมูลการจัดอันดับ	json array
rankingList[].rank	อันดับ	integer
rankingList[].playerId	ตัวระบุบัญชี	long
rankingList[].score	คะแนน	long
rankingList[].achievementTimeUtc	เวลาที่คะแนนถูกบันทึก (ตาม UTC+0). รูปแบบ: `yyyy-MM-dd'T'HH:mm:ss.SSS`	string
rankingList[].extraData	ข้อมูลเพิ่มเติมของบัญชี playerid (ชื่อเล่น, ระดับ, ประเทศ, ฯลฯ)	string
playerRank	ข้อมูลการจัดอันดับของผู้ใช้ที่มี `playerid` ที่ระบุใน Query Parameter (จะถูกส่งคืนเฉพาะเมื่อมีข้อมูล `playerid` ใน Query Parameter)	json
playerRank.rank	อันดับ	integer
playerRank.playerId	ตัวระบุบัญชี	long
playerRank.score	คะแนน	long
playerRank.achievementTimeUtc	เวลาที่คะแนนถูกบันทึก (ตาม UTC+0), รูปแบบ: `yyyy-MM-dd'T'HH:mm:ss.SSS`	string
playerRank.extraData	ข้อมูลเพิ่มเติมของบัญชี playerid (ชื่อเล่น, ระดับ, ประเทศ, ฯลฯ)	string

ตัวอย่างคำขอ¶

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	รหัสกระดานคะแนน	string	Y
playerId	รหัสบัญชี	string	Y

พารามิเตอร์หัวเรื่อง¶

ชื่อฟิลด์	คำอธิบาย	ประเภท	จำเป็น
Authorization	โทเค็นการตรวจสอบสิทธิ์ที่จำเป็นสำหรับการเรียก API (Bearer)	string	Y

พารามิเตอร์การค้นหา¶

ชื่อฟิลด์	คำอธิบาย	ประเภท	จำเป็น
requesttimeutc	เวลาพื้นฐานสำหรับการสอบถาม (ตาม UTC+0), รูปแบบ: `yyyy-MM-dd'T'HH:mm:ss.SSS`	สตริง	N

การตอบกลับ¶

ชื่อฟิลด์	คำอธิบาย	ประเภท
playerRank.rank	อันดับ	integer
playerRank.playerId	รหัสประจำตัวบัญชี	long
playerRank.score	คะแนน	long
playerRank.achievementTimeUtc	เวลาที่คะแนนถูกบันทึก (ตาม UTC+0), รูปแบบ: `yyyy-MM-dd'T'HH:mm:ss.SSS`	string
playerRank.extraData	ข้อมูลเพิ่มเติมของบัญชี playerid (ชื่อเล่น, ระดับ, ประเทศ, ฯลฯ)	string

ตัวอย่างคำขอ¶

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
ลิงก์ Sandbox	https://sandbox-api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/{playerId}/ranks
วิธีการ HTTP	GET
ประเภทเนื้อหา	application/json

พารามิเตอร์เส้นทาง¶

ชื่อฟิลด์	คำอธิบาย	ประเภท	จำเป็น
leaderboardId	รหัสลีดเดอร์บอร์ด	string	Y
playerId	ตัวระบุบัญชี	string	Y

พารามิเตอร์หัวเรื่อง¶

ชื่อฟิลด์	คำอธิบาย	ประเภท	จำเป็น
Authorization	โทเค็นการตรวจสอบสิทธิ์ที่จำเป็นสำหรับการเรียก API (Bearer)	string	Y

พารามิเตอร์การค้นหา¶

ชื่อฟิลด์	คำอธิบาย	ประเภท	จำเป็น
nearby	จำนวนอันดับรอบๆ `playerId` สูงสุด 100	integer	Y
requesttimeutc	เวลาพื้นฐานสำหรับการสอบถาม (UTC+0), รูปแบบ: `yyyy-MM-dd'T'HH:mm:ss.SSS`	string	N

การตอบกลับ¶

ชื่อฟิลด์	คำอธิบาย	ประเภท
rankingList	รายการข้อมูลการจัดอันดับ	json array
rankingList[].rank	อันดับ	integer
rankingList[].playerId	รหัสบัญชี	long
rankingList[].score	คะแนน	long
rankingList[].achievementTimeUtc	เวลาที่คะแนนถูกบันทึก (UTC+0), รูปแบบ: `yyyy-MM-dd'T'HH:mm:ss.SSS`	string
rankingList[].extraData	ข้อมูลเพิ่มเติมของบัญชี playerid (ชื่อเล่น, ระดับ, ประเทศ, ฯลฯ)	string
playerRank	ข้อมูลการจัดอันดับผู้ใช้สำหรับ `playerid` ที่ป้อนในพารามิเตอร์เส้นทาง	json
playerRank.rank	อันดับ	integer
playerRank.playerId	รหัสบัญชี	long
playerRank.score	คะแนน	long
playerRank.achievementTimeUtc	เวลาที่คะแนนถูกบันทึก (ใน UTC+0), ในรูปแบบ `yyyy-MM-dd'T'HH:mm:ss.SSS`	string
playerRank.extraData	ข้อมูลเพิ่มเติมของบัญชี playerid (ชื่อเล่น, ระดับ, ประเทศ, ฯลฯ)	string

ตัวอย่างคำขอ¶

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
ลิงก์ Sandbox	https://sandbox-api-leaderboard.withhive.com/leaderboards/{leaderboardId}/players/count
วิธีการ HTTP	GET
ประเภทเนื้อหา	application/json

พารามิเตอร์เส้นทาง¶

ชื่อฟิลด์	คำอธิบาย	ประเภท	จำเป็น
leaderboardId	รหัสลีดเดอร์บอร์ด	สตริง	ใช่

พารามิเตอร์หัว¶

ชื่อฟิลด์	คำอธิบาย	ประเภท	จำเป็น
Authorization	โทเค็นการตรวจสอบสิทธิ์ที่จำเป็นสำหรับการเรียก API (Bearer)	string	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;
}