说明

rank_type 排行榜类型，用于区分排行榜，排行榜唯一标识

错误码

{
    ok = 0,                 -- 成功
    method_error = 1,       -- HTTP方法错误
    rank_type_error = 2,        -- 排行类型错误
    playerid_error = 3,     -- 玩家ID错误
    score_type_error = 4,   -- 分数类型错误
    updates_type_error = 5, -- 用户列表数据类型错误
    extdata_type_error = 6, -- 扩展数据类型错误
    n_type_error = 7, -- n类型错误
    with_extras_type_error = 8, -- with_extras类型错误
    start_rank_type_error = 9, -- start_rank类型错误
    end_rank_type_error = 10, -- end_rank类型错误
    updates_data_not_be_none = 11, -- 待更新的用户数据不能为空
    delete_error = 11, -- 删除失败，可能原因为未找到该玩家
    player_ids_type_error = 12, -- player_ids类型错误
    player_ids_index_type_error = 13, -- player_ids子项必须为字符串
    min_score_type_error = 14, -- min_score类型错误
    cache_num_error = 15, -- cache_num数据错误
    allow_negative_type_error = 16, -- allow_negative数据错误
    set_config_error = 17, -- 设置排行榜参数失败
    internal_error = 99,    -- 内部错误
}

接口详情

1. 设置排行榜参数

设置上榜分数下限，缓存条数，分数可否为负。

• URL: /rank/set_config
• Method: POST
• 权限: 需要认证

请求参数

参数名	位置	类型	必填	说明
rank_type	body	string	是	需要设置的排行榜
min_score	body	integer	否	上榜分数下限 默认0
max_score	body	integer	否	上榜分数上限限 默认999999
cache_num	body	integer	否	缓存数量 默认0
allow_negative	body	bool	否	是否允许分数为负数 默认false
open_min	body	bool	否	为true时min_score才生效
open_max	body	bool	否	为true时max_score才生效

请求示例

{
    "rank_type": "test_rank_type",
    "min_score": 1,
    "max_score": 1,
    "cache_num": 100,
    "allow_negative": true,
    "open_min": false,
    "open_max": false
}

响应示例

成功响应 (200 OK)

{
	"code": 0
}

2. 获取排行榜参数

• URL: /rank/get_config
• Method: POST/GET
• 权限: 需要认证

请求参数

参数名	位置	类型	必填	说明
rank_type	path	string	是	需要获取的排行榜

请求示例

{
    "rank_type": "test_rank_type"
}

响应示例

成功响应 (200 OK)

{
	"code": 0,
	"data": {
		"cache_num": 1,
		"min_score": 1,
		"allow_negative": false
	}
}

3. 直接修改用户数据

• URL: /rank/update_score_direct
• Method: POST
• 权限: 需要认证

请求参数

参数名	位置	类型	必填	说明
rank_type	body	string	是	需要获取的排行榜
player_id	body	string	是	用户唯一ID
score	body	integer	是	最新的分数
extra_data	body	string	否	额外的数据

请求示例

{
	"rank_type": "test_rank_type",
	"player_id": "1001",
	"score": 10,
	"extdata": "exercitation voluptate"
}

响应示例

成功响应 (200 OK)

{
	"score": 10,
	"code": 0
}

4. 批量直接修改用户数据

• URL: /rank/batch_update_score_direct
• Method: POST
• 权限: 需要认证

请求参数

参数名	位置	类型	必填	说明
rank_type	body	string	是	需要获取的排行榜
updates	body	list	是	集合
updates[1].player_id	body	string	是	用户唯一ID
updates[1].score	body	integer	是	最新的分数
updates[1].extra_data	body	string	否	额外的数据

请求示例

{
    "rank_type": "test_rank_type",
    "updates": [
        {
            "player_id": "Google",
            "score": 1,
            "extdata": "这里可存字符串"
        },
        {
            "player_id": "Baidu",
            "score": 1,
            "extdata": "这里可存字符串"
        }
    ]
}

响应示例

成功响应 (200 OK)

{
	"code": 0
}

5. 更新用户分数

• URL: /rank/update_score
• Method: POST
• 权限: 需要认证

请求参数

参数名	位置	类型	必填	说明
rank_type	body	string	是	需要获取的排行榜
player_id	body	string	是	用户唯一ID
delta_score	body	integer	是	分数变化量（可正可负）
extra_data	body	string	否	额外的数据

请求示例

{
	"rank_type": "test_rank_type",
	"player_id": "1001",
	"delta_score": 10,
	"extdata": "exercitation voluptate"
}

响应示例

成功响应 (200 OK)

{
    "score": 40,
    "code": 0
}

6. 批量更新用户分数

• URL: /rank/batch_update_score
• Method: POST
• 权限: 需要认证

请求参数

参数名	位置	类型	必填	说明
rank_type	body	string	是	需要获取的排行榜
updates	body	array	是	集合
updates[1].player_id	body	string	是	用户唯一ID
updates[1].delta_score	body	integer	是	分数变化量（可正可负）
updates[1].extra_data	body	string	否	额外的数据

请求示例

{
    "rank_type": "test_rank_type",
    "updates": [
        {
            "player_id": "Google",
            "delta_score": 1,
            "extdata": "这里可存字符串"
        },
        {
            "player_id": "Baidu",
            "delta_score": 1,
            "extdata": "这里可存字符串"
        }
    ]
}

响应示例

成功响应 (200 OK)

{
	"code": 0
}

7. 获取用户数据

• URL: /rank/get_player_info
• Method: POST
• 权限: 需要认证

请求参数

参数名	位置	类型	必填	说明
rank_type	body	string	是	需要获取的排行榜
player_id	body	string	是	用户唯一ID

请求示例

{
	"rank_type": "test_rank_type",
	"player_id": "1001"
}

响应示例

成功响应 (200 OK)

{
	"code": 0,
	"data": {
		"player_id": "1001",
		"rank": 1,
		"extra": "exercitation voluptate",
		"score": 432
	}
}

8. 获取排行榜前N名

• URL: /rank/get_top_n
• Method: POST
• 权限: 需要认证

请求参数

参数名	位置	类型	必填	说明
rank_type	body	string	是	需要获取的排行榜
n	body	integer	是	前N条数据
with_extras	body	bool	否	是否返回extra_data，默认true

请求示例

{
	"rank_type": "test_rank_type",
	"n": 2,
	"with_extras": true
}

响应示例

成功响应 (200 OK)

{
	"code": 0,
	"data": [
		{
			"rank": 1,
			"score": 432,
			"player_id": "1001",
			"extra": "exercitation voluptate"
		},
		{
			"rank": 2,
			"score": 1,
			"player_id": "Google",
			"extra": {}
		}
	]
}

9. 获取指定排名范围内用户

• URL: /rank/get_range
• Method: POST
• 权限: 需要认证

请求参数

参数名	位置	类型	必填	说明
rank_type	body	string	是	需要获取的排行榜
start_rank	body	integer	否	起始名次，默认1
end_rank	body	integer	否	结束名次，默认为起始名次
with_extras	body	bool	否	是否返回extra_data，默认true

请求示例

{
	"rank_type": "test_rank_type",
	"start_rank": 1,
	"end_rank": 2,
	"with_extras": true
}

响应示例

成功响应 (200 OK)

{
	"code": 0,
	"data": [
		{
			"score": 432,
			"rank": 1,
			"player_id": "1001",
			"extra": "exercitation voluptate"
		},
		{
			"score": 1,
			"rank": 2,
			"player_id": "Google",
			"extra": {}
		}
	]
}

10. 删除指定排行榜指定用户

• URL: /rank/remove_player
• Method: POST
• 权限: 需要认证

请求参数

参数名	位置	类型	必填	说明
rank_type	body	string	是	需要获取的排行榜
player_id	body	string	是	用户唯一ID

请求示例

{
	"rank_type": "test_rank_type",
	"player_id": "1001"
}

响应示例

成功响应 (200 OK)

{
	"code": 0
}

11. 批量删除指定排行榜用户

• URL: /rank/batch_remove_player
• Method: POST
• 权限: 需要认证

请求参数

参数名	位置	类型	必填	说明
rank_type	body	string	是	需要获取的排行榜
player_ids	body	list	是	用户唯一ID列表
player_ids.1	body	string	是	用户唯一ID
player_ids....	body	string	是	用户唯一ID
player_ids.n	body	string	是	用户唯一ID

请求示例

{
    "rank_type": "test_rank_type",
    "player_ids": [
        "1001",
        "1002"
    ]
}

响应示例

成功响应 (200 OK)

{
	"code": 0
}