API การจับคู่

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

ในการใช้ API การจับคู่ คุณต้องเตรียมรายการต่อไปนี้

• โทเค็นการตรวจสอบสิทธิ์สำหรับการเรียก API (Certification Key): Hive Console App Center > จัดการโครงการ > เลือกเกมของคุณจากรายการเกม > รายละเอียดเกม > ข้อมูลพื้นฐาน > Certification Key
• ดัชนีเกม (gameIndex): Hive Console App Center > จัดการโครงการ > เลือกเกมของคุณจากรายการเกม > รายละเอียดเกม > ข้อมูลพื้นฐาน > Game Index
• หมายเลขการแข่งขัน (matchId): คุณสามารถตรวจสอบสิ่งนี้เมื่อสร้างการแข่งขันใน Hive Console.

URL รากคำขอ¶

รหัสการตอบกลับทั่วไป¶

นี่คือรหัสการตอบสนอง API ที่พบบ่อย

การจับคู่คำขอ¶

เมื่อผู้ใช้แต่ละคนขอแมตช์ ให้เรียกใช้ API นี้ แมตช์ที่ตรงกับ matchId จะต้องถูกสร้างล่วงหน้าใน Hive Console.

URL ที่ร้องขอ¶

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

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

เนื้อหาคำขอ¶

การตอบกลับ¶

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

curl --location 'https://sandbox-api-match.withhive.com/gameindexes/1/matchmakings/1/request' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a' \
--data '{
   "playerId":100,
   "point": 1000
}'

ตัวอย่างการตอบกลับ¶

{
   "playerId": 100,
   "matchInfo": {
       "gameIndex": 1,
       "matchId": 1
   },
   "requestingStatus": "requested",
   "requestingInfo": {
       "requestTimeUtc": "2024-06-05T05:09:28.72",
       "point": 1000
   },
   "matchingInfo": {
       "status": "matchingInProgress"
   }
}

ตรวจสอบสถานะการจับคู่¶

ตรวจสอบสถานะของการแข่งขันที่ร้องขอ

URL ขอ¶

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

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

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

การตอบสนอง¶

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

curl --location --request GET 'https://sandbox-api-match.withhive.com/gameindexes/1/matchmakings/1/players?id=100' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a'

ตัวอย่างการตอบกลับ¶

สถานะการแข่งขันเมื่อคุณยังไม่ได้ทำการขอการแข่งขันมีดังนี้

{
   "playerId": 100,
   "matchInfo": {
       "gameIndex": 1,
       "matchId": 1
   },
   "requestingStatus": "notRequested"
}

Request Match จะส่งคืนสถานะ requested และ matchingInProgress เมื่อการจับคู่ยังคงดำเนินอยู่.

{
   "playerId": 100,
   "matchInfo": {
       "gameIndex": 1,
       "matchId": 1
   },
   "requestingStatus": "requested",
   "requestingInfo": {
       "requestTimeUtc": "2024-06-05T05:09:28.72",
       "point": 1000
   },
   "matchingInfo": {
       "status": "matchingInProgress"
   }
}

เมื่อทำการตรวจสอบสถานะคำขอหลังจากการแข่งขันเสร็จสิ้น จะส่งกลับผลลัพธ์เป็น matched หรือ timeout นี่คือสถานะที่การแข่งขันเสร็จสิ้นแล้ว แต่ยังไม่ได้รับ การเรียกกลับผลการแข่งขัน

    {
       "playerId": 100,
       "matchInfo": {
           "gameIndex": 1,
           "matchId": 1
       },
       "requestingStatus": "requested",
       "requestingInfo": {
           "requestTimeUtc": "2024-06-05T05:09:28.72",
           "point": 1000
       },
       "matchingInfo": {
           "status": "matched"
       }
   }

เมื่อการแข่งขันเสร็จสิ้น, Hive เซิร์ฟเวอร์จะส่ง การเรียกกลับผลการแข่งขัน ไปยังเซิร์ฟเวอร์ของคุณ หากเซิร์ฟเวอร์ของคุณได้รับการเรียกกลับผลการแข่งขัน, ส่งคืน HTTPStatus 200 ไปยัง Hive เซิร์ฟเวอร์, และหากคุณตรวจสอบสถานะคำขอการแข่งขันอีกครั้ง, มันจะเปลี่ยนเป็น notRequested และคีย์ matchingInfo จะถูกลบออกตามที่แสดงด้านล่าง นี่เป็นเพราะ Hive เซิร์ฟเวอร์ถือว่าคำขอการแข่งขันของคุณเสร็จสิ้นเมื่อได้รับ HTTPStatus 200 ในการตอบกลับการเรียกกลับและลบธุรกรรมคำขอการแข่งขันออก

{
   "playerId": 100,
   "matchInfo": {
       "gameIndex": 1,
       "matchId": 1
   },
   "requestingStatus": "notRequested"
}

ยกเลิกคำขอการแข่งขัน¶

ยกเลิกคำขอจับคู่ เมื่อคุณยกเลิกคำขอจับคู่ ธุรกรรมคำขอจับคู่จะถูกลบออกจาก Hive Server.

หากการแข่งขันเสร็จสิ้นหลังจาก Request Match และคุณได้รับ Match Result Callback และตอบกลับด้วย HTTPStatus 200 เซิร์ฟเวอร์ Hive จะถือว่าการแข่งขันเสร็จสิ้นและลบธุรกรรมคำขอการแข่งขัน ในสถานะนี้ แม้ว่าคุณจะเรียกเพื่อยกเลิกคำขอการแข่งขัน เนื่องจากธุรกรรมคำขอการแข่งขันได้ถูกลบไปแล้ว การดำเนินการยกเลิกจะไม่ถูกดำเนินการและจะไม่มีข้อยกเว้นใด ๆ ถูกส่งคืน

URL ที่ร้องขอ¶

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

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

การตอบกลับ¶

ถ้าเป็น 200 OK ร่างกายจะว่างเปล่า.

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

curl --location --request DELETE 'https://sandbox-api-match.withhive.com/gameindexes/1/matchmakings/1/players/100' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a'

ตัวอย่างการตอบกลับ¶

ไม่มีการตอบสนองเฉพาะหากคำขอถูกยกเลิกตามปกติ

ผลลัพธ์การจับคู่ callback¶

เมื่อการแข่งขันเสร็จสิ้น เซิร์ฟเวอร์ Hive จะส่งผลการแข่งขันไปยังเซิร์ฟเวอร์ของคุณเป็นการเรียกกลับ หากเซิร์ฟเวอร์ของคุณได้รับการเรียกกลับผลการแข่งขันโดยไม่มีปัญหา เซิร์ฟเวอร์ของคุณควรตอบสนองด้วย HttpStatus 200 โดยการลงทะเบียน URL เซิร์ฟเวอร์ที่ต้องการใน Hive Console ผลการแข่งขันจะถูกส่งไปยังที่อยู่นี้เป็นการเรียกกลับ ที่อยู่ต้องเป็น URL ที่เข้าถึงได้สาธารณะ ข้อมูล API มีดังนี้

URL การรับ Callback (Hive เซิร์ฟเวอร์ → เซิร์ฟเวอร์ของคุณ)¶

เมื่อจุดสิ้นสุด API เซิร์ฟเวอร์ของคุณถูกลงทะเบียนใน Hive Console เซิร์ฟเวอร์ Hive จะส่งผลลัพธ์การเรียกกลับไปยังจุดสิ้นสุดนี้เมื่อการจับคู่เสร็จสมบูรณ์

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

ค่าที่ส่งผ่านกับการเรียกกลับ¶

ตัวอย่างการเรียกกลับ (Hive เซิร์ฟเวอร์ → เซิร์ฟเวอร์ของคุณ)¶

curl --location 'The API endpoint of your server registered in the Hive Console.' --header 'Content-Type: application/json' --header 'X-Match-Signature: nj2YlgGTlLXcAhrl6ijSgfD71gTWokBiM8WPn72xxg8=' --data '{
   "gameIndex": 1,
   "matchId": 1,
   "matchingInfos": [
       {
           "matchingId": "1:1_2024-06-05T05:43:28.91_1",
           "privateInfos": [
               {
                   "playerId": 100,
                   "point": 1000
               },
               {
                   "playerId": 101,
                   "point": 1000
               }
           ]
       }
   ],
   "timeoutPlayerInfos": []
}'

คุณสามารถตรวจสอบความถูกต้องของผลลัพธ์การเรียกกลับโดยใช้ค่าของพารามิเตอร์ Header X-Match-Signature และกุญแจที่จะใช้ในการคำนวณอัลกอริธึมสามารถพบได้ใน Hive Console ด้านล่างเป็นตัวอย่างของโค้ด Java เพื่อรับ Signature

import java.nio.charset.StandardCharsets;
import java.util.Base64;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
public class MatchSignature {  
   private static final String HMAC_SHA_256 = "HmacSHA256";
   private static final String UTF_8 = "UTF-8";
   public String getSignature(String secret, String httpRequestBody) throws Exception {
       SecretKeySpec key = new SecretKeySpec(secret.getBytes(), HMAC_SHA_256);
       Mac mac = Mac.getInstance(HMAC_SHA_256);
       mac.init(key);
       byte[] source = httpRequestBody.getBytes(UTF_8);

       return new String(Base64.getEncoder().encode(mac.doFinal(source)), StandardCharsets.UTF_8);
   }
}

หากการเรียกกลับที่ส่งจากเซิร์ฟเวอร์ Hive ถูกส่งไปยังสำเร็จ คุณควรส่งสถานะ HTTP 200 กลับเป็นการตอบสนอง

• การตอบกลับด้วย HttpStatus 200: ถือว่าการแข่งขันเสร็จสมบูรณ์อย่างสำเร็จ ดังนั้นคำขอการแข่งขันจะถูกยกเลิก
• การตอบกลับด้วยค่าที่ไม่ใช่ HttpStatus 200 หรือ Timeout: การตอบกลับผลการแข่งขันจะถูกส่งซ้ำในระยะเวลาปกติ

หากเซิร์ฟเวอร์ Hive ไม่สามารถรับการตอบสนองสถานะ HTTP 200 ติดต่อกันได้ ผลลัพธ์การจับคู่จะไม่ถูกส่งกลับเป็นระยะเวลาหนึ่งเพื่อวัตถุประสงค์ในการจัดการระบบ