註冊停權通知遊戲伺服器¶

當停權使用者資訊被新註冊或變更，或停權被解除時，此 API 會將相應資料即時自動傳送到遊戲伺服器。遊戲伺服器可透過此 API 立即接收使用者停權狀態的變化，並套用到服務中。

資料傳遞時機：當停權使用者資訊被新註冊或變更時，以及停權被解除時，資料會自動傳遞到遊戲伺服器。停權解除包括管理員直接解除和停權期限到期兩種情況，這兩種情況都會將 status 作為 E 傳遞。
資料傳送單位：一次請求(Request)最多傳送 100 筆停權使用者資訊。不過，為了保證同一使用者的處理順序，系統會將使用者分成多個群組進行傳送，因此即使目標很多，也不一定總是按 100 筆填滿後傳送。請求次數和每次請求的筆數會依目標使用者的分布而不同。

若要使用此 API，請先準備可接收請求(Request)的遊戲伺服器，然後在 Hive 控制台 > 認證 > 停權 > 註冊遊戲伺服器中註冊遊戲伺服器。

遊戲伺服器實作時的注意事項

準備處理重複接收（保證冪等性）：如果網路傳送失敗，重試(Retry)邏輯會執行，因此可能會接收同一事件資料兩次以上。遊戲伺服器必須以冪等(Idempotent)方式處理，確保即使多次收到同一請求，系統狀態也能保持一致。
順序可能反轉：傳送失敗的請求會被放入重試佇列並稍後傳送，而後續請求可能不等待而先傳送。因此，如果同一使用者在短時間內連續發生「註冊 -> 變更 -> 解除」等事件，請求到達順序可能會反轉。
判斷最新狀態（比較 event_time）：由於請求到達順序可能與實際事件發生順序不同，在將接收的資料套用到遊戲伺服器之前，必須比較 event_time 欄位並判斷是否為最新狀態後再處理。詳細邏輯請參閱判斷處理順序。
必須進行遊戲伺服器狀態檢查：除停權使用者資訊外，系統還會定期傳送狀態檢查請求，用於確認遊戲伺服器是否處於可接收狀態。如果未對該請求正常回應，事件傳遞將會停止，因此請務必查看並處理遊戲伺服器狀態檢查指南。

請求 URL¶

Request URL	Hive 控制台中註冊的專案遊戲伺服器 URL（[認證 > 停權 > 註冊遊戲伺服器]）
HTTP Method	POST
Content-Type	application/json
Data Format	JSON

請求標頭¶

欄位名稱	說明	類型	必填
Authorization	用於遊戲伺服器認證的 Bearer 權杖以 `Bearer {遊戲伺服器認證金鑰}` 格式傳遞。	String	Y

Note

遊戲伺服器認證金鑰可在 Hive 控制台 [認證 > 停權 > 註冊遊戲伺服器 > 專案詳細資訊 > 遊戲伺服器認證金鑰]中查看。
遊戲伺服器認證金鑰驗證必須由接收請求的遊戲伺服器直接實作。

請求本文¶

欄位名稱	說明	類型	必填
game_index	遊戲索引	Integer	Y
server_url	遊戲伺服器 URL	String	Y
data	停權使用者清單（最多 100 筆）	List	Y
data[].event_time	發布時間（epoch 毫秒）遊戲伺服器用於判斷處理順序的值。詳情	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": "{Hive 控制台中註冊的專案遊戲伺服器 URL}",
  "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": "{Hive 控制台中註冊的專案遊戲伺服器 URL}",
  "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": "{Hive 控制台中註冊的專案遊戲伺服器 URL}",
  "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 毫秒（自 1970 年 1 月 1 日 00:00:00 UTC 起經過的毫秒數）表示。例如，1720612623847 按 KST 為 2024-07-10 20:57:03.847。值越大表示越晚發生的處理，因此遊戲伺服器可以透過比較該值，不受請求到達順序影響地判斷最新狀態。

請按 player_id 儲存最後套用的 event_time，並與新接收的值比較後按如下方式處理。

比較結果	含義	處理
接收值 > 儲存值	更晚發生的處理	套用並更新儲存值
接收值 = 儲存值	已套用處理的重新傳送	忽略（或以冪等方式重新套用）
接收值 < 儲存值	延遲到達的過去處理	忽略

使用 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 欄位只包含一筆 player_id 為 1 的 dummy 資料，如下所示。

player_id：1（實際不存在的 dummy ID）
event_time / start_date：傳送狀態檢查請求的時間
必須進行例外處理：player_id 為 1 的請求只是用於確認是否可以接收資料的信號。不得執行實際停權邏輯，並且必須從處理順序判斷對象中排除。

{
  "game_index": 539,
  "server_url": "{Hive 控制台中註冊的專案遊戲伺服器 URL}",
  "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 的失敗代碼，也會被視為正常回應。

如果狀態檢查失敗，停權使用者資訊傳遞將停止

如果連續 5 次沒有回應，或回應中沒有 result_code，該遊戲伺服器會被切換為不可用狀態。從此時起，實際停權使用者資訊將不會被傳遞。之後如果對狀態檢查請求正常回應，則會自動恢復為可用狀態並重新開始傳遞。

因此，請不要單獨過濾 player_id 為 1 的請求，而應透過與實際請求相同的路徑處理，並始終返回包含 result_code 的回應。