ลงทะเบียนเซิร์ฟเวอร์เกมสำหรับการแจ้งเตือนการระงับการใช้งาน¶

API นี้จะส่งข้อมูลไปยังเซิร์ฟเวอร์เกมโดยอัตโนมัติแบบเรียลไทม์เมื่อมีการลงทะเบียนใหม่หรือเปลี่ยนแปลงข้อมูลผู้ใช้ที่ถูกระงับการใช้งาน หรือเมื่อมีการยกเลิกการระงับการใช้งาน เซิร์ฟเวอร์เกมจะรับการเปลี่ยนแปลงสถานะการระงับของผู้ใช้ผ่าน API นี้ได้ทันทีและนำไปใช้กับบริการ

เวลาการส่งข้อมูล: ระบบจะส่งข้อมูลไปยังเซิร์ฟเวอร์เกมโดยอัตโนมัติเมื่อมีการลงทะเบียนใหม่หรือเปลี่ยนแปลงข้อมูลผู้ใช้ที่ถูกระงับการใช้งาน และเมื่อมีการยกเลิกการระงับการใช้งาน การยกเลิกการระงับรวมทั้งกรณีที่ผู้ดูแลระบบยกเลิกโดยตรงและกรณีที่ครบกำหนดระยะเวลาการระงับ โดยทั้งสองกรณีจะส่ง status เป็น E
หน่วยการส่งข้อมูล: คำขอ(Request)หนึ่งครั้งจะส่งข้อมูลผู้ใช้ที่ถูกระงับได้สูงสุด 100 รายการ อย่างไรก็ตาม เพื่อรับประกันลำดับการประมวลผลของผู้ใช้รายเดียวกัน ระบบจะแบ่งผู้ใช้ออกเป็นหลายกลุ่มเพื่อส่งข้อมูล ดังนั้นแม้มีเป้าหมายจำนวนมาก ก็ไม่ได้หมายความว่าจะส่งครบ 100 รายการในทุกคำขอ จำนวนคำขอและจำนวนรายการต่อคำขอจะแตกต่างกันตามการกระจายตัวของผู้ใช้เป้าหมาย

หากต้องการใช้ API นี้ ให้เตรียมเซิร์ฟเวอร์เกมให้สามารถรับคำขอ(Request)ได้ก่อน จากนั้นลงทะเบียนเซิร์ฟเวอร์เกมที่ Hive Console > การยืนยันตัวตน > การระงับการใช้งาน > ลงทะเบียนเซิร์ฟเวอร์เกม

ข้อควรระวังเมื่อติดตั้งใช้งานเซิร์ฟเวอร์เกม

เตรียมรองรับการรับข้อมูลซ้ำ (รับประกัน idempotency): หากการส่งผ่านเครือข่ายล้มเหลว ระบบ retry จะทำงาน จึงอาจได้รับข้อมูลเหตุการณ์เดียวกันมากกว่าหนึ่งครั้ง เซิร์ฟเวอร์เกมต้องประมวลผลแบบ idempotent เพื่อให้สถานะของระบบยังคงสอดคล้องกันแม้ได้รับคำขอเดียวกันหลายครั้ง
ลำดับอาจสลับกันได้: คำขอที่ส่งไม่สำเร็จจะถูกเก็บไว้ในคิวสำหรับส่งซ้ำและถูกส่งในภายหลัง ในขณะที่คำขอต่อไปอาจถูกส่งก่อนโดยไม่ต้องรอ ดังนั้น หากเหตุการณ์ "ลงทะเบียน -> เปลี่ยนแปลง -> ยกเลิก" เกิดขึ้นต่อเนื่องในเวลาสั้น ๆ สำหรับผู้ใช้รายเดียวกัน ลำดับการมาถึงของคำขออาจสลับกันได้
ตรวจสอบสถานะล่าสุด (เปรียบเทียบ event_time): เนื่องจากลำดับที่คำขอมาถึงอาจแตกต่างจากลำดับเหตุการณ์จริง ต้องเปรียบเทียบฟิลด์ event_time ก่อนนำข้อมูลที่ได้รับไปใช้กับเซิร์ฟเวอร์เกมเสมอ และประมวลผลหลังจากตรวจสอบแล้วว่าเป็นสถานะล่าสุด ดูตรรกะโดยละเอียดได้ที่ ตรวจสอบลำดับการประมวลผล
จำเป็นต้องตรวจสอบสถานะเซิร์ฟเวอร์เกม: นอกจากข้อมูลผู้ใช้ที่ถูกระงับการใช้งานแล้ว ระบบจะส่งคำขอตรวจสอบสถานะเป็นระยะเพื่อตรวจสอบว่าเซิร์ฟเวอร์เกมพร้อมรับข้อมูลหรือไม่ หากไม่ตอบกลับคำขอนี้ตามปกติ การส่งเหตุการณ์จะหยุดลง โปรดตรวจสอบและรองรับคำแนะนำ การตรวจสอบสถานะเซิร์ฟเวอร์เกม

URL คำขอ¶

Request URL	URL เซิร์ฟเวอร์เกมของโปรเจ็กต์ที่ลงทะเบียนใน Hive Console ([การยืนยันตัวตน > การระงับการใช้งาน > ลงทะเบียนเซิร์ฟเวอร์เกม])
HTTP Method	POST
Content-Type	application/json
Data Format	JSON

ส่วนหัวคำขอ¶

ชื่อฟิลด์	คำอธิบาย	ประเภท	จำเป็น
Authorization	Bearer token สำหรับการยืนยันตัวตนของเซิร์ฟเวอร์เกม ส่งในรูปแบบ `Bearer {คีย์การยืนยันตัวตนเซิร์ฟเวอร์เกม}`	String	Y

Note

คุณสามารถตรวจสอบคีย์การยืนยันตัวตนเซิร์ฟเวอร์เกมได้ใน Hive Console [การยืนยันตัวตน > การระงับการใช้งาน > ลงทะเบียนเซิร์ฟเวอร์เกม > รายละเอียดโปรเจ็กต์ > คีย์การยืนยันตัวตนเซิร์ฟเวอร์เกม]
ต้องติดตั้งการตรวจสอบคีย์การยืนยันตัวตนเซิร์ฟเวอร์เกมโดยตรงบนเซิร์ฟเวอร์เกมที่รับคำขอ

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

ชื่อฟิลด์	คำอธิบาย	ประเภท	จำเป็น
game_index	ดัชนีเกม	Integer	Y
server_url	URL เซิร์ฟเวอร์เกม	String	Y
data	รายชื่อผู้ใช้ที่ถูกระงับการใช้งาน (สูงสุด 100 รายการ)	List	Y
data[].event_time	เวลาที่เผยแพร่เหตุการณ์ (epoch milliseconds) เป็นค่าที่เซิร์ฟเวอร์เกมใช้ตรวจสอบลำดับการประมวลผล รายละเอียด	Long	Y
data[].player_id	Player ID	Integer	Y
data[].status	สถานะการระงับการใช้งาน `P`: ผู้ใช้ที่ถูกระงับถาวร `B`: ผู้ใช้ที่ถูกระงับแบบมีระยะเวลา `E`: ยกเลิกการระงับการใช้งาน	String	Y
data[].start_date	วันที่เริ่มระงับการใช้งาน หาก `status` เป็น `E` ระบบจะส่งวันที่เริ่มต้นของการระงับที่ถูกยกเลิก	String	Y
data[].end_date	วันที่สิ้นสุดการระงับการใช้งาน หาก `status` เป็น `E` ระบบจะส่งวันที่สิ้นสุดของการระงับที่ถูกยกเลิก	String	Y

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

data ทั้งหมดที่อยู่ในคำขอหนึ่งครั้งจะมี status เดียวกันและ event_time เดียวกัน ระบบจะไม่ส่งสถานะที่แตกต่างกันปะปนกันในคำขอเดียว

การระงับแบบมีระยะเวลา (`B`)¶

{
  "game_index": 539,
  "server_url": "{URL เซิร์ฟเวอร์เกมของโปรเจ็กต์ที่ลงทะเบียนใน Hive Console}",
  "data": [
    {
      "event_time": 1720612623847,
      "player_id": 1,
      "status": "B",
      "start_date": "2024-07-10 20:56:59",
      "end_date": "2024-07-13 20:56:59"
    },
    {
      "event_time": 1720612623847,
      "player_id": 2,
      "status": "B",
      "start_date": "2024-07-10 20:56:59",
      "end_date": "2024-07-13 20:56:59"
    }
  ]
}

การระงับถาวร (`P`)¶

{
  "game_index": 539,
  "server_url": "{URL เซิร์ฟเวอร์เกมของโปรเจ็กต์ที่ลงทะเบียนใน Hive Console}",
  "data": [
    {
      "event_time": 1720612624215,
      "player_id": 3,
      "status": "P",
      "start_date": "2024-07-10 20:56:59",
      "end_date": "9999-12-31 00:00:00"
    },
    {
      "event_time": 1720612624215,
      "player_id": 4,
      "status": "P",
      "start_date": "2024-07-10 20:56:59",
      "end_date": "9999-12-31 00:00:00"
    }
  ]
}

ยกเลิกการระงับการใช้งาน (`E`)¶

ระบบจะส่งช่วงเวลาของการระงับที่ถูกยกเลิกตามเดิม ดังนั้น start_date และ end_date อาจแตกต่างกันตามผู้ใช้แต่ละราย

{
  "game_index": 539,
  "server_url": "{URL เซิร์ฟเวอร์เกมของโปรเจ็กต์ที่ลงทะเบียนใน Hive Console}",
  "data": [
    {
      "event_time": 1720829722391,
      "player_id": 5,
      "status": "E",
      "start_date": "2024-07-01 10:00:00",
      "end_date": "2024-07-08 10:00:00"
    },
    {
      "event_time": 1720829722391,
      "player_id": 6,
      "status": "E",
      "start_date": "2024-07-03 15:30:00",
      "end_date": "9999-12-31 00:00:00"
    }
  ]
}

ตรวจสอบลำดับการประมวลผล¶

event_time คือเวลาที่เซิร์ฟเวอร์ Hive เผยแพร่ข้อมูลนั้น แสดงเป็น epoch milliseconds (จำนวนมิลลิวินาทีที่ผ่านไปตั้งแต่ 1 มกราคม 1970 00:00:00 UTC) ตัวอย่างเช่น 1720612623847 คือ 2024-07-10 20:57:03.847 ตามเวลา KST ค่ายิ่งมากหมายถึงการประมวลผลที่เกิดภายหลัง เซิร์ฟเวอร์เกมจึงสามารถเปรียบเทียบค่านี้เพื่อตรวจสอบสถานะล่าสุดได้ ไม่ว่าคำขอจะมาถึงในลำดับใด

ให้บันทึก event_time ล่าสุดที่นำไปใช้แล้วสำหรับแต่ละ player_id จากนั้นเปรียบเทียบกับค่าที่ได้รับใหม่และประมวลผลตามตารางด้านล่าง

ผลการเปรียบเทียบ	ความหมาย	การประมวลผล
ค่าที่ได้รับ > ค่าที่บันทึกไว้	การประมวลผลที่เกิดภายหลัง	นำไปใช้และอัปเดตค่าที่บันทึกไว้
ค่าที่ได้รับ = ค่าที่บันทึกไว้	การส่งซ้ำของการประมวลผลที่นำไปใช้แล้ว	เพิกเฉย หรือประมวลผลซ้ำแบบ idempotent
ค่าที่ได้รับ < ค่าที่บันทึกไว้	การประมวลผลในอดีตที่มาถึงล่าช้า	เพิกเฉย

ข้อควรระวังเมื่อใช้ event_time

ต้องเปรียบเทียบเฉพาะผู้ใช้ที่มี player_id เดียวกันเท่านั้น ผู้ใช้ต่างกันอาจมี event_time เดียวกันได้ หากเปรียบเทียบโดยไม่แยกผู้ใช้ อาจเข้าใจผิดว่าคำขอปกติเป็นการประมวลผลในอดีตและทำให้ถูกข้ามไป
คำขอที่ส่งซ้ำจะคงเวลาการเผยแพร่ครั้งแรกไว้ ค่าไม่ได้ถูกอัปเดตเพียงเพราะเป็นการส่งซ้ำ จึงสามารถใช้ค่านี้กรองคำขอในอดีตที่มาถึงล่าช้าได้
event_time คือเวลาที่เซิร์ฟเวอร์ Hive เผยแพร่ จึงแตกต่างจากเวลาที่เซิร์ฟเวอร์เกมรับคำขอ รวมถึง start_date และ end_date ให้ใช้ event_time ไม่ใช่ start_date ในการตรวจสอบลำดับ
event_time เป็นเวลาสัมบูรณ์ที่ไม่ขึ้นกับเขตเวลา แม้เซิร์ฟเวอร์เกมและเซิร์ฟเวอร์ Hive จะใช้เขตเวลาต่างกัน ผลการตรวจสอบลำดับจะไม่เปลี่ยนแปลง

หากต้องตรวจสอบให้แน่ใจว่าค่าที่ได้รับเป็นสถานะล่าสุดหรือไม่ ให้เรียกดูสถานะปัจจุบันของผู้ใช้นั้นด้วย API ตรวจสอบผู้ใช้ที่ถูกระงับการใช้งานเกม

เนื้อหาการตอบกลับ¶

หลังจากประมวลผลคำขอสำเร็จ เซิร์ฟเวอร์เกมต้องตอบกลับในรูปแบบต่อไปนี้

ชื่อฟิลด์	คำอธิบาย	ประเภท
result_code	รหัสตอบกลับ รายละเอียด	Integer

รหัสตอบกลับ¶

ค่ารหัส	คำอธิบาย
0	สำเร็จ
ค่าอื่น	ล้มเหลว (รหัสข้อผิดพลาดที่กำหนดโดยเซิร์ฟเวอร์เกม)

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

สำเร็จ¶

{
  "result_code": 0
}

การตรวจสอบสถานะเซิร์ฟเวอร์เกม¶

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

ช่วงเวลาการส่งอาจปรับเปลี่ยนได้ตามสถานการณ์การดำเนินงาน ดังนั้นเซิร์ฟเวอร์เกมไม่ควรติดตั้งใช้งานโดยตั้งสมมติฐานว่าจะมีรอบเวลาที่แน่นอน ต้องสามารถส่งคืนการตอบกลับปกติได้เสมอไม่ว่าจะได้รับคำขอเมื่อใด

ฟิลด์ data ของคำขอตรวจสอบสถานะจะมีข้อมูล dummy เพียงหนึ่งรายการที่มี player_id เป็น 1 ดังตัวอย่างด้านล่าง

player_id: 1 (dummy ID ที่ไม่มีอยู่จริง)
event_time / start_date: เวลาที่ส่งคำขอตรวจสอบสถานะ
ต้องมีการจัดการข้อยกเว้น: คำขอที่มี player_id เป็น 1 เป็นเพียงสัญญาณสำหรับตรวจสอบว่าสามารถรับข้อมูลได้หรือไม่ ห้ามดำเนินตรรกะการระงับการใช้งานจริง และต้องแยกออกจาก การตรวจสอบลำดับการประมวลผล

{
  "game_index": 539,
  "server_url": "{URL เซิร์ฟเวอร์เกมของโปรเจ็กต์ที่ลงทะเบียนใน Hive Console}",
  "data": [
    {
      "event_time": 1720612623847,
      "player_id": 1,
      "status": "P",
      "start_date": "2024-07-10 20:57:03",
      "end_date": "9999-12-31 00:00:00"
    }
  ]
}

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

หากการตรวจสอบสถานะล้มเหลว การส่งข้อมูลผู้ใช้ที่ถูกระงับจะหยุดลง

หากไม่มีการตอบกลับ หรือมีการตอบกลับที่ไม่มี result_code ต่อเนื่องกัน 5 ครั้ง เซิร์ฟเวอร์เกมดังกล่าวจะถูกเปลี่ยนเป็นสถานะไม่พร้อมใช้งาน และตั้งแต่นั้นข้อมูลผู้ใช้ที่ถูกระงับการใช้งานจริงจะไม่ถูกส่ง หลังจากนั้น หากตอบกลับคำขอตรวจสอบสถานะตามปกติ สถานะจะกู้คืนเป็นพร้อมใช้งานโดยอัตโนมัติและการส่งข้อมูลจะกลับมาทำงานอีกครั้ง

ดังนั้นอย่าแยกกรองคำขอที่มี player_id เป็น 1 ออกต่างหาก ให้ประมวลผลผ่านเส้นทางเดียวกับคำขอจริงและส่งคืนการตอบกลับที่มี result_code เสมอ