GAS 排行榜接口

基本信息

接口描述： 提供应用排行榜功能，包括查询用户关卡分数与排名、查询单关卡排行榜、更新排行榜、删除排行榜数据的操作，可在 开发者运营管理平台-应用管理-接口设置-排行榜 中管理排行数据。

接口地址： https://api.chinadlrs.com/developer/rank.php

请求方式： POST

响应格式： JSON

范围性测试

此接口暂时仅对指定的应用开放，非指定应用调用将返回错误代码 403

需要开放授权登录

此接口的查询用户关卡分数与排名、更新排行榜、删除排行榜数据等操作基于开放授权登录，需要先获取有效的 access_token
具体的获取流程请参考《GAS 开放授权登录接口说明文档》

公共参数

查询参数 (Query Parameters)

参数名	类型	必填	描述	默认值
type	number	是	操作类型（1-4）	无

查询参数

查询参数通过在接口地址后直接拼接的方式传递，地址和参数之间用 ? 分隔，多个参数之间用 & 连接。

例如操作类型为2、限制查询50条记录的接口地址为：
https://api.chinadlrs.com/developer/rank.php?type=1&size=50

请求头 (Headers)

参数名	类型	必填	描述
Content-Type	string	是	必须设置为 `application/json`

操作类型说明

1. 查询用户关卡分数与排名 (type=1)

功能描述： 查询指定用户在指定关卡的分数与当前名次。

请求体 (Body)

参数名	类型	必填	描述	示例
appid	int	是	应用唯一标识符	`1`
apptoken	string	是	加密后的应用秘钥	`"ABCDE..."`
email	string	是	用户邮箱地址	`"user@example.com"`
access_token	string	是	加密后的访问令牌	`"P5h7hs9+TzQXdkMFbcOLMUD87vzz..."`
level_id	string	是	加密后的关卡ID	`"ABCDE..."`
start_offset	int	否	名次范围起始偏移量，可为负数	`-2`
end_offset	int	否	名次范围结束偏移量，可为负数	`2`

数据加密

apptoken、access_token 和 level_id 参数是经过加密的字符串，用于验证应用权限和保护数据安全
具体的加密算法请参考《数据加密说明文档》

偏移参数说明

start_offset 与 end_offset 必须成对提供且均为整数，用于计算返回的名次区间：

区间起点：start_rank = position + start_offset，当起点早于第 1 名（含区间倒置）时按 0 返回，表示前 N 名
区间终点：end_rank = position + end_offset，超出该关卡总记录数时按总记录数返回

例如用户当前关卡名次为第 5 名，请求 start_offset: -2、end_offset: 3 时，返回 start_rank: 3、end_rank: 8。

请求示例

{
  "appid": 1,
  "email": "user@example.com",
  "apptoken": "ABCDE...",
  "access_token": "P5h7hs9+TzQXdkMFbcOLMUD87vzz...",
  "level_id": "ABCDE...", // 加密后的关卡ID
  "start_offset": -2, // 选填，需与 end_offset 同时提供
  "end_offset": 3 // 选填，需与 start_offset 同时提供
}

响应参数

参数名	类型	描述	示例
code	number	状态码	`200`
data	string	加密后的排行数据（解密后为对象）	`"U2FsdGVkX1+..."`
msg	string	响应消息	`"操作成功"`

响应数据解密

data 字段是经过加密的字符串，使用 apptoken 解密后得到 JSON 对象，字段如下：

score：当前分数
position：当前名次（从 1 开始）
start_rank：名次区间起点（提供偏移参数时返回）
end_rank：名次区间终点（提供偏移参数时返回）

2. 查询单关卡排行榜 (type=2)

功能描述： 查询指定关卡下分数最高的前 N 名用户，按分数降序排列。

查询参数 (Query Parameters)

参数名	类型	必填	描述	默认值
size	number	是	返回数量（1-100）	20

查询参数

查询参数通过在接口地址后直接拼接的方式传递，地址和参数之间用 ? 分隔，多个参数之间用 & 连接。

例如查询单关卡排行榜前 10 名的接口地址为：
https://api.chinadlrs.com/developer/rank.php?type=2&size=10

请求体 (Body)

参数名	类型	必填	描述	示例
appid	int	是	应用唯一标识符	`1`
apptoken	string	是	加密后的应用秘钥	`"ABCDE..."`
level_id	string	是	加密后的关卡ID	`"ABCDE..."`

数据加密

apptoken 和 level_id 参数是经过加密的字符串，用于验证应用权限和保护数据安全
具体的加密算法请参考《数据加密说明文档》

请求示例

{
  "appid": 1,
  "apptoken": "ABCDE...",
  "level_id": "ABCD..."
}

响应参数

参数名	类型	描述	示例
code	number	状态码	`200`
data	string	加密后的排行数据（解密后为数组）	`"U2FsdGVkX1+..."`
msg	string	响应消息	`"操作成功"`

响应数据解密

data 字段是经过加密的字符串，使用 apptoken 解密后得到按 score 降序排列的数组，元素字段如下：

uid：用户UID
name：用户名称
avatar：用户头像
score：分数

3. 更新排行榜 (type=3)

功能描述： 更新指定用户在指定关卡的分数。若该关卡已有记录，则根据 mode 参数决定累加或覆写；若不存在记录则直接新增。

查询参数 (Query Parameters)

参数名	类型	必填	描述	默认值
mode	number	否	更新模式（1-2）	`1`

更新模式

mode 参数决定更新方式：

1（默认）：累加模式，在原分数基础上累加新分数
2：覆写模式，直接设为请求的分数

请求体 (Body)

参数名	类型	必填	描述	示例
appid	int	是	应用唯一标识符	`1`
apptoken	string	是	加密后的应用秘钥	`"ABCDE..."`
email	string	是	用户邮箱地址	`"user@example.com"`
access_token	string	是	加密后的访问令牌	`"P5h7hs9+TzQXdkMFbcOLMUD87vzz..."`
level_id	string	是	加密后的关卡ID	`"the_beginning"`（解密后的内容）
score	number	是	加密后的分数	`100`（解密后的内容）

数据加密

apptoken、access_token、level_id 和 score 参数是经过加密的字符串，用于验证应用权限和保护数据安全
具体的加密算法请参考《数据加密说明文档》

请求示例

{
  "appid": 1,
  "email": "user@example.com",
  "apptoken": "ABCDE...",
  "access_token": "P5h7hs9+TzQXdkMFbcOLMUD87vzz...",
  "level_id": "ABCD...", // 加密后的关卡ID
  "score": "ABCD..." // 加密后的分数
}

响应参数

参数名	类型	描述	示例
code	number	状态码	`200`
data	null	无数据返回	`null`
msg	string	响应消息	`"操作成功"`

4. 删除排行榜数据 (type=4)

功能描述： 删除指定用户在应用内的排行榜数据。若提供 level_id 则仅删除该关卡的数据，否则删除该用户在当前应用下的全部排行榜数据。

删除范围

不提供 level_id 参数时将删除该用户在当前应用下的全部排行数据，该操作不可恢复，请谨慎操作。

请求体 (Body)

参数名	类型	必填	描述	示例
appid	int	是	应用唯一标识符	`1`
apptoken	string	是	加密后的应用秘钥	`"ABCDE..."`
email	string	是	用户邮箱地址	`"user@example.com"`
access_token	string	是	加密后的访问令牌	`"P5h7hs9+TzQXdkMFbcOLMUD87vzz..."`
level_id	string	否	加密后的关卡ID，不提供则删除该用户全部排行数据	`"the_beginning"`（解密后的内容）

数据加密

apptoken、access_token 和 level_id 参数是经过加密的字符串，用于验证应用权限和保护数据安全
具体的加密算法请参考《数据加密说明文档》

请求示例

{
  "appid": 1,
  "email": "user@example.com",
  "apptoken": "ABCDE...",
  "access_token": "P5h7hs9+TzQXdkMFbcOLMUD87vzz...",
  "level_id": "ABCD..." // 加密后的关卡ID
}

响应参数

参数名	类型	描述	示例
code	number	状态码	`200`
data	null	无数据返回	`null`
msg	string	响应消息	`"操作成功"`

成功响应示例

查询排行成功（type=1、type=2）

{
  "code": 200,
  "data": "U2FsdGVkX1+...加密后的排行数据",
  "msg": "操作成功"
}

更新/删除成功（type=3、type=4）

{
  "code": 200,
  "data": null,
  "msg": "操作成功"
}

错误响应示例

参数缺失（如缺少 email、access_token、level_id 等）

{
  "code": 400,
  "data": null,
  "msg": "参数缺失或无效"
}

偏移参数未成对提供（type=1）

{
  "code": 400,
  "data": null,
  "msg": "start_offset和end_offset必须同时提供"
}

偏移参数非整数（type=1）

{
  "code": 400,
  "data": null,
  "msg": "start_offset和end_offset必须为整数"
}

AppToken 验证失败

{
  "code": 401,
  "data": null,
  "msg": "AppToken验证失败"
}

非白名单应用调用（排行榜功能仅对指定应用开放）

{
  "code": 403,
  "data": null,
  "msg": "该接口仅限指定应用使用"
}

用户不存在

{
  "code": 404,
  "data": null,
  "msg": "用户不存在"
}

排行榜记录不存在（查询或删除时无对应记录）

{
  "code": 404,
  "data": null,
  "msg": "排行榜记录不存在"
}

size 参数超出 1-100 范围或 level_id 缺失（type=2）

{
  "code": 100,
  "data": null,
  "msg": "参数格式错误"
}

score 参数不是非负整数（type=3）

{
  "code": 400,
  "data": null,
  "msg": "参数格式错误"
}

状态码说明

状态码	描述	解决方案
200	操作成功
400	参数缺失或无效	检查 appid、apptoken、email、access_token、level_id 参数是否完整
400	type参数无效	检查 type 参数是否为 1-4
400	start_offset和end_offset必须同时提供	检查偏移参数是否成对提供
400	start_offset和end_offset必须为整数	检查偏移参数是否为整数（可为负数）
400	参数格式错误	检查 score 参数是否为非负整数
401	AppToken验证失败	检查 apptoken 是否正确
403	该接口仅限指定应用使用	排行榜功能仅对指定的应用开放
404	用户不存在	验证 email 是否正确
404	排行榜记录不存在	确认该用户在该关卡是否存在排行记录
100	参数格式错误	检查 size 参数是否在 1-100 范围内、level_id 参数是否提供
500	数据库操作错误	联系系统管理员

基本信息​

公共参数​

查询参数 (Query Parameters)​

请求头 (Headers)​

操作类型说明​

1. 查询用户关卡分数与排名 (type=1)​

2. 查询单关卡排行榜 (type=2)​

3. 更新排行榜 (type=3)​

4. 删除排行榜数据 (type=4)​

成功响应示例​

错误响应示例​

状态码说明​

基本信息

公共参数

查询参数 (Query Parameters)

请求头 (Headers)

操作类型说明

1. 查询用户关卡分数与排名 (type=1)

2. 查询单关卡排行榜 (type=2)

3. 更新排行榜 (type=3)

4. 删除排行榜数据 (type=4)

成功响应示例

错误响应示例

状态码说明