TextData
概要
获取和保存用户输入的自由文本所需的 API 。监控对象是已保存的文本。
需要事先创建TextData 对象分组所需的 TextDataGroup 对象。
TextData 对象字段
向TextData API 发送 GET 请求后,可获取 TextData 对象。
| 值 | 说明 | 类型 | 补充 |
|---|---|---|---|
| id | TextData 对象的 id | xs:string | – |
| groupName | TextDataGroup 对象的 name | xs:string | – |
| parentId | 父 TextData 对象的 id | xs:string | – |
| writerId | 此数据写入人的 guid | xs:string | – |
| ownerId | 此数据所有者的 guid | xs:string | – |
| data | 文本数据 | xs:string | 最多2048byte |
| status | 逻辑状态值 | xs:int | – |
| published | 生成时间 | xs:dateTime | GMT |
| updated | 更新时间 | xs:dateTime | GMT |
来自API 的响应中含有的 xsd:dateTime 类型格式中不含时区指定符。因此采用GMT(格林尼治标准时间)进行描述。
TextData#status 字段值
| status | 说明 |
|---|---|
| 0 | 通常 |
| 11 | 用户编辑 |
| 21 | 操作员编辑 |
| 31 | 合作伙伴编辑 |
TextDataGroup 对象字段
向TextDataGroup API 发送 GET 请求后,可获取TextDataGroup 对象。
| 值 | 说明 | 类型 | 补充 |
|---|---|---|---|
| id | TextDataGroup 对象的 id | xs:string | – |
| name | TextDataGroup 对象的名称 | xs:string | 最多32byte |
| appId | application 的 id | xs:string | – |
| parentId | 父 TextDataGroup 对象的 id | xs:string | – |
API 请求
HTTP 方法
Authorization Code Grant
- GET
- 获取文本数据列表
- 获取文本数据
- 获取文本数据组列表
- POST
- 创建文本数据
- PUT
- 更新文本数据
- DELETE
- 删除文本数据
Client Credentials Grant
- GET
- 获取文本数据组列表
- 获取文本数据组
- 获取文本数据
- POST
- 创建文本数据组
- 创建文本数据
- PUT
- 更新文本数据
- DELETE
- 删除文本数据组
- 删除文本数据
如果使用Client Credentials Grant,那么在非 Mobage 会员状态下也能进行文本数据的创建、更新和删除,但请勿在非Mobage会员状态下进行获取文本数据之外的操作。
端点 URL
-
Sandbox 环境
https://sb-app.mobage.jp/social/api/restful/v2/textdata/{appid}/{gid}{-prefix|/|selector}正式环境
https://app.mobage.jp/social/api/restful/v2/textdata/{appid}/{gid}{-prefix|/|selector}URI Template 参数
appid
在appid 参数中,指定下述任意一项的值。
值 说明 备注 @app 当前执行的 application id 必须
gid
在gid 参数中,指定下述任意一项的值。
| 值 | 说明 | 備考 |
|---|---|---|
| @all | 表示所有文本数据组 | 任意 |
| {gid} | 指定文本数据分类的 gid 值 (TextDataGroup.name 字段值) 。是展示文本数据列表的类集资源。 | 任意 |
selector
在selector 参数中,指定下述任意一项的值。
| 值 | 说明 | 备注 |
|---|---|---|
| @self | 指定的文本数据组条目。 | 任意 |
| @all | 指定的文本数据组所属的文本数据类集。 | 任意 |
| @all/{-join | ; | textDataId} |
对{textDataId},使用分号分隔指定多个 TextData#id ,可获取TextData 类集资源。
查询参数
可指定下述查询参数。
format
可指定响应格式。
| 值 | 说明 | 备注 |
|---|---|---|
| json | "application/json; charset=utf8" | 任意、默认值 |
fields
可指定想要获取的 TextData 信息。关于可指定的字段名,请参见 TextData 对象字段。
要多个指定时,使用不带空格的逗号 (,) 分隔指定。
省略fields 参数时,获取下述全部属性信息。
为提高性能,请尽量只获取必要的属性。
count
获取类集资源的响应时,可指定最多可获取的条目资源条数。在selector 中已指定 @all 时或已指定多个 TextData#id 时,可指定此项。
默认值为 50 条,最多可指定1000条。
为提高性能,请尽量只获取必要的条数。
startIndex
指定类集资源的开始值。省略时,指定为 1。另外,获取 TextDataGroup 的类集资源时, startIndex指定忽略 ,默认为 1。
filterBy
只有在获取 TextData 类集时,可使用filterBy。
指定filterBy 后,可对响应反馈的 TextData 对象类集添加搜索条件。在filterBy 值中,指定搜索条件的关键字段。
目前可指定的 filterBy 值如下表所示。
| filterBy | 说明 |
|---|---|
| ownerId | TextData#ownerId |
| writerId | TextData#writerId |
要指定filterBy,需要已指定filterOp, filterValue。
另外,想要同时使用ownerId, writerId 时,需要使用 ',' (逗号) 分隔。
例如,想要同时对ownerId (guid:5), writerId (guid:10) 施加指定的 filter 时,
GET /api/restful/textdata/@app/messageboard/@all?count=10&startIndex=11&filterBy=ownerId,writerId&filterOp=equals,equals&filterValue=5,10
如上所述,访问 API。
filterOp
只有在获取TextData 类集时,可使用filterOp。
指定filterOp 后,可对响应反馈的 TextData 对象类集添加搜索条件。在filterOp 值中,指定对搜索条件的关键字和值的评价方式。
目前可指定的 filterOp 值如下表所示。
| filterOp | 说明 |
|---|---|
| equals | filterBy 中指定的字段与filterValue中指定的值是否一致? |
要指定filterOp ,需要已指定filterBy, filterValue。
filterBy 中指定有多个字段时,需要使用相应数量的 ',' (逗号) 分隔指定 filterOp 值。
filterValue
只有在获取 TextData 类集时,可使用filterValue。
指定filterValue 后,可对响应反馈的 TextData 对象类集添加搜索条件。可在filterValue 值中对搜索条件的关键字指定评价值。
目前可指定的 filterValue 值如下表所示。
| filterValue | 说明 |
|---|---|
| {guid} | guid 的值 (整数值) |
要指定filterValue ,需要已指定filterBy, filterOp。
filterBy 中指定有多个字段时,需要用相应数量的 ',' (逗号) 分隔指定 filterValue 值。
sortBy
只有在获取TextData 类集时,可使用sortBy。
指定sortBy 和 sortOrder 后,可对响应反馈的 TextData 对象类集添加排序条件。可在sortBy 值中指定排序的关键字段。
目前可指定的 sortBy 值如下表所示。
| sortBy | 说明 |
|---|---|
| id | TextData 的 id |
| updated | TextData的更新时间 |
要指定sortBy ,需要已指定sortOrder。
sortOrder
只有在获取 TextData 类集时,可使用sortOrder。
指定sortBy 和 sortOrder 后,可对响应反馈的 TextData 对象类集添加排序条件。可在sortOrder 值中指定排序时的升序和降序。
目前可指定的 sortOrder 值如下表所示。
| sortOrder | 说明 |
|---|---|
| ascending | 升序 |
| descending | 降序 |
要指定sortOrder ,需要已指定sortBy。
API 响应
响应代码
API 的响应代码为以下中的任意一项。
| 请求 HTTP 方法 | 响应代码 | 响应信息 | 说明 |
|---|---|---|---|
| GET | 200 | OK | 数据获取正常完成 |
| POST | 201 | Created | 数据生成成功 |
| PUT/DELETE | 202 | Accepted | 数据更新或删除成功 |
| GET/PUT/DELETE | 404 | Not Found | 数据不存在,或已被物理删除 |
| GET/PUT/DELETE | 403 | Forbidden | 由于认证错误以外的原因导致不能访问的情况 |
| GET/POST/PUT/DELETE | 400 | Bad Request | 请求数据不当 |
| GET/POST/PUT/DELETE | 401 | Unauthorized | OAuth 验证失败 |
| GET/POST/PUT/DELETE | 405 | Method Not Allowed | 方法不允许 |
| GET/POST/PUT/DELETE | 500 | Internal Server Error | API 端的问题导致失败 |
使用流程
关于各功能的请求/响应格式示例,请见下述样例。
1. 合作伙伴创建 TextDataGroup。(Trusted)
2. 对创建的 TextDataGroup,可使用下述功能。(Trusted)
- 获取TextDataGroup
- 删除TextDataGroup
- 创建 TextDataGroup 所属的 TextData 条目。(Trusted/Proxy)
4. 对创建的 TextData 条目,可使用下述功能。(Trusted/Proxy)
- 获取TextData
- 更新TextData
- 删除TextData
注意事项
- 请通过 Trusted Model (OAuth Consumer Request) 访问 API,对TextDataGroup 进行管理
- TextDataGroup#name 值只能使用英文数字和下划横线。
- TextDataGroup#parentId, TextData#parentId 为了表达父子关系,添加了从子方角度来看的父方 id 值。这是监控所需,因此如有具有父子关系的数据结构,请务必添加。
- 请在 TextData#data 字段中添加可进行语句判断的字符串。如果不能识别,可能会被操作员删除,敬请注意。
- TextData#data 字段中含有违反平台运营政策的禁用词时,添加和更新TextData 条目时会发生 400 Bad Request。
- TextData#writerId 中带有发帖用户的 guid。guid 的数值部分为 0 时,视为合作伙伴的 Trusted Model 更新数据。
- 请合作伙伴对非 TextData#writerId 的用户可能会试图更新的 TextData 进行访问权限的控制。在API 端,非 TextData#writerId 时也会更新。
- 例如,使用 WiKi 之类的格式时,可能会有多人对同一数据进行更新。
- TextData#ownerId 是为表现原所有者或父数据的所有者等所准备的字段。在对所有者的条目或 使用Trusted Model 的条目中,请务必设置。
- 例如,任意的用户在按用户分配的留言板中发帖时,所有者就是被分配到留言板的用户,因此在TextData#ownerId中设置所有者的ID。
- TextData#ownerId 的用户已将 viewer 拉黑时,请设定使其不能使用BlackList API 进行发帖。
- 请将 TextData#data 的大小限制在 2048 byte 以内。
- 对指定有多个 TextData#id 的GET ,请只指定同一群组中的 id。不能获取不同群组所属的 id。
- 对已删除的 TextData,不再能通过 GET 获取条目。(反馈404 Not Found)
- 用户未安装此应用软件时,响应代码反馈 403。
- POST 时不含 ownerId 和 parentId 值时,初始值反馈 0。
限制事项
- 1个应用软件可创建5 个 TextDataGroup。
- 应用软件的安装用户数不超过 10,000 用户时,各 TextDataGroup 中可存储的最大条数为 100,000 条。
- 至前一日为止安装了应用的用户数超过 10,000 时,最大条数为至前一日为止的安装用户数的合计 × 10 条。
- 超出最大条数时,从群组所属条目中最早的条目起会随时进行物理删除。(反馈404 Not Found)
- 请勿在1个TextDataGroup ID中管理多个类别所属的TextData。(例如,请将“打招呼”功能的发帖内容和“作战会议”功能的发帖内容分别作为不同的TextDataGroup ID。又如,要在“作战会议”的发帖格式中使用其他column输入“标题”和“作战内容”这2项时,请作为1个TextDataGroup ID。)
- 不支持 Unicode6.0(iOS终端表情符号)。字符代码的输入输出均为 UTF-8。
样例
添加TextDataGroup
添加新 TextDataGroup 的示例。
请求格式
POST /api/restful/v2/textdata/@app/@all
Content-Type: application/json; charset=utf8
{
"name": "diary"
}
响应格式
201 Created
删除TextDataGroup
请求格式
DELETE /api/restful/v2/textdata/@app/diary/@self
响应格式
202 Accepted
获取TextDataGroup 类集
下面是对TextDataGroup 类集使用count, startIndex 查询参数的示例。
请求格式
GET /api/restful/v2/textdata/@app/@all?count=2&startIndex=1
响应格式
{
"entry" : [
{
"parentId" : "0",
"appId" : "12000002",
"name" : "diary",
"id" : "1"
},
{
"parentId" : "0",
"appId" : "12000002",
"name" : "bbs",
"id" : "2"
}
],
"startIndex" : 1,
"itemsPerPage" : 2,
"totalResults" : 5
}
获取TextDataGroup
请求格式
GET /api/restful/v2/textdata/@app/diary/@self
响应格式
200 OK
Content-Type: application/json; charset=utf8
{
"startIndex" : 1,
"textDataGroup" : {
"parentId" : "0",
"appId" : "12000002",
"name" : "diary",
"id" : "1"
},
"itemsPerPage" : 1,
"totalResults" : 1
}
从群组获取 TextData 类集
请求格式
GET /api/restful/v2/textdata/@app/diary/@all?count=5&fields=id,data
响应格式
{
"entry" : [
{
"id" : "1",
"data" : "今天的晚饭"
},
{
"id" : "2",
"data" : "抓住了milasister"
},
{
"id" : "3",
"data" : "montra有趣"
},
{
"id" : "4",
"data" : "被nunuenba的图片震惊了!!!"
},
{
"id" : "5",
"data" : "试了一下爆裂运"
}
],
"startIndex" : 1,
"itemsPerPage" : 5,
"totalResults" : 8
}
指定多个TextData#id 获取 TextData 条目
请求格式
GET /api/restful/v2/textdata/@app/messages/@all/100;1107;1108?format=json
响应格式
{
"entry" : [
{
"status" : "0",
"data" : "已经无限1up了",
"writerId" : "sb.mbga.jp:10001",
"published" : "2010-01-19T06:29:57",
"parentId" : "0",
"id" : "1107",
"updated" : "2010-01-19T06:29:57",
"groupName":"messages",
"ownerId" : "sb.mbga.jp:0"
},
{
"status" : "0",
"data" : "我想越过这根竿子!",
"writerId" : "sb.mbga.jp:12003",
"published" : "2010-01-19T06:30:03",
"parentId" : "0",
"id" : "1108",
"updated" : "2010-01-19T06:30:03",
"groupName":"messages",
"ownerId" : "sb.mbga.jp:0"
}
],
"startIndex" : 1,
"itemsPerPage" : 50,
"totalResults" : 2
}
创建TextData 条目
下面是在 diary TextDataGroup 中新添加 TextData 条目的示例。
例) 10009 用户在应用日记中发帖时
请求格式
POST /api/restful/v2/textdata/@app/diary/@all
Content-Type: application/json; charset=utf8
{
"data" : "怪盗王也在玩"
}
响应格式
201 Created
Location: /api/restful/v2/textdata/@app/diary/@all/19
"published" : "2009-12-09T06:39:01",
"writerId" : "10009",
"updated" : "2009-12-09T06:39:01",
"id" : "19",
"groupName" : "diary",
"data" : "怪盗王也在玩"
例) 10012 用户对10009 用户的日记发言时
请求格式
POST /api/restful/v2/textdata/@app/diary/@all
Content-Type: application/json; charset=utf8
{
"data" : "我也在玩",
"ownerId" : "10009"
}
响应格式
201 Created
Location: /api/restful/v2/textdata/@app/diary/@all/44
"published" : "2009-12-09T08:42:23",
"writerId" : "sb.mbga.jp:10012",
"updated" : "2009-12-09T08:42:23",
"id" : "44",
"parentId" : "19",
"groupName" : "diary",
"data" : "我也在玩",
"ownerId" : "sb.mbga.jp:10009"
获取TextData 条目
请求格式
GET /api/restful/v2/textdata/@app/diary/@all/5
响应格式
"status": 0,
"data" : "试了一下爆裂运",
"writerId" : "sp.mbga.jp:10012",
"published":"2009-11-26T12:59:29",
"parentId" : "0",
"id" : "5",
"updated" : "2009-11-26T12:59:29",
"groupName" : "diary",
"ownerId" : "sp.mbga.jp:0"
更新TextData 条目
请求格式
PUT /api/restful/v2/textdata/@app/diary/@all/5
Content-Type: application/json; charset=utf8
{
"data": "到Lv30 了"
}
响应格式
202 Accepted
删除TextData 条目
请求格式
DELETE /api/restful/v2/textdata/@app/diary/@all/5
响应格式
404 Not Found