排行榜

上报用户的排行榜积分

C2S POST /bp/leaderboard/data

S2S POST /bp/server/user/{user_id}/leaderboard/data

接口功能： 上报用户的排行榜积分。

注意

• 服务端以客户端上报的为准，不会进行累加
• 发奖励的 10 分钟内不允许更新，会报错，见下面的错误码。

请求头部参数 (Headers)：

参考接入 BytePower

• X-BytePower-Session-Token：登录后获取用户的 session。
• X-BytePower-Sign：请求体签名

请求体

• content-type: "application/json"

• 描述：用户注册所需信息

• 参数类型

  名字	类型	示例	是否必填	描述
  name	string	XXX	true	排行榜的 name
  extra	object	{}	false	用户自定义内容
  score	float64	1	true	用户在排行榜的分数

• 请求体示例：

{
  "name": "test_kill_day",
  "data": {
    "extra": {
      "name": "xx",
      "url": "ss"
    },
    "score": 90141
  }
}

响应

• HTTP 状态码：200

  描述：上报成功 响应示例：

• 参数类型

  名字	类型	示例	是否必填	描述
  name	string	XXX	true	排行榜的 name
  period	string	XXXX	true	排行榜所处的当前周期，重置后会变化
  order	string	DESC	true	排行榜排名顺序，DESC/ASC
  status	string	ok	true	都会是 ok，不会有别的值，可以暂时忽略这个字段
  elapsed_seconds	int	100	true	本期排行榜的持续时间，单位为秒
  post_time	string	2024-03-08T10:30:30.474016045+08:00	true	RFC3339 标准格式

{
  "leaderboard": [
    {
      "name": "test_kill_day",
      "period": "2024030716:2024030816",
      "order": "DESC",
      "post_time": "2024-03-07T16:23:53.12836592+08:00",
      "status": "ok",
      "elapsed_seconds": 124915
    }
  ]
}

HTTP 状态码：4xx 描述：错误 响应示例：

{
  "error": {
    "error_type": "invalid_parameter",
    "message": "xxxxx"
  }
}

error_type：

• invalid_parameter（参数错误）
• config_invalid （console 配置问题）
• leaderboard.in_reward （在领奖中）
• share_group_limit （分享次数受限）
• database （数据库和缓存错误，极少情况下会出现）
• redis_service （缓存错误，极少情况下会出现，比如缓存升级等场景）

获取排行榜信息

C2S POST /bp/leaderboard

S2S POST /bp/server/user/{user_id}/leaderboard

接口功能： 获取排行榜信息。

请求头部参数 (Headers)：

参考接入 BytePower

• X-BytePower-Session-Token：登录后获取用户的 session。
• X-BytePower-Sign：请求体签名

请求体

• content-type: "application/json"

• 描述：用户注册所需信息

• 参数类型

  名字	类型	示例	是否必填	描述
  name	string	XXX	true	排行榜的 name
  around	int	1	false	查询当前用户排名前后的用户
  from	int	1	true	最小配置 1，查询条件开始的排名
  to	int	100	true	最大为 console 配置的 size，查询条件中最后的排名，包含此排名用户

• 请求体示例：

{
  "name": "test_kill_day",
  "around": 1,
  "from": 1,
  "to": 100
}

响应

• HTTP 状态码：200

  描述：获取成功 响应示例：

• 参数类型

  名字	类型	示例	是否必填	描述
  around_data	array	[]	true	返回用户前后的排名数据
  member	string	XXXX	true	排名榜的用户 id
  score	float64	11	true	排名榜的用户的分数
  extra	object	{}	false	排名榜的用户的自定义参数，上报数据时传递的
  rank	int	1	true	排名榜的用户的排名
  rank_data	array	[]	true	按条件查询的排名数据
  name	string	XXX	true	排行榜的 name
  self_rank	int	1	true	用户自身排名
  period	string	XXXX	true	排行榜所处的当前周期，重置后会变化
  order	string	DESC	true	排行榜排名顺序，DESC/ASC
  elapsed_seconds	int	100	true	本期排行榜的持续时间，单位为秒
  request_time	string	2024-03-08T10:30:30.474016045+08:00	true	RFC3339 标准格式

{
  "leaderboard": {
    "around_data": [
      {
        "member": "UUEHQTGTFWSPI",
        "score": 9014181,
        "extra": {
          "name": "xx",
          "url": "ss"
        },
        "rank": 1
      },
      {
        "member": "UUEHQTGTFWSSS",
        "score": 9014182,
        "extra": {
          "name": "xx",
          "url": "ss"
        },
        "rank": 2
      }
    ],
    "rank_data": [
      {
        "member": "UUEHQTGTFWSPI",
        "score": 9014120,
        "extra": {
          "name": "xx",
          "url": "ss"
        },
        "rank": 1
      },
      {
        "member": "UUEHQTGTFWSSS",
        "score": 9014190,
        "extra": {
          "name": "xx",
          "url": "ss"
        },
        "rank": 2
      }
    ],
    "name": "test_kill_day",
    "self_rank": 1,
    "period": "2024030716:2024030816",
    "order": "DESC",
    "elapsed_seconds": 118867,
    "request_time": "2024-03-08T10:30:30.474016045+08:00"
  }
}

HTTP 状态码：4xx 描述：错误 响应示例：

{
  "error": {
    "error_type": "invalid_parameter",
    "message": "xxxxx"
  }
}

error_type：

• invalid_parameter（无效参数）
• config_invalid （console 配置问题）
• database （数据库和缓存错误，极少情况下会出现，比如数据库升级等场景）
• redis_service （缓存错误，极少情况下会出现，比如缓存升级等场景）