跳到主要内容

AppData

概要​

按用户分配的持久数据 API。

Appdata 对象字段​

向Appdata API 发送请求后,会反馈Appdata 对象。

值说明类型补充
entry持久数据tnx:AppdataEntry (unbounded)key-value 格式的类集

entry 字段​

请指定Appdata Entry 对象的数组。此时可指定的 Appdata Entry 对象字段如下。

值说明类型补充
key持久数据的关键字xs:string上限 32 byte
value持久数据的值xs:string上限 1024 byte

关于JSON 格式的描述​

以下描述均为同一对象。

  1. 完整描述
{
"entry": [
{ "key": "score", "value": "78" },
{ "key": "high_score", "value": "97" }
]
}

2.仅简要描述 Appdata Entry

{
"entry": [
{ "score": "78" },
{ "high_score": "97" }
]
}
  1. 简要描述 Appdata, Appdata Entry
{
"score": "78",
"high_score": "97"
}
如无特殊理由,3. Appdata, Appdata Entry 两种对象都请发送简要描述。

API 请求​

HTTP 方法​

  • Authorization Code Grant
    • GET - Appdata 获取
    • POST - Appdata 创建和更新
    • PUT - Appdata 创建和更新 (与POST 时的动作相同)
    • DELETE - Appdata 删除
  • Client Credentials Grant
    • GET - Appdata 获取

端点 URL​

  • Sandbox 环境

    https://sb-app.mobage.jp/social/api/restful/v2/appdata/{guid}/{selector}/{appid}
  • 正式环境

    https://app.mobage.jp/social/api/restful/v2/appdata/{guid}/{selector}/{appid}

URI Template 参数​

guid​

在guid 参数中,指定以下任意一项的值。

值说明备注
@meviewer の guid必须
{guid}用户 ID必须

要指定guid 中有效的用户 ID ,需要用户已安装此应用软件。

selector​

selector 参数中,可仅指定 @self。

值说明备注
@self表示viewer 的 Appdata 类集资源必须
appid​

在appid 参数中,可仅指定 @app。

值说明备注
@app表示对当前执行应用软件的 Appdata 条目资源必须

查询参数​

format​

可指定响应格式。

值说明备注
json"application/json; charset=utf8"任意、默认值

fields​

在Appdata 中, fields 指定的是 Appdata Entry 对象的 key 值。因此在进行Appdata 的更新和删除时,请指定特定的 key 进行操作。详情请参见 
OpenSocial RESTful Protocol Specification v0.9 - 9.3 Partial Updates 。

API 响应​

响应代码​

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

请求 HTTP 方法响应代码响应信息说明
GET200OKAppdata 获取正常完成
POST/PUT201CreatedAppdata 生成和更新成功
DELETE202AcceptedAppdata 删除成功
GET/POST/PUT/DELETE400Bad Request请求数据不当
GET/POST/PUT/DELETE401UnauthorizedOAuth 验证失败
GET/POST/PUT/DELETE403Forbidden由于认证错误以外的原因导致不能访问的情况
GET/POST/PUT/DELETE405Method Not Allowed方法不允许
GET/POST/PUT/DELETE500Internal Server ErrorAPI 端的问题导致失败

注意事项​

  • 不指定fields 的 GET 是指所有 Appdata 条目。如果事先知道需要的关键字,请务必指定 fields。
  • 不指定fields 的 POST/PUT/DELETE 反馈 400 。请在fields 中指定操作对象的关键字后发送请求。
  • key, value 本身的大小限制为key 最多32 byte ,value 最多 1024 byte。
  • 对每位已安装应用软件的用户,key-value 最多为 30 条。
  • 通过Client Credentials Grant 发送请求时,如果用户未安装此应用软件,响应代码反馈 400。
  • Appdata 生成或更新成功时,响应代码反馈 201。
  • Appdata 删除成功时,响应代码反馈 202。

样例​

Appdata 创建​

新建 Appdata 的示例如下。

请求格式​

POST /social/api/restful/v2/appdata/@me/@self/@app?format=json&fields=max_score,score
Content-Type: application/json; charset=utf8

{
"max_score":96,
"score":78
}

或、

POST /social/api/restful/v2/appdata/@me/@self/@app?format=json&fields=max_score,score
Content-Type: application/json; charset=utf8

{
"entry": [
{ "key":"max_score", "value":96 },
{ "key":"score", "value":78 }
]
}

或、

POST /social/api/restful/v2/appdata/@me/@self/@app?format=json&fields=max_score,score
Content-Type: application/json; charset=utf8

{
"entry": {
"max_score":96,
"score":78
}
}

响应格式

201 Created

指定关键字相应Appdata的获取​

仅限特定关键字,获取相应的 Appdata。

请求格式​

GET /social/api/restful/v2/appdata/@me/@self/@app?format=json&fields=score

响应格式​

200 OK

{
"entry":{
"sb.mbga.jp:10000":{
"score":"78"
}
}
}

指定关键字所相应Appdata 的删除​

仅限特定关键字,删除相应的 Appdata。

请求格式​

DELETE /social/api/restful/v2/appdata/@me/@self/@app?format=json&fields=score

响应格式

202 Accepted
{
"score":"78"
}

更新履历​

  • 2016/01/12
    • 对查询参数、注意事项和样例进行了修改。
  • 2015/12/02
    • 已支持Client Credentials Grant ,故对此做出补充。