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 格式的描述
以下描述均为同一对象。
- 完整描述
{
"entry": [
{ "key": "score", "value": "78" },
{ "key": "high_score", "value": "97" }
]
}
2.仅简要描述 Appdata Entry
{
"entry": [
{ "score": "78" },
{ "high_score": "97" }
]
}
- 简要描述 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 参数中,指定以下任意一项的值。
| 值 | 说明 | 备注 |
|---|---|---|
| @me | viewer の 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 方法 | 响应代码 | 响应信息 | 说明 |
|---|---|---|---|
| GET | 200 | OK | Appdata 获取正常完成 |
| POST/PUT | 201 | Created | Appdata 生成和更新成功 |
| DELETE | 202 | Accepted | Appdata 删除成功 |
| GET/POST/PUT/DELETE | 400 | Bad Request | 请求数据不当 |
| GET/POST/PUT/DELETE | 401 | Unauthorized | OAuth 验证失败 |
| GET/POST/PUT/DELETE | 403 | Forbidden | 由于认证错误以外的原因导致不能访问的情况 |
| GET/POST/PUT/DELETE | 405 | Method Not Allowed | 方法不允许 |
| GET/POST/PUT/DELETE | 500 | Internal Server Error | API 端的问题导致失败 |
注意事项
- 不指定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 ,故对此做出补充。