egret-docs-master/extension/matchvs/guide/rank
guofei 4fe0162b34 fist commit 2024-06-19 13:32:32 +08:00
..
README.md fist commit 2024-06-19 13:32:32 +08:00

README.md

为方便开发者做游戏全局排行榜Matchvs 提供了便捷的排行榜功能,主要流程为:

1.创建排行榜

2.上报用户分数

3.拉取排行榜

域名

Matchvs 环境分为测试环境alpha和 正式环境release所以在使用http接口时需要通过域名进行区分。使用正式环境需要先在官网控制台将您的游戏发布上线。

  • alpha环境域名alphavsopen.matchvs.com
  • release环境域名vsopen.matchvs.com

请求与响应格式

不同接口请求方式不同具体可查看各接口文档说明。所有接口采用统一的json返回格式

Content-Type: application/json

json包体中包含如下字段

字段 类型 是否必须 说明
statusCode int 返回结果的状态码200表示成功
desc string 返回结果的描述信息
data JsonObject/JsonArray 客户端需要的信息实体依据

响应示例:

{
  "statusCode": 200,
  "desc": "成功",
  "data": [
    {
      "createTime": "2018-10-26T15:29:09+08:00",
      "customPeriod": 0,
      "customStartTime": 0,
      "gameID": 102003,
      "historyPeriodNum": 0,
      "id": 5,
      "rankGist": "score",
      "rankNum": 0,
      "rankinglistName": "高分榜",
      "snapshotList": [
        "第一个快照"
      ],
      "sortOrder": 0,
      "updatePeriodType": 3,
      "updateRuleType": 3
    }
  ]
}

接口签名校验

除接口自有参数外每个接口的URL中都必须包含sign参数ts、seq、mode3个参数可选

  • ts为请求时间戳精确到秒。
  • seq为请求序号每次请求递增变化。
  • mode指定本次请求使用哪种签名方式。
  • sign由签名参数和签名方法计算得到的签名值。

签名校验由API网关来负责同时设置ts和seq可用于避免重复请求攻击当前支持如下两种方式签名方式:

1 普通用户类接口

1. 按照如下格式拼接出字符串:
	appKey&param1=xxx&param2=xxx&...[&seq=xxx&ts=xxx]&token
	params为参与签名的参数并按照参数名字母序升序排列
	[&seq=xxx&ts=xxx]表示如果设置了seq和tsseq和ts会参与签名计算mode参数不参与签名计算
	appKey为您在官网配置游戏所得token通过用户注册、登录请求获取
2. 计算第一步拼接好的字符串的MD5值即为sign的值。

2 管理员类接口

1. 按照如下格式拼接出字符串:
	appkey&param1=xxx&param2=xxx&...[&seq=xxx&ts=xxx]&appSecret
	params为参与签名的参数并按照参数名字母序升序排列
	[&seq=xxx&ts=xxx]表示如果设置了seq和tsseq和ts会参与签名计算mode参数不参与签名计算
	appKey和appSecret为您在官网配置游戏所得
2. 计算第一步拼接好的字符串的MD5值即为sign的值。

接口列表

说明 目前排行榜属于公测阶段提供给大家免费使用。需要注意的是公测阶段每个游戏创建排行榜上限为3个排行榜查询次数限每天5万次删除排行榜的接口限每月10次。

1 创建排行榜

接口: POST /rank/ranking_list_configs?ts=xxx&seq=xxx&mode=2&sign=xxx
  • 接口说明该接口用于创建一个指定游戏ID所属的排行榜并对这个排行榜的名称、排行依据、排名顺序和更新周期等进行相应的设置。
  • 签名方式:只支持管理员类接口签名(即mode=2)。

请求

Content-Type: application/json

请求实例

{
  "gameID": 123456,
  "rankinglistName": "liuzhihao_test",
  "rankGist": "test",
  "sortOrder": 0,
  "updatePeriodType": 0,
  "customStartTime": 0,
  "customPeriod": 0,
  "rankNum": 0,
  "historyPeriodNum": 0,
  "updateRuleType": 0
}

请求参数说明

排行依据: 排行依据是服务器进行排行的成绩名称通常为分数、等级、比赛时间等0。

排行周期: 在一定周期后排行榜重置重新开始排行。日每天24:00重置榜单每周日24:00重置榜单每月末24:00重置榜单不重置榜单

  • 如,周,第一周榜单为 小明 3 ,小红 2 ;第二周只有小红有记录,则榜单为 小红 4 。

上一周期榜单: 上个完整周期产生的榜单

  • 如,上周(周一至周天)的榜单为小明 3 ,小红 2 ;当前周截止周三 10:10 的榜单为 小红1 ,小明 1

**排名个数: ** 须指定历史周期的排名个数用户有500万而上一周期只需要保持top 100的用户。开发者可指定 0 - 全部数据n - top n 数据

分数更新规则: 取大,取小,取最新,求和;取大/小是指,当有新的分数上报时,保留一个较大/小值;取最新是指,新的分数直接覆盖掉旧的分数;求和是指将上报的分数累加。

  • 小明分3次上报分数3,1,2 ;如果取大,则第三次的排行是以 3 分进行排序取小则是1分取最新则是2分求和则是6分。
包体字段 说明 备注 是否参与签名
gameID 游戏ID 必填
rankinglistName 用户自定义排行榜名 必填,不能为空串
rankGist 用户自定义排行榜依据 必填,不能为空串
sortOrder 排名顺序(0为降序1为升序) 值默认为0
updatePeriodType 更新的周期类型: 0为自然日1为自然周2为自然月3为总4为自定义 值默认为0
customStartTime 用户自定义起始时间点为一个int64时间戳 当且仅当updatePeriodType的值为4时该字段值才有意义值默认为0
customPeriod 用户自定义周期数(分钟) 当且仅当updatePeriodType的值为4时该字段值才有意义值默认为0
rankNum 排名个数0表示全部n表示top n 值默认为0
historyPeriodNum 历史周期数0表示只保留当前周期的1表示保留当前和上一周期以此类推 值默认为0
updateRuleType 更新规则其中0为取小1为取大2为取新3为求和 值默认为0

应答

应答实例

{
  "statusCode": 200,
  "desc": "成功",
  "data": {
    "id": 9,
    "gameID": 123456,
    "rankinglistName": "liuzhihao_test",
    "rankGist": "test",
    "sortOrder": 0,
    "updatePeriodType": 0,
    "customStartTime": 0,
    "customPeriod": 0,
    "rankNum": 0,
    "historyPeriodNum": 0,
    "updateRuleType": 0,
    "createTime": "2018-10-29T11:11:54.928963767+08:00"
  }
}
  • 返回包体的 data 字段中除了id和createTime字段外其余字段均与上面 “请求参数说明” 中的字段相一致。
  • 返回包体的 statusCode200 表示接口调用成功,为 其它值 时表示接口调用失败,并会在 desc 字段中返回相应的错误信息。

2 查询排行榜的配置信息及其快照列表

接口: GET /rank/ranking_list_configs?接口自有参数列表&ts=xxx&seq=xxx&mode=xxx&sign=xxx
  • 接口说明:
该接口支持以游戏ID(gameID)和排行榜名称(rankinglistName)来查询所需的排行榜配置信息及其快照列表,例如

a. 一次性查回来1000条满足gameID为123456的排行榜配置信息以及这些排行榜对应的快照列表   

  /rank/ranking_list_configs?gameID=123456&limit=1000

b. 查询gameID为123456并且排行榜名rankinglistName为liuzhihao_test的排行榜配置信息以及其对应的快照列表   

  /rank/ranking_list_configs?gameID=123456&rankinglistName=liuzhihao_test

上面的接口示例中limit参数用于限制查询条数(偏移位固定为0)默认limit参数的值为1000。
query的查询参数 说明 备注 是否参与签名
gameID 游戏ID 必填
rankinglistName 排行榜名称
  • 签名方式:支持管理员类接口签名和普通用户类接口签名。

请求

Content-Type: application/json

应答

应答实例

{
  "statusCode": 200,
  "desc": "成功",
  "data": [
    {
      "createTime": "2018-10-29T13:41:17+08:00",
      "customPeriod": 60,
      "customStartTime": 0,
      "gameID": 102003,
      "historyPeriodNum": 1,
      "id": 14,
      "rankGist": "score",
      "rankNum": 0,
      "rankinglistName": "自定义周期榜",
      "snapshotList": [],
      "sortOrder": 0,
      "updatePeriodType": 4,
      "updateRuleType": 3
    },
    {
      "createTime": "2018-10-26T15:29:09+08:00",
      "customPeriod": 0,
      "customStartTime": 0,
      "gameID": 102003,
      "historyPeriodNum": 0,
      "id": 5,
      "rankGist": "score",
      "rankNum": 0,
      "rankinglistName": "高分榜",
      "snapshotList": [
        "第一个快照"
      ],
      "sortOrder": 0,
      "updatePeriodType": 3,
      "updateRuleType": 3
    }
  ]
}
  • 返回包体中,除了 snapshotList 字段(快照列表)、id字段和createTime字段外其余字段的含义与上面 “创建排行榜”“请求参数说明” 中的字段相一致。
  • 返回包体的 statusCode200 表示接口调用成功,为 其它值 时表示接口调用失败,并会在 desc 字段中返回相应的错误信息。

3 删除排行榜

接口: DELETE /rank/ranking_list_configs?ts=xxx&seq=xxx&mode=2&sign=xxx
  • 接口说明:该接口用于删除指定游戏、指定名称的排行榜,并清除掉相应的快照等一系列数据。
  • 签名方式:只支持管理员类接口签名。

请求

Content-Type: application/json

请求实例

{
  "gameID": 123456,
  "rankinglistName": "liuzhihao_test"
}

请求参数说明

包体字段 说明 备注 是否参与签名
gameID 游戏ID 必填
rankinglistName 排行榜名称 必填

应答

应答实例

{
  "statusCode": 200,
  "desc": "成功"
}
  • 返回包体的 statusCode200 表示接口调用成功,为 其它值 时表示接口调用失败,并会在 desc 字段中返回相应的错误信息。

4 设置快照/重置排行榜

如果游戏需要在非固定周期进行新的一轮计分,而不想清除已产生的数据。则可以为该排行榜设置一个快照,历史数据会作为快照保留,新产生数据作为新的榜单进行计算。

如,游戏有不固定周期的赛季/活动如中秋三天、国庆七天等。开发者可以在指定时间在客户端或gameServer里通过设置排行榜快照来实现固定赛季/活动。

  • 如,积分榜,设置周期为总,即不自动刷新榜单;然后开发者在中秋前一天晚上设置排行榜快照(不保留快照,重置排行榜),在中秋期间拉取的榜单,即为中秋三天里的活动排行榜。

  • 开发者可选择是否保留排行榜快照如果否则历史排行榜不会保留达到重置排行榜作用重置是指将排行榜里的玩家数据清除排行榜规则不变清除之后重新开始计算排行榜如果是则需要指定排行榜快照的名称top n 值0 为保存全部),此时服务保留的是设置快照前的排行榜数据。

    • 某游戏是在国庆分三次1-2号3-4号5-7号举行赛事每次赛事的成绩是基于之前成绩取最高分则开发者可以在1号赛事开始时设置排行榜快照选择保留快照不重置排行榜数据然后在3号设置排行榜快照选择保留快照不重置排行榜在5号、7号同样设置最后在国庆假期结束时连续三次赛事排名前三的玩家可领取奖励。
接口: POST /rank/snapshot?ts=xxx&seq=xxx&mode=2&sign=xxx
  • 接口说明该接口用于备份当前榜单数据每个排行榜的快照个数不能超过3个。
  • 签名方式:只支持管理员类接口签名(即mode=2)。

请求

Content-Type: application/json

请求实例

{
	"gameID": 102003,
	"rankName": "高分榜",
	"reset": false,
	"snapshotName": "第一个快照",
	"top": 10
}

请求参数说明

包体字段 说明 备注 是否参与签名
gameID 游戏ID 必填
rankName 用户自定义排行榜名 必填,不能为空串
reset 是否重置榜单数据,重置是指将排行榜里的玩家数据清除,排行榜规则不变,清除之后,重新开始计算排行榜 必填
snapshotName 快照名ps:空串表示不保留榜单历史数据 默认为空串
top 快照名不为空时保留榜单前top名的数据0为保存全部 值默认为0

应答

应答实例

{
  "statusCode": 200,
  "desc": "成功"
}
  • 返回包体的 statusCode200 表示接口调用成功,为 其它值 时表示接口调用失败,并会在 desc 字段中返回相应的错误信息。

5 删除快照

接口: DELETE /rank/snapshot?ts=xxx&seq=xxx&mode=2&sign=xxx
  • 接口说明:该接口用于删除排行榜快照。
  • 签名方式:只支持管理员类接口签名(即mode=2)。

请求

Content-Type: application/json

请求实例

{
	"gameID": 102003,
	"rankName": "高分榜",
	"snapshotName": "第一个快照"
}

请求参数说明

包体字段 说明 备注 是否参与签名
gameID 游戏ID 必填
rankName 用户自定义排行榜名 必填,不能为空串
snapshotName 用户自定义快照名 必填,不能为空串

应答

应答实例

{
  "statusCode": 200,
  "desc": "成功"
}
  • 返回包体的 statusCode200 表示接口调用成功,为 其它值 时表示接口调用失败,并会在 desc 字段中返回相应的错误信息。

6 上报分数

接口: PUT /rank/scores?mode=xxx
  • 接口说明:该接口用于上报玩家分数。上报成功,排行榜会立即更新排名。
  • 签名方式:支持管理员类接口签名和普通用户类接口。
  • mode为必选参数接口调用需指明签名方式。

请求

{
    "userID": 123,
    "gameID": 1000,
    "items": [
        {
            "fieldName": "金币",
            "value": 20
        }
    ]
}
字段 说明 备注 是否参与签名
userID 玩家ID 必填
gameID 游戏ID 必填
fieldName 排行依据 必填
fieldName 分数 必填

应答

{
    "statusCode": 200,
    "desc": "成功"
}
  • statusCode状态码。200表示成功其它表示失败。
  • desc描述。失败时描述失败原因。

7 查询用户排名

接口: GET /rank/grades?userID=123&gameID=100&type=0&rankName=周榜&snapshotName=周榜&period=0
  • 接口说明:该接口用于请求玩家的排行榜或者快照的排名。
  • 签名方式:支持管理员类接口签名和普通用户类接口。

请求

字段 说明 备注 是否参与签名
userID 玩家ID 必填
gameID 游戏ID 必填
type 类型取值0或者10排行榜1快照 默认为0
rankName 排行榜名称 必填
snapshotName 快照名称 type=0时必填
period 周期取值0或10当前周期1上一周期 默认为0

应答

{
    "statusCode": 200,
    "desc": "成功",
    "data": [
        {
            "userID": 1000,
            "rank": 1,
            "value": 100
        }
    ]
}
  • statusCode状态码。200表示成功其它表示失败。
  • desc描述。失败时描述失败原因。
  • data返回的数据。
说明
userID 玩家ID
rank 排名
value 分值

8 查询排行榜数据

接口: GET /rank/ranking_list?gameID=1000&rankName=周榜&period=0&top=100&pageIndex=0&pageMax=10&self=0&userID=1000
  • 接口说明:该接口用于请求排行榜数据,可指定排行榜,周期,可分页请求。
  • 签名方式:支持管理员类接口签名和普通用户类接口。

请求

字段 说明 备注 是否参与签名
userID 玩家ID 必填
gameID 游戏ID 必填
rankName 排行榜名称 必填
period 周期取值0或10当前周期1上一周期 默认值0
top 请求排行榜前n位大于0 必填
pageIndex 当前页码大于0 必填
pageMax 每页个数大于0 必填
self 是否查询自己取值0或1 默认值0

应答

{
    "statusCode": 200,
    "desc": "成功",
    "data": [
        {
            "userID": 1000,
            "rank": 1,
            "value": 100
        }
    ]
}
  • statusCode状态码。200表示成功其它表示失败。
  • desc描述。失败时描述失败原因。
  • data返回的数据。如果有请求自己的排名自己的排名为最后一个。
说明
userID 玩家ID
rank 排名
value 分值

9 查询快照数据

接口: GET /rank/snapshot?gameID=1000&rankName=周榜&snapshotName=欢度元旦&top=100&pageIndex=0&pageMax=10&self=0&userID=1000
  • 接口说明:该接口用于请求快照数据,可指定快照,周期,可分页请求。
  • 签名方式:支持管理员类接口签名和普通用户类接口。

请求

字段 说明 备注 是否参与签名
userID 玩家ID 必填
gameID 游戏ID 必填
rankName 排行榜名称 必填
snapshotName 快照名称 必填
top 请求排行榜前n位大于0 必填
pageIndex 当前页码大于0 必填
pageMax 每页个数大于0 必填
self 是否查询自己取值0或1 默认值0

应答

{
    "statusCode": 200,
    "desc": "成功",
    "data": [
        {
            "userID": 1000,
            "rank": 1,
            "value": 100
        }
    ]
}
  • statusCode状态码。200表示成功其它表示失败。
  • desc描述。失败时描述失败原因。
  • data返回的数据。如果有请求自己的排名自己的排名为最后一个。
说明
userID 玩家ID
rank 排名
value 分值