跳到主要内容

TextData

概要​

获取和保存用户输入的自由文本所需的 API 。监控对象是已保存的文本。
需要事先创建TextData 对象分组所需的 TextDataGroup 对象。

TextData 对象字段

向TextData API 发送 GET 请求后,可获取 TextData 对象。

值说明类型补充
idTextData 对象的 idxs:string–
groupNameTextDataGroup 对象的 namexs:string–
parentId父 TextData 对象的 idxs:string–
writerId此数据写入人的 guidxs:string–
ownerId此数据所有者的 guidxs:string–
data文本数据xs:string最多2048byte
status逻辑状态值xs:int–
published生成时间xs:dateTimeGMT
updated更新时间xs:dateTimeGMT
备注

来自API 的响应中含有的 xsd:dateTime 类型格式中不含时区指定符。因此采用GMT(格林尼治标准时间)进行描述。

TextData#status 字段值​

status说明
0通常
11用户编辑
21操作员编辑
31合作伙伴编辑

TextDataGroup 对象字段​

向TextDataGroup API 发送 GET 请求后,可获取TextDataGroup 对象。

值说明类型补充
idTextDataGroup 对象的 idxs:string–
nameTextDataGroup 对象的名称xs:string最多32byte
appIdapplication 的 idxs:string–
parentId父 TextDataGroup 对象的 idxs: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说明
ownerIdTextData#ownerId
writerIdTextData#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说明
equalsfilterBy 中指定的字段与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说明
idTextData 的 id
updatedTextData的更新时间

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

sortOrder​

只有在获取 TextData 类集时,可使用sortOrder。

指定sortBy 和 sortOrder 后,可对响应反馈的 TextData 对象类集添加排序条件。可在sortOrder 值中指定排序时的升序和降序。

目前可指定的 sortOrder 值如下表所示。

sortOrder说明
ascending升序
descending降序

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

API 响应​

响应代码​

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

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

使用流程​

关于各功能的请求/响应格式示例,请见下述样例。

1. 合作伙伴创建 TextDataGroup。(Trusted)
2. 对创建的 TextDataGroup,可使用下述功能。(Trusted)

  • 获取TextDataGroup
  • 删除TextDataGroup
  1. 创建 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