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

User Achievement

概要​

User Achievement API 可以获取和更新用户对已定义的 Achievement 的达成状况 。
 
在 User Achievement API 中,可进行以下操作。

User Achievement 对象字段​

表示 User Achievement 的对象。

值说明类型不能写入补充
userId用户 IDintegerTRUE
appId应用软件 IDstringTRUE
achievementIdAchievement IDstringTRUE
state状态stringFALSE
steps进度integerFALSE
numOfUnlockedUnlock 次数integerTRUE
published创建时间stringTRUE
updated更新时间stringTRUE

Increment User Achievement 对象字段​

值说明类型不能写入补充
steps进度的差值integerfalse可指定包括负数在内的整数。

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 参数中,指定下述任意一项的值。

值说明类型备注
@meviewer の userIdstring必须
{userId}用户 IDstring or array必须
self or friends​

在self or friends 参数中,指定下述任意一项的值。

值说明类型备注
@self获取userId 参数指定的用户本人的 User Achievement 对象时string必须
@friends获取userId 参数指定的用户好友的 User Achievement 类集时string必须
appId​

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

值说明类型备注
@app当前执行的应用软件 IDstring必须
{appId}个别分配的应用软件 IDstring必须
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说明
stateUserAchievement#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 值中指定排序的关键字段。

值说明类型备注
sortBysortBy    指定排序关键字段名。只能指定"userId", "achievementId", "updated" 。string任意

要指定sortBy ,需要已指定sortOrder。

sortOrder​

只有在获取 User Achievement 类集时,可使用sortOrder。
指定sortBy 和 sortOrder 后,可对响应反馈的 User Achievement 对象类集添加排序条件。可在sortOrder 值中指定排序的关键字段。

值说明类型备注
sortOrdersortOrder    指定升序 (ascending)、降序 (descending) 。string任意

要指定sortOrder ,需要已指定sortBy。

updatedSince​

只有在获取 User Achievement 类集时,可使用updatedSince。
指定updatedSince 后,可对响应反馈的 User Achievement 对象类集设置指定时间以后的数据获取条件。

值说明类型备注
updatedSinceupdatedSince    获取对象为指定时间以后的数据 (最终更新时间的下限值)。但是,sortBy 非 updated 时忽略。string任意
fields​

可指定想要获取的字段。关于可指定的字段名,请参见 User Achievement 对象字段。
要指定多个时,使用不带空格的逗号 (,) 分隔指定。

值说明类型備考
fields想要只指定此资源的特定字段进行获取时,设置此项。array任意

为提高性能,请尽量只获取必要的属性。无任何指定时,可获取的默认字段如下。

["userId", "achievementId", "state"]

API响应​

响应代码​

API 的响应代码为以下中的任意一项。

请求 HTTP 方法响应代码响应信息说明
GET200OK数据获取正常完成
GET400Bad Request请求数据不当
GET401UnauthorizedOAuth 验证失败
GET403Forbidden由于认证错误以外的原因导致不能访问的情况
GET404Not FounduserId 不存在或 userId 的用户未安装 appId 的应用软件时。
GET405Method Not Allowed方法不允许
GET500Internal Server ErrorAPI 端的问题导致失败
GET503Service UnavailableAPI 端的暂时性错误

响应的数据结构​

作为API 的响应 payload ,反馈如下数据结构。

propertytitletypedescription
entry条目列表array
entry[].userId用户 IDstring
entry[].appId应用软件 IDstring
entry[].achievementIdAchievement IDstring
entry[].state状态string
entry[].steps达成度integer
entry[].numOfUnlockedUnlock 次数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,fields 

    URI Template 参数

    userId​

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

    值说明类型备注
    @meviewer 的 userIdstring必须
    {userId}用户 IDstring or array必须
    self​

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

    值说明类型备注
    @self获取userId 参数指定的用户本人的 User Achievement 对象时string必须
    appId​

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

    值说明类型備考
    @app当前执行的应用软件 IDstring必须
    {appId}个别分配的应用软件 IDstring必须
    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 方法响应代码响应信息说明
GET200OK数据获取正常完成
GET400Bad Request请求数据不当
GET401UnauthorizedOAuth 验证失败
GET403Forbidden由于认证错误以外的原因导致不能访问的情况
GET404Not Found分别指定单个userId 和 achievementId 时,此 achievementId 的 UserAchievement 对象不存在时。
GET405Method Not Allowed方法不允许
GET500Internal Server ErrorAPI 端的问题导致失败
GET503Service UnavailableAPI 端的暂时性错误

响应的数据结构​

作为API 响应的 payload ,反馈如下数据结构。

propertytitletypedescription
entry条目列表array
entry[].userId用户 IDstring
entry[].appId应用软件 IDstring
entry[].achievementIdAchievement IDstring
entry[].state状态string
entry[].steps达成度integer
entry[].numOfUnlockedUnlock 次数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 参数,指定下述任意一项的值。

    值说明类型备注
    @meviewer の userIdstring必须
    {userId}用户 IDstring or array必须
    self​

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

    值说明类型备注
    @self获取userId 参数指定的用户本人的 User Achievement 对象时string必须
    appId​

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

    值说明类型备注
    @app当前执行的应用软件 IDstring必须
    {appId}个别分配的应用软件 IDstring必须
    achievementId​

    在achievementId 参数中,指定以下值。

    值说明类型备注
    {achievementId}想要获取任意 Achievement 的 User Achievement 类集时,指定此项。string or array必须

    查询参数​

    可指定下述查询参数。

fields​

指定部分更新 (Partial Update) 的对象 field 。只能指定state, steps 中的任意一项。

值说明类型备注
fields只能指定"state", "steps" 中的任意一项。array任意

API 响应​

响应代码​

API 的响应代码为以下中的任意一项。

请求 HTTP 方法响应代码响应信息说明
PUT200OK资源更新正常完成。
PUT400Bad Request请求数据不当
PUT401UnauthorizedOAuth 验证失败
PUT403Forbidden由于认证错误以外的原因导致不能访问的情况
PUT404Not Found分别指定单个userId 和 achievementId 时,此 achievementId 的 UserAchievement 对象不存在时。
PUT409Conflict指定的资源不能更改时。
PUT500Internal Server ErrorAPI 端的问题导致失败
PUT503Service UnavailableAPI 端的暂时性错误

响应的数据结构​

会反馈 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"
}
 

​