跳到主要内容
未列出页
此页面未列出。搜索引擎不会对其索引,只有拥有直接链接的用户才能访问。

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

  • true 时,无论比现有积分高或低,总是可更新积分。
  • false 时,不能更新为比现有积分等级低的积分。

allowNegativeScore

负分设置

boolean

Read-Only

  • true 时,允许小于 0 的积分。
  • false 时,不允许小于 0 的积分。

allowTiedRank

同分排名设置

boolean

Read-Only

  • true 时,反馈按同积分同等级排名的数据。
  • false 时,反馈按同积分不同等级排名的数据。

reverse

排序设置

boolean

Read-Only

  • true 时,低积分的等级高。
  • false 时,高积分的等级高。

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 字段​

值说明单位
hoursHH.zzz秒
minutesMM.zzz秒
secondsSS.zzz秒
day_secondDD HH:MM:SS.zzz秒
day_minuteDD HH:MM.zzz秒
day_hourDD HH.zzz秒
hour_secondHH:MM:SS.zzz秒
hour_minuteHH:MM.zzz秒
minute_secondMM:SS.zzz秒

关于scoreFormat 与 displayValue 的关系​

积分对象 displayValue 的格式根据 Leaderboard.scoreFormat 而变化。

组合示例​

scoreFormatvaluedisplayValue
decimal100100.0
hours36001
minute_second365060:50

积分对象字段​

这是积分对象。用于获取积分排名、添加/更新/删除/加/减积分。只对 value 更改积分值。

值说明类型Read-Only
userId用户 IDstringRead-Only
value积分值int
displayValue格式规则值stringRead-Only
rank积分等级intRead-Only

API请求​

HTTP 方法​

Authorization Code Grant​

Client Credentials Grant​

appId​

在appid 参数中,指定下述任一项的值。

值说明备注
@app当前执行的应用程序 ID必须
leaderboardId​

在leaderboardId 参数中,指定下述任一项的值。

值说明备注
{leaderboardId}输入积分榜的指定值 (leaderboards.id 字段值) 。获取积分榜信息时为任意,其他为必须
userId​

在userId 参数中,指定下述任一项的值。

值说明备注
@meviewer 的 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 方法响应代码响应信息说明
GET200OK数据获取正常完成
POST/PUT/DELETE202Accepted数据更新或删除成功
GET/POST/PUT/DELETE400Bad Request请求数据不当
GET/POST/PUT/DELETE401UnauthorizedOAuth 验证失败
GET/PUT/DELETE403Forbidden由于认证错误以外的原因导致不能访问的情况
GET/PUT/DELETE404Not Found数据不存在,或已被物理删除
POST/PUT409Conflict积分值不能更新/加减时
GET/POST/PUT/DELETE429Too Many Requests请求数量超出限制时
GET/POST/PUT/DELETE500Internal Server ErrorAPI 端的问题导致失败
GET/POST/PUT/DELETE503Service 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

​