User Achievement
概要
User Achievement API 可以获取和更新用户对已定义的 Achievement 的达成状况 。
在 User Achievement API 中,可进行以下操作。
- 获取 User Achievement
- 更新 User Achievement
User Achievement 对象字段
表示 User Achievement 的对象。
| 值 | 说明 | 类型 | 不能写入 | 补充 |
|---|---|---|---|---|
| userId | 用户 ID | integer | TRUE | |
| appId | 应用软件 ID | string | TRUE | |
| achievementId | Achievement ID | string | TRUE | |
| state | 状态 | string | FALSE | |
| steps | 进度 | integer | FALSE | |
| numOfUnlocked | Unlock 次数 | integer | TRUE | |
| published | 创建时间 | string | TRUE | |
| updated | 更新时间 | string | TRUE |
Increment User Achievement 对象字段
| 值 | 说明 | 类型 | 不能写入 | 补充 |
|---|---|---|---|---|
| steps | 进度的差值 | integer | false | 可指定包括负数在内的整数。 |
API 请求
HTTP 方法
Authorization Code Grant
- GET
- 获取任意用户在应用内创建和更新过的 User Achievement 类集
- 指定 Achievement ID ,获取任意用户的 User Achievement 类集
- PUT
- 指定 Achievement ID ,创建和更新任意用户的 User Achievement 对象
Client Credentials Grant
- 不支持。
获取任意用户在应用内创建和更新过的 User Achievement 类集 (GET)
端点
-
Sandbox 环境
https://sb-app.mobage.jp/social/api/restful/v2/people{/userId}/@self/achievements{/appId}{?format,count,filterBy,filterOp,filterValue,sortBy,sortOrder,fields}https://sb-app.mobage.jp/social/api/restful/v2/people{/userId}/@friends/achievements{/appId,achievementId}{?format,count,filterBy,filterOp,filterValue,sortBy,sortOrder,fields} -
正式环境
https://app.mobage.jp/social/api/restful/v2/people{/userId}/@self/achievements{/appId}{?format,count,filterBy,filterOp,filterValue,sortBy,sortOrder,fields}https://app.mobage.jp/social/api/restful/v2/people{/userId}/@friends/achievements{/appId,achievementId}{?format,count,filterBy,filterOp,filterValue,sortBy,sortOrder,fields}
URI Template 参数
userId
在userId 参数中,指定下述任意一项的值。
| 值 | 说明 | 类型 | 备注 |
|---|---|---|---|
| @me | viewer の userId | string | 必须 |
| {userId} | 用户 ID | string or array | 必须 |
self or friends
在self or friends 参数中,指定下述任意一项的值。
| 值 | 说明 | 类型 | 备注 |
|---|---|---|---|
| @self | 获取userId 参数指定的用户本人的 User Achievement 对象时 | string | 必须 |
| @friends | 获取userId 参数指定的用户好友的 User Achievement 类集时 | string | 必须 |
appId
在appId 参数中,指定下述任意一项的值。
| 值 | 说明 | 类型 | 备注 |
|---|---|---|---|
| @app | 当前执行的应用软件 ID | string | 必须 |
| {appId} | 个别分配的应用软件 ID | string | 必须 |
achievementId
在achievementId 参数中,指定以下值。
| 值 | 说明 | 类型 | 备注 |
|---|---|---|---|
| {achievementId} | 想要获取任意 Achievement 的 User Achievement 类集时,指定此项。 | string or array | 任意 |
查询参数
可指定下述查询参数。
format
可指定响应格式。只能指定json 。
| 值 | 说明 | 类型 | 备注 |
|---|---|---|---|
| json | "application/json; charset=utf8" | string | 任意、默认值 |
count
获取类集资源的响应时,可指定最多可获取的条目资源条数。
| 值 | 说明 | 类型 | 备注 |
|---|---|---|---|
| count | 默认值为 50 条,最多可指定1000条。 | integer | 任意 |
※为提高性能,请尽量只获取必要的条数。
filterBy
只有在获取 User Achievement 类集时,可使用filterBy。
指定filterBy 后,可对响应反馈的 User Achievement 对象类集添加搜索条件。可在filterBy 值中指定搜索条件的关键字段。
| 值 | 说明 | 类型 | 备注 |
|---|---|---|---|
| filterBy | 指定想要添加条件的字段名。只能指定"state" 。 | string | 任意 |
目前可指定的 filterBy 值如下表所示。
| filterBy | 说明 |
|---|---|
| state | UserAchievement#state |
要指定filterBy,需要已指定 filterOp, filterValue 。
filterOp
只有在获取 User Achievement 类集时,可使用filterOp。
指定filterOp 后,可对响应反馈的 User Achievement 对象类集添加搜索条件。在filterOp 值中,指定对搜索条件的关键字和值的评价方式。
| 值 | 说明 | 类型 | 备注 |
|---|---|---|---|
| filterOp | 指定评价条件的运算符。只能指定"equals" 。省略时,视为指定 "equals" 。 | string | 任意 |
要指定filterOp ,需要已指定filterBy, filterValue 。
filterValue
只有在获取 User Achievement 类集时,可使用filterValue。
指定filterValue 后,可对响应反馈的 User Achievement 对象类集添加搜索条件。在filterValue 值中,指定对搜索条件的关键字和值的评价方式。
| 值 | 说明 | 类型 | 备注 |
|---|---|---|---|
| filterValue | 指定评价值。可指定"HIDDEN", "REVEALED", "UNLOCKED" が指定可能です。 | string | 任意 |
要指定filterValue ,需要已指定filterBy, filterOp 。
sortBy
只有在获取 User Achievement 类集时,可使用sortBy。
指定sortBy 和 sortOrder 后,可对响应反馈的 User Achievement 对象类集添加排序条件。可在sortBy 值中指定排序的关键字段。
| 值 | 说明 | 类型 | 备注 |
|---|---|---|---|
| sortBy | sortBy 指定排序关键字段名。只能指定"userId", "achievementId", "updated" 。 | string | 任意 |
要指定sortBy ,需要已指定sortOrder。
sortOrder
只有在获取 User Achievement 类集时,可使用sortOrder。
指定sortBy 和 sortOrder 后,可对响应反馈的 User Achievement 对象类集添加排序条件。可在sortOrder 值中指定排序的关键字段。
| 值 | 说明 | 类型 | 备注 |
|---|---|---|---|
| sortOrder | sortOrder 指定升序 (ascending)、降序 (descending) 。 | string | 任意 |
要指定sortOrder ,需要已指定sortBy。
updatedSince
只有在获取 User Achievement 类集时,可使用updatedSince。
指定updatedSince 后,可对响应反馈的 User Achievement 对象类集设置指定时间以后的数据获取条件。
| 值 | 说明 | 类型 | 备注 |
|---|---|---|---|
| updatedSince | updatedSince 获取对象为指定时间以后的数据 (最终更新时间的下限值)。但是,sortBy 非 updated 时忽略。 | string | 任意 |
fields
可指定想要获取的字段。关于可指定的字段名,请参见 User Achievement 对象字段。
要指定多个时,使用不带空格的逗号 (,) 分隔指定。
| 值 | 说明 | 类型 | 備考 |
|---|---|---|---|
| fields | 想要只指定此资源的特定字段进行获取时,设置此项。 | array | 任意 |
为提高性能,请尽量只获取必要的属性。无任何指定时,可获取的默认字段如下。
["userId", "achievementId", "state"]
API响应
响应代码
API 的响应代码为以下中的任意一项。
| 请求 HTTP 方法 | 响应代码 | 响应信息 | 说明 |
|---|---|---|---|
| GET | 200 | OK | 数据获取正常完成 |
| GET | 400 | Bad Request | 请求数据不当 |
| GET | 401 | Unauthorized | OAuth 验证失败 |
| GET | 403 | Forbidden | 由于认证错误以外的原因导致不能访问的情况 |
| GET | 404 | Not Found | userId 不存在或 userId 的用户未安装 appId 的应用软件时。 |
| GET | 405 | Method Not Allowed | 方法不允许 |
| GET | 500 | Internal Server Error | API 端的问题导致失败 |
| GET | 503 | Service Unavailable | API 端的暂时性错误 |
响应的数据结构
作为API 的响应 payload ,反馈如下数据结构。
| property | title | type | description |
|---|---|---|---|
| entry | 条目列表 | array | |
| entry[].userId | 用户 ID | string | |
| entry[].appId | 应用软件 ID | string | |
| entry[].achievementId | Achievement ID | string | |
| entry[].state | 状态 | string | |
| entry[].steps | 达成度 | integer | |
| entry[].numOfUnlocked | Unlock 次数 | integer | |
| entry[].published | 创建时间 | string | |
| entry[].updated | 更新时间 | string | |
| startIndex | 开始索引值 | integer | |
| itemsPerPage | 每页条数 | integer | |
| totalResults | 总条数 | integer | |
| filtered | 使用过滤旗标 | boolean | 使用过滤时为 true |
| sorted | 使用排序旗标 | boolean | 使用排序时为 true。 |
样例
获取任意用户的 User Achievement 类集时
请求格式
GET /people/@me/@self/achievements/@app?filterValue=UNLOCKED&count=10&fields=achievementId%2CnumOfUnlocked%2Cupdated&updatedSince=2013-07-13T05%3A37%3A11&sortOrder=descending&sortBy=updated&filterBy=state
Authorization: OAuth oauth_parameters
响应格式
200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: no-cache
Pragma: no-cache
{
"entry": [
{ "achievementId": "blood_reign", "numOfUnlocked": 1, "updated": "2013-07-16T04:57:08" },
{ "achievementId": "dragon_scale", "numOfUnlocked": 1, "updated": "2013-07-16T03:49:18" },
{ "achievementId": "animal_hunter", "numOfUnlocked": 5, "updated": "2013-07-16T02:53:49" },
{ "achievementId": "exorcist", "numOfUnlocked": 1, "updated": "2013-07-16T01:48:36" },
{ "achievementId": "self_preservation", "numOfUnlocked": 2, "updated": "2013-07-16T00:51:54" },
{ "achievementId": "berserk", "numOfUnlocked": 1, "updated": "2013-07-15T23:57:03" },
{ "achievementId": "arbitration", "numOfUnlocked": 1, "updated": "2013-07-15T22:54:31" },
{ "achievementId": "broken_heart", "numOfUnlocked": 3, "updated": "2013-07-15T21:54:15" },
{ "achievementId": "sniper", "numOfUnlocked": 1, "updated": "2013-07-15T20:56:45" },
{ "achievementId": "fist_fight", "numOfUnlocked": 1, "updated": "2013-07-15T19:57:15" }
],
"startIndex": 1,
"itemsPerPage": 10,
"totalResults": 31,
"filtered": true,
"sorted": true,
"updatedSince": true
}
获取任意用户好友的 User Achievement 类集时
获取好友的 User Achievement 类集时,必须指定 achievementId 。
请求格式
GET /people/@me/@friends/achievements/@app/bogus_hero?count=10&fields=userId%2Cstate%2CnumOfUnlocked%2Cupdated&updatedSince=2013-07-13T05%3A37%3A11&sortOrder=descending&sortBy=userId
Authorization OAuth oauth_parameters
响应格式
200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: no-cache
Pragma: no-cache
{
"entry": [
{ "userId": "sp.mbga.jp:10234", "state": "UNLOCKED", "numOfUnlocked": 1, "updated": "2013-07-15T19:26:42" },
{ "userId": "sp.mbga.jp:10211", "state": "REVEALED", "numOfUnlocked": 0, "updated": "2013-07-16T01:26:49" },
{ "userId": "sp.mbga.jp:10108", "state": "HIDDEN", "numOfUnlocked": 0, "updated": "2013-07-15T10:26:53" },
{ "userId": "sp.mbga.jp:9987", "state": "REVEALED", "numOfUnlocked": 0, "updated": "2013-07-16T06:27:00" },
{ "userId": "sp.mbga.jp:9312", "state": "UNLOCKED", "numOfUnlocked": 1, "updated": "2013-07-15T09:27:07" },
{ "userId": "sp.mbga.jp:8778", "state": "UNLOCKED", "numOfUnlocked": 1, "updated": "2013-07-15T15:27:12" },
{ "userId": "sp.mbga.jp:7009", "state": "HIDDEN", "numOfUnlocked": 0, "updated": "2013-07-15T20:27:17" },
],
"startIndex": 1,
"itemsPerPage": 10,
"totalResults": 17,
"filtered": false,
"sorted": true,
"updatedSince": false
}
指定 Achievement ID ,获取任意用户的 User Achievement 类集 (GET)
端点
-
Sandbox 环境
https://sb-app.mobage.jp/social/api/restful/v2/people{/userId}/@self/achievements{/appId,achievementId}{?format,fields} -
正式环境
https://app.mobage.jp/social/api/restful/v2/people{/userId}/@self/achievements{/appId,achievementId}{?format,fieldsURI Template 参数
userId
在userId 参数中,指定下述任意一项的值。
值 说明 类型 备注 @me viewer 的 userId string 必须 {userId} 用户 ID string or array 必须 self
在self 参数中,指定下述任意一项的值。
值 说明 类型 备注 @self 获取userId 参数指定的用户本人的 User Achievement 对象时 string 必须 appId
在appId 参数中,指定下述任意一项的值。
值 说明 类型 備考 @app 当前执行的应用软件 ID string 必须 {appId} 个别分配的应用软件 ID string 必须 achievementId
achievementId パラメータには以下を指定します。
值 说明 类型 备注 {achievementId} 为了获取任意 Achievement 的 User Achievement 类集,指定此项。 string or array 必须
查询参数
可指定下述查询参数。
format
可指定响应格式。只能指定json 。
| 值 | 说明 | 类型 | 备注 |
|---|---|---|---|
| json | "application/json; charset=utf8" | string | 任意、默认值 |
fields
可指定想要获取的字段。关于可指定的字段名,请参见 User Achievement 对象字段。
要指定多个时,使用不带空格的逗号 (,) 分隔指定。
| 值 | 说明 | 类型 | 備考 |
|---|---|---|---|
| fields | 只想要指定此资源的特定字段进行获取时,设置此项。 | array | 任意 |
为提高性能,请尽量只获取必要的属性。无任何指定时,可获取的默认字段如下。
["userId", "achievementId", "state"]
API 响应
响应代码
API 的响应代码为以下中的任意一项。
| 请求 HTTP 方法 | 响应代码 | 响应信息 | 说明 |
|---|---|---|---|
| GET | 200 | OK | 数据获取正常完成 |
| GET | 400 | Bad Request | 请求数据不当 |
| GET | 401 | Unauthorized | OAuth 验证失败 |
| GET | 403 | Forbidden | 由于认证错误以外的原因导致不能访问的情况 |
| GET | 404 | Not Found | 分别指定单个userId 和 achievementId 时,此 achievementId 的 UserAchievement 对象不存在时。 |
| GET | 405 | Method Not Allowed | 方法不允许 |
| GET | 500 | Internal Server Error | API 端的问题导致失败 |
| GET | 503 | Service Unavailable | API 端的暂时性错误 |
响应的数据结构
作为API 响应的 payload ,反馈如下数据结构。
| property | title | type | description |
|---|---|---|---|
| entry | 条目列表 | array | |
| entry[].userId | 用户 ID | string | |
| entry[].appId | 应用软件 ID | string | |
| entry[].achievementId | Achievement ID | string | |
| entry[].state | 状态 | string | |
| entry[].steps | 达成度 | integer | |
| entry[].numOfUnlocked | Unlock 次数 | integer | |
| entry[].published | 创建时间 | string | |
| entry[].updated | 更新时间 | string | |
| startIndex | 开始索引值 | integer | |
| itemsPerPage | 每页条数 | integer | |
| totalResults | 总条数 | integer |
样例
指定 Achievement ID ,获取任意用户的 User Achievement 类集
请求格式
GET /people/@me/@self/achievements/@app/bogus_hero
Authorization: OAuth oauth_parameters
响应格式
200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: no-cache
Pragma: no-cache
{
"userId": "sp.mbga.jp:12345",
"achievementId": "bogus_hero",
"state": "REVEALED"
}
指定多个 Achievement ID ,获取多个任意用户的 User Achievement 类集
请求格式
GET /people/10234,10351,11487/@self/achievements/@app/blood_reign,animal_hunter
Authorization: OAuth oauth_parameters
响应格式
200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: no-cache
Pragma: no-cache
{
"entry": [
{ "userId": "sp.mbga.jp:10234", "achievementId": "blood_reign", "state": "UNLOCKED" },
{ "userId": "sp.mbga.jp:10234", "achievementId": "animal_hunter", "state": "REVEALED" },
{ "userId": "sp.mbga.jp:10351", "achievementId": "animal_hunter", "state": "REVEALED" },
{ "userId": "sp.mbga.jp:11487", "achievementId": "blood_reign", "state": "HIDDEN" },
{ "userId": "sp.mbga.jp:11487", "achievementId": "animal_hunter", "state": "UNLOCKED" }
],
"startIndex": 1,
"itemsPerPage": 5
"totalResults": 5
}
指定 Achievement ID ,创建和更新任意用户的 User Achievement 对象 (PUT)
端点
-
Sandbox 环境
https://sb-app.mobage.jp/social/api/restful/v2/people{/userId}/@self/achievements{/appId,achievementId}{?fields} -
正式环境
https://app.mobage.jp/social/api/restful/v2/people{/userId}/@self/achievements{/appId,achievementId}{?fields}URI Template 参数
userId
userId 参数,指定下述任意一项的值。
值 说明 类型 备注 @me viewer の userId string 必须 {userId} 用户 ID string or array 必须 self
在self 参数中,指定下述任意一项的值。
值 说明 类型 备注 @self 获取userId 参数指定的用户本人的 User Achievement 对象时 string 必须 appId
在appId 参数中,指定下述任意一项的值。
值 说明 类型 备注 @app 当前执行的应用软件 ID string 必须 {appId} 个别分配的应用软件 ID string 必须 achievementId
在achievementId 参数中,指定以下值。
值 说明 类型 备注 {achievementId} 想要获取任意 Achievement 的 User Achievement 类集时,指定此项。 string or array 必须 查询参数
可指定下述查询参数。
fields
指定部分更新 (Partial Update) 的对象 field 。只能指定state, steps 中的任意一项。
| 值 | 说明 | 类型 | 备注 |
|---|---|---|---|
| fields | 只能指定"state", "steps" 中的任意一项。 | array | 任意 |
API 响应
响应代码
API 的响应代码为以下中的任意一项。
| 请求 HTTP 方法 | 响应代码 | 响应信息 | 说明 |
|---|---|---|---|
| PUT | 200 | OK | 资源更新正常完成。 |
| PUT | 400 | Bad Request | 请求数据不当 |
| PUT | 401 | Unauthorized | OAuth 验证失败 |
| PUT | 403 | Forbidden | 由于认证错误以外的原因导致不能访问的情况 |
| PUT | 404 | Not Found | 分别指定单个userId 和 achievementId 时,此 achievementId 的 UserAchievement 对象不存在时。 |
| PUT | 409 | Conflict | 指定的资源不能更改时。 |
| PUT | 500 | Internal Server Error | API 端的问题导致失败 |
| PUT | 503 | Service Unavailable | API 端的暂时性错误 |
响应的数据结构
会反馈 User Achievement 对象字段 本身。
注意事项
- 更新state 时,根据更新前的 state 值有所限制。
- 更新前的 state 为 HIDDEN 时,只能更改为 REVEALED, UNLOCKED
- 更新前的 state 为 REVEALED 时,只能更改为 UNLOCKED
- 更新前的 state 为 UNLOCKED 时,只有当Achievement.repeatable 为 true 的 Achievement 时,才可再次指定 UNLOCKED 。
- 更新steps 时,如果更新前的状态符合以下任意一项,则可进行。
- state 值为 REVEALED
- Achievement.repeatable 为 true, 并且 state 值为 UNLOCKED 的 Achievement
- Achievement.repeatable 为 true 时,当指定的 steps 值超出 Achievement.totalSteps 时,不会设置超出的值,而会采用 Achievement.totalSteps 值。
样例
指定 Achievement ID ,创建和更新任意用户的 User Achievement 对象 (PUT)
更新 steps
请求格式
PUT /people/@me/@self/achievements/@app/bogus_hero?fields=steps
Authorization: OAuth oauth_parameters
Content-Type: application/json; charset=utf-8
{
"steps": 10
}
响应格式
200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: no-cache
Pragma: no-cache
{
"userId": "sp.mbga.jp:12345",
"appId": "12000129",
"achievementId": "bogus_hero",
"state": "REVEALED",
"steps": 10,
"numOfUnlocked": 0,
"published": "2013-07-15T09:13:58",
"updated": "2013-07-15T11:22:16"
}
更新 state
请求格式
PUT /people/@me/@self/achievements/@app/bullpen_ace?fields=state
Authorization: OAuth oauth_parameters
Content-Type: application/json; charset=utf-8
{
"state": "REVEALED"
}
响应格式
200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: no-cache
Pragma: no-cache
{
"userId": "sp.mbga.jp:12345",
"appId": "12000129",
"achievementId": "bullpen_ace",
"state": "REVEALED",
"steps": 0,
"numOfUnlocked": 0,
"published": "2013-07-15T09:13:58",
"updated": "2013-07-15T11:22:16"
}