Leaderboard
概要
获取积分榜信息、获取积分排名、添加/更新/删除/加/减积分所需的 API。
Leaderboard 对象字段
积分榜信息对象。可用于获取积分榜信息。可在 Mobage Developers Japan(开发者网站) 中设置各值。
值 | 说明 | 类型 | Read-Only | 补充 |
|---|---|---|---|---|
id | 积分榜id | string | Read-Only | – |
appId | 应用ID | string | Read-Only | – |
title | 标题 | string | Read-Only | – |
scoreFormat | 积分格式 | string | Read-Only | 为显示积分所使用的格式。值的列表请参见以下“关于Leaderboard.scoreFormat 的值”。 |
scorePrecision | 积分小数点后的位数 | int | Read-Only | – |
iconUrl | 图标URL | string | Read-Only | – |
allowLowerScore | 积分替换设置 | boolean | Read-Only |
|
allowNegativeScore | 负分设置 | boolean | Read-Only |
|
allowTiedRank | 同分排名设置 | boolean | Read-Only |
|
reverse | 排序设置 | boolean | Read-Only |
|
defaultScore | 默认积分 | int | Read-Only | – |
archived | 存档 | boolean | Read-Only | true 时,关闭积分榜,不能更新积分。只能浏览。 |
published | 生成时间 | dateTime | Read-Only | GMT |
updated | 更新时间 | dateTime | Read-Only | GMT |
关于Leaderboard.scoreFormat 的值
scoreFormat 会根据 Mobage Developers Japan(开发者网站)中的格式设置,反馈以下 Numeric Expression Fields 或 Time Expression Fields 的值。
Numeric Expression 字段
| 值 | 说明 | 单位 |
|---|---|---|
| integer | 整数 | – |
| decimal | 小数 | – |
Time Expression 字段
| 值 | 说明 | 单位 |
|---|---|---|
| hours | HH.zzz | 秒 |
| minutes | MM.zzz | 秒 |
| seconds | SS.zzz | 秒 |
| day_second | DD HH:MM:SS.zzz | 秒 |
| day_minute | DD HH:MM.zzz | 秒 |
| day_hour | DD HH.zzz | 秒 |
| hour_second | HH:MM:SS.zzz | 秒 |
| hour_minute | HH:MM.zzz | 秒 |
| minute_second | MM:SS.zzz | 秒 |
关于scoreFormat 与 displayValue 的关系
积分对象 displayValue 的格式根据 Leaderboard.scoreFormat 而变化。
组合示例
| scoreFormat | value | displayValue |
|---|---|---|
| decimal | 100 | 100.0 |
| hours | 3600 | 1 |
| minute_second | 3650 | 60:50 |
积分对象字段
这是积分对象。用于获取积分排名、添加/更新/删除/加/减积分。只对 value 更改积分值。
| 值 | 说明 | 类型 | Read-Only |
|---|---|---|---|
| userId | 用户 ID | string | Read-Only |
| value | 积分值 | int | |
| displayValue | 格式规则值 | string | Read-Only |
| rank | 积分等级 | int | Read-Only |
API请求
HTTP 方法
Authorization Code Grant
- GET
- PUT
- POST
- DELETE
Client Credentials Grant
-
GET
-
PUT
-
POST
-
DELETE
-
Sandbox 环境
https://sb-app.mobage.jp/social/api/restful/v2/leaderboards/{appId}/{leaderboardId}/{userId}/{selector} -
正式环境
https://app.mobage.jp/social/api/restful/v2/leaderboards/{appId}/{leaderboardId}/{userId}/{selector}URI Template 参数
appId
在appid 参数中,指定下述任一项的值。
| 值 | 说明 | 备注 |
|---|---|---|
| @app | 当前执行的应用程序 ID | 必须 |
leaderboardId
在leaderboardId 参数中,指定下述任一项的值。
| 值 | 说明 | 备注 |
|---|---|---|
| {leaderboardId} | 输入积分榜的指定值 (leaderboards.id 字段值) 。 | 获取积分榜信息时为任意,其他为必须 |
userId
在userId 参数中,指定下述任一项的值。
| 值 | 说明 | 备注 |
|---|---|---|
| @me | viewer 的 userId | 必须 |
| {userId} | 用户 ID | 必须 |
selector
在selector 参数中,指定下述任一项的值。
| 值 | 说明 | 备注 |
|---|---|---|
| @self | 对userId 参数指定的用户积分的条目资源 | 必须 |
| @friends | 对userId 参数指定的用户好友的类集资源 | 必须 |
| @all | 与@friends 同义 | 必须 |
| @aroundme | 与userId 参数所指定的用户的等级相接近的用户信息的类集资源 | 必须 |
查询参数
可指定下述查询参数。
format
可指定响应格式。
| 值 | 说明 | 备注 |
|---|---|---|
| json | "application/json; charset=utf8" | 任意、默认值 |
fields
可指定想要获取的积分信息、积分榜信息。关于可指定的字段名,请参见Score 对象字段、Leaderboard对象字段。要指定多个时,使用不带空格的逗号 (,) 分割指定。省略fields 参数时,获取下述全部字段。
count
获取类集资源的响应时,可指定最多可获取的条目资源条数。可在selector 中指定 @all 或 @aroundme。
默认值为 50 条,最多可指定 1000 条。
为提高性能,请尽量只获取必要的条数。
startIndex
指定类集资源的开始值。省略时,自动指定 1。
sortBy
指定sortBy 和 sortOrder 后,可对响应反馈的对象类集添加排序条件。
可在sortBy 值中指定排序的关键字段。可指定的 sortBy 值如下。要指定sortBy ,需要已指定sortOrder。
| sortBy | 说明 |
|---|---|
| rank | 积分等级 |
| value | 积分值 |
sortOrder
只有在获取类集时,可使用sortOrder。
指定sortBy 和 sortOrder 后,可对响应反馈的对象类集添加排序条件。
可在sortOrder 值中指定排序时的升序和降序。可指定的 sortOrder 值如下表所示。要指定sortOrder ,需要已指定sortBy。
| sortOrder | 说明 |
|---|---|
| ascending | 升序 |
| descending | 降序 |
API响应
响应代码
API 的响应代码为以下中的任一项。
| 请求 HTTP 方法 | 响应代码 | 响应信息 | 说明 |
|---|---|---|---|
| GET | 200 | OK | 数据获取正常完成 |
| POST/PUT/DELETE | 202 | Accepted | 数据更新或删除成功 |
| GET/POST/PUT/DELETE | 400 | Bad Request | 请求数据不当 |
| GET/POST/PUT/DELETE | 401 | Unauthorized | OAuth 验证失败 |
| GET/PUT/DELETE | 403 | Forbidden | 由于认证错误以外的原因导致不能访问的情况 |
| GET/PUT/DELETE | 404 | Not Found | 数据不存在,或已被物理删除 |
| POST/PUT | 409 | Conflict | 积分值不能更新/加减时 |
| GET/POST/PUT/DELETE | 429 | Too Many Requests | 请求数量超出限制时 |
| GET/POST/PUT/DELETE | 500 | Internal Server Error | API 端的问题导致失败 |
| GET/POST/PUT/DELETE | 503 | Service Unavailable | 超出API 端的限制导致暂时不能使用时 |
样例
获取积分榜列表
获取与当前执行的应用程序 ID 绑定的积分榜列表。
请求格式
GET /api/restful/v2/leaderboards/@app
响应格式
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"entry": [
{
"id": "1334",
"appId": "12000129",
"title": "Best time ranking",
"scoreFormat": "minute_second",
"scorePrecision": 0,
"iconUrl": "http://example.com/time_ranking.png",
"allowLowerScore": false,
"reverse": false,
"archived": false,
"defaultScore": null,
"published": "2012-02-14 21:00:12T",
"updated": "2012-02-14 21:00:12T"
},
{
"id": "1373",
"appId": "12000129",
"title": "The number of win ranking",
"scoreFormat": "integer",
"scorePrecision": 0,
"iconUrl": "http://example.com/win_ranking.png",
"allowLowerScore": false,
"reverse": true,
"archived": false,
"defaultScore": 0,
"published": "2012-02-14 21:00:12T",
"updated": "2012-02-14 21:00:12T"
}
],
"totalResults": 2,
"itemsPerPage": 50,
"startIndex": 1,
"sorted": false
}
获取指定积分榜信息
从 Leaderboard ID 获取指定的积分榜信息。
请求格式
GET /leaderboards/@app/1334
响应格式
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"id": "1334",
"appId": "12000129",
"title": "Best time ranking",
"scoreFormat": "minute_second",
"scorePrecision": 0,
"iconUrl": "http://example.com/time_ranking.png",
"allowLowerScore": false,
"reverse": false,
"archived": false,
"defaultScore": null,
"published": "2012-02-14 21:00:12T",
"updated": "2012-02-14 21:00:12T"
}
获取多个指定积分榜
从 Leaderboard ID 获取多个指定的积分榜信息。
请求格式
GET /api/restful/v2/leaderboards/@app/1334,1373
响应格式
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"entry": [
{
"id": "1334",
"appId": "12000129",
"title": "Best time ranking",
"scoreFormat": "minute_second",
"scorePrecision": 0,
"iconUrl": "http://example.com/time_ranking.png",
"allowLowerScore": false,
"reverse": false,
"archived": false,
"defaultScore": null,
"published": "2012-02-14 21:00:12T",
"updated": "2012-02-14 21:00:12T"
},
{
"id": "1373",
"appId": "12000129",
"title": "The number of win ranking",
"scoreFormat": "integer",
"scorePrecision": 0,
"iconUrl": "http://example.com/win_ranking.png",
"allowLowerScore": false,
"reverse": true,
"archived": false,
"defaultScore": 0,
"published": "2012-02-14 21:00:12T",
"updated": "2012-02-14 21:00:12T"
}
],
"totalResults": 2,
"itemsPerPage": 50,
"startIndex": 1,
"sorted": false
}
获取最高积分列表
在指定的积分榜中,获取前 50 位用户积分。
请求格式
GET /api/restful/v2/leaderboards/@app/1334/@me/@all?sortBy=rank&sortOrder=asscending&count=50&startIndex=1
响应格式
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"entry": [
{
"userId": "10028",
"value": 128,
"displayValue": "2:08",
"rank": 1,
},
{
"userId": "10029",
"value": 130,
"displayValue": "2:10",
"rank": 2,
},
/* ... */
],
"totalResults": 2,
"itemsPerPage": 50,
"startIndex": 1,
"sorted": true
}
获取指定用户的好友积分列表
在指定的积分榜中,获取用户的好友积分。
请求格式
GET /api/restful/v2/leaderboards/@app/1334/@me/@friends?sortBy=rank&sortOrder=ascending
响应格式
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"entry": [
{
"userId": "10028",
"value": 128,
"displayValue": "2:08",
"rank": 1,
},
{
"userId": "10029",
"value": 130,
"displayValue": "2:10",
"rank": 2,
},
],
"totalResults": 2,
"itemsPerPage": 50,
"startIndex": 1,
"sorted": true
}
获取指定用户的积分
可从指定的积分榜中,获取指定用户的积分。
请求格式
GET /api/restful/v2/leaderboards/@app/1334/10128/@self
响应格式
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"userId": "10128",
"value": 128,
"displayValue": "2:08",
"rank": 1
}
获取与指定用户等级接近的等级的用户信息
从指定的积分榜中,获取接近等级的用户信息的是示例如下。
-
指定用户的等级为 100 且 count 设置为 20 时,会获取90 至 109 等级的用户信息。
-
指定用户的等级为 100 且 count 设置为 21 时,会获取90 至 110 等级的用户信息。
-
指定用户的等级为 6 且 count 设置为 50 时,会获取1 至 50 等级的用户信息。
注意
但是,在同分排名设置中勾选“将同积分作为同排名处理”时(allowTiedRank = true) ,不一定会获取如上所述 90 至 110 级的排名,而会获取count 设置的人数。例如,排名为1, 2, 3, 4, 4, 4, 7, 8, 8, 10 ,自己为 7,count 设置为 5 时,可获取4, 4, 7, 8, 8 等级的用户信息。 :::
请求格式
GET /api/restful/v2/leaderboards/@app/aaa111/10128/@aroundme?count=3&sortBy=value&sortOrder=descending
响应格式
{
"entry" : [
{
"value" : 300,
"displayValue" : "300.00",
"userId" : "10768",
"rank" : 3
},
{
"value" : 200,
"displayValue" : "200.00",
"userId" : "10128",
"rank" : 2
},
{
"value" : 100,
"displayValue" : "100.00",
"userId" : "10444",
"rank" : 1
}
],
"startIndex" : 1,
"sorted" : true,
"itemsPerPage" : 3,
"totalResults" : 6
}
添加/更新指定用户的积分
添加或更新指定积分榜和用户积分。添加(新注册)积分、更新积分(替换积分)都在 PUT 上进行。
要添加/更新积分,请务必在查询参数中指定 fiels=value。
未勾选“总是替换” (allowLowerScore = false) 且排序设置为“降序”(reverse = false)时,不能更新为比用户当前积分低的值。
未勾选“总是替换” (allowLowerScore = false) 且排序设置为“升序”(reverse = true)时,不能更新为比用户当前积分高的值。
未勾选“允许负分” (allowNegativeScore = false) 时,当指定负分时,会反馈409错误代码响应。
请求格式
PUT /api/restful/v2/leaderboards/@app/1334/@me/@self?fields=value
Content-Type: application/json; charset=utf-8
{
"value": 100
}
响应格式
202 Accepted
Content-Type: application/json; charset=utf-8
{
"rank": 57,
"value": 100,
"userId": "mbga.jp:1192",
"displayValue": "1:40",
}
积分更新时的错误
未勾选“总是替换” (allowLowerScore = false) 且排序设置为“降序”(reverse = false)的情况下,当试图更新为比指定用户的现有积分低的积分时会反馈错误响应,如下面所述。
未勾选“总是替换” (allowLowerScore = false) 且排序设置为“升序”(reverse = true)的情况下,当试图更新为比指定用户的当前积分高的积分时,也会反馈同样错误。
请求格式
PUT /api/restful/v2/leaderboards/@app/1334/@me/@self?fields=value
Content-Type: application/json; charset=utf-8
{
"value": 80
}
响应格式
409 Conflict
Content-Type: "application/json; charset=utf-8"
{
"Error" : {
"Code" : "409",
"Message" : "Conflict (The leaderboard (leaderboard_name) doesn't allow a worse score (appId: 1200xxxx, current_score: 100, new_score: 80))"
}
}
增加指定用户的现有积分
可增加指定用户的现有积分。
未勾选“总是替换” (allowLowerScore = false) 且排序设置为“升序”(reverse = true)时,会反馈409 错误代码。
请求格式
POST /api/restful/v2/leaderboards/@app/1334/@me/@self/increment
Content-Type: application/json; charset=utf-8
{
"value": 100
}
响应格式
202 Accepted
Content-Type: application/json; charset=utf-8
{
"rank": 14,
"value": 1100,
"userId": "12345",
"displayValue": "1100"
}
减少指定用户的现有积分
可减少指定用户的现有积分。
未勾选“总是替换” (allowLowerScore = false) 且排序设置为“降序”(reverse = false)时,会反馈409 错误代码。
未勾选“允许负分” (allowNegativeScore = false) 时,即使减积分的结果小于 0 (负值),积分也一定会是 0。
请求格式
POST /api/restful/v2/leaderboards/@app/1334/@me/@self/decrement
Content-Type: application/json; charset=utf-8
{
"value": 100
}
响应格式
202 Accepted
Content-Type: application/json; charset=utf-8
{
"rank": 29,
"value": 900,
"userId": "12345",
"displayValue": "900"
}
删除指定用户的积分
可将指定用户的积分信息删除。
请求格式
DELETE /api/restful/v2/leaderboards/@app/1334/@me/@self
Content-Type: application/json; charset=utf-8
响应格式
202 Accepted
Content-Type: application/json; charset=utf-8