# **服务端接口**

下面是排行榜相关的服务端接口。 开发者可以自行编写程序或脚本调用这些接口在服务端进行管理性质的操作。

## **请求格式**

请求的主体必须是 JSON 格式，而且 HTTP Header 的 Content-Type 需要设置为 application/json。

请求的鉴权是通过 HTTP Header 里面包含的键值对来进行的，参数如下表：

| Key   | Value         | 含义             | 来源          |
| :---- | :------------ | :------------- | :---------- |
| G-Id  | {{gamekey}}   | 当前游戏的gamekey   |             |
| G-Key | {{masterkey}} | 当前游戏的masterkey | 向SDK 对接人员获取 |

## **接口域名**

<http://archive.4399api.com/>

下文 curl 示例中用 {{host}} 表示

## **管理成绩**

### **查询成绩**

接口参数：

| 参数          | 类型     | 描述                              |
| :---------- | :----- | :------------------------------ |
| ranking\_id | string | 排行榜ID（必填）                       |
| server\_id  | int    | 区服ID（必填）                        |
| page        | int    | 页数（非必填，默认为1，最大值25，每页最多返回200个数据） |

发送方式：GET

请求示例：

```bash
curl -X GET \
 -H "G-Id: {{gamekey}}" \
 -H "G-Key: {{masterkey}}" \
 -H "Content-Type: application/json" \
 -d '{"ranking_id": "1", "server_id": 1}' \
 http://{{host}}/archive/api/ranking
```

返回结果：

```json
{
    "code":200,
    "message":"success",
    "result":[{"rank":1,"uid":"321","role_id":"fdaj","score":10,"role_name":"aaaa","role_avatar":"bbbb"}]
}
```

### **更新成绩**

接口参数：

| 参数           | 类型     | 描述                   |
| :----------- | :----- | :------------------- |
| ranking\_id  | string | 排行榜ID（必填）            |
| server\_id   | int    | 区服ID（必填）             |
| uid          | int    | 用户UID（必填）            |
| role\_id     | string | 角色ID（必填）             |
| score        | float  | 分数（必填）               |
| overwrite    | bool   | 强制更新（非必填，强制更新时填true） |
| role\_name   | string | 用户名称（非必填，需更新名称时填写）   |
| role\_avatar | string | 用户头像（非必填，需更新头像时填写）   |

发送方式：POST

请求示例：

```bash
curl -X POST \
  -H "G-Id: {{gamekey}}" \
  -H "G-Key: {{masterkey}}" \
  -H "Content-Type: application/json" \
  -d '{"ranking_id": "1", "server_id": 1, "uid":3417726071,"role_id":"1","score":3,"overwrite":true}' \
  http://{{host}}/archive/api/ranking
```

返回结果：

{ "code":200, "message":"success", "result"\:null }

### **删除成绩**

接口参数：

| 参数          | 类型     | 描述        |
| :---------- | :----- | :-------- |
| ranking\_id | string | 排行榜ID（必填） |
| server\_id  | int    | 区服ID（必填）  |
| uid         | int    | 用户UID（必填） |
| role\_id    | string | 角色ID（必填）  |

发送方式：DELETE

请求示例：

```bash
curl -X POST \
  -H "G-Id: {{gamekey}}" \
  -H "G-Key: {{masterkey}}" \
  -H "Content-Type: application/json" \
  -d '{"ranking_id": "1", "server_id": 1, "uid":3417726071,"role_id":"1","score":3,"overwrite":true}' \
  http://{{host}}/archive/api/ranking
```

返回结果：

```json
{
    "code":200,
    "message":"success",
    "result":null
}
```

## **历史数据**

### **获取历史榜单**

接口参数：

| 参数          | 类型     | 描述                   |
| :---------- | :----- | :------------------- |
| ranking\_id | string | 排行榜ID（必填）            |
| server\_id  | int    | 区服ID（必填）             |
| version     | int    | 迭代周期（必填，可根据当前周期值时推算） |

发送方式：GET

请求示例：

```bash
curl -X GET \
  -H "G-Id: {{gamekey}}" \
  -H "G-Key: {{masterkey}}" \
  -H "Content-Type: application/json" \
  -d '{"ranking_id": "1", "server_id": 1, "version": 1}' \
  http://{{host}}/archive/api/rankingHistory
```

返回结果：

```json
{
    "code":200,
    "message":"success",
    "result": "archive.4399api.com\/download\/ranking\/1fda991b6c5474d20dedab6c8d3a0458.log"
}
```

返回的对象中result为文件下载地址

## **黑名单管理**

### **获取黑名单**

接口参数：

| 参数  | 类型         | 描述                             |
| :-- | :--------- | :----------------------------- |
| uid | int,string | 用户UID（非必填，多个可用逗号隔开，不填时获取所有黑名单） |

发送方式：GET

请求示例：

```bash
curl -X GET \
  -H "G-Id: {{gamekey}}" \
  -H "G-Key: {{masterkey}}" \
  -H "Content-Type: application/json" \
  -d '{"uid": "3417726071,3417726072"}' \
  http://{{host}}/archive/api/blacklist
```

返回结果：

```json
{
    "code":200,
    "message":"success",
    "result":["3417726071"]
}
```

返回的对象中result为黑名单uid集合

### **添加黑名单**

接口参数：

| 参数  | 类型         | 描述                 |
| :-- | :--------- | :----------------- |
| uid | int,string | 用户UID（必填，多个可用逗号隔开） |

发送方式：POST

请求示例：

```bash
curl -X POST \
  -H "G-Id: {{gamekey}}" \
  -H "G-Key: {{masterkey}}" \
  -H "Content-Type: application/json" \
  -d '{"uid": "3417726071"}' \
  http://{{host}}/archive/api/blacklist
```

返回结果：

```json
{
    "code":200,
    "message":"success",
    "result":null
}
```

### **删除黑名单**

接口参数：

| 参数  | 类型         | 描述                 |
| :-- | :--------- | :----------------- |
| uid | int,string | 用户UID（必填，多个可用逗号隔开） |

发送方式：DELETE

请求示例：

```bash
curl -X DELETE \
  -H "G-Id: {{gamekey}}" \
  -H "G-Key: {{masterkey}}" \
  -H "Content-Type: application/json" \
  -d '{"uid": "3417726071"}' \
  http://{{host}}/archive/api/blacklist
```

返回结果：

```json
curl -X DELETE \
  -H "G-Id: {{gamekey}}" \
  -H "G-Key: {{masterkey}}" \
  -H "Content-Type: application/json" \
  -d '{"uid": "3417726071"}' \
  http://{{host}}/archive/api/blacklist
```