注册封禁通知游戏服务器¶

当封禁用户信息被新注册或变更，或封禁被解除时，此 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 的响应。