User Chat Channel
概要
管理用户参加的频道以及频道与用户之间的相关信息所需的 API。
关于游戏聊天的使用方法,请见这里的教程。
- 1 个用户创建1 个聊天室,禁止只向特定用户发送信息(游戏通知)的行为。
- 1个应用软件可生成的频道最大条数为 1,000,000 条。
UserChatChannel 对象字段
表示用户参加频道的对象。
| 值 | 说明 | 类型 | 补充 |
|---|---|---|---|
| id | 频道 ID | xs:string | 表示频道的唯一性标识符 |
| unreadMessages | 未读条数 | xs:int | – |
| joined | 参加时间 | xs:date | 参加时间 (ISO8601, GMT格式) |
| updated | 更新时间 | xs:date | 更新时间 (ISO8601, GMT格式) |
API 请求
HTTP 方法
Authorization Code Grant
- GET 获取用户参加的频道列表,获取用户参加的频道
Client Credentials Grant
- GET 不支持。
端点 URL
-
Sandbox 环境
https://sb-app.mobage.jp/social/api/restful/v2/people/{userId}/{groupId}/channels/{-prefix|/|channelId} -
正式环境
https://app.mobage.jp/social/api/restful/v2/people/{userId}/{groupId}/channels/{-prefix|/|channelId}
URI Template 参数
userId
userId 参数,指定下述任意一项的值。
| 值 | 说明 | 备注 |
|---|---|---|
| @me | 与viewer 的用户ID同义 | 必须 |
groupId
在groupId 参数中,指定下述任意一项的值。
| 值 | 说明 | 备注 |
|---|---|---|
| @self | 对userId 参数指定的用户本人个人简介信息的条目资源 | 必須 |
channelId
在channelId 参数中,指定下述任意一项的值。
| 值 | 说明 | 备注 |
|---|---|---|
| {channelId} | 频道 ID | 任意 |
查询参数
可指定下述查询参数。
format
可指定响应格式。
| 值 | 说明 | 备注 |
|---|---|---|
| json | "application/json; charset=utf8" | 任意、默认值 |
fields
可指定想要获取的频道信息。关于可指定的字段名,请参见 UserChatChannel 对象字段。
要指定多个时,使用不带空格的逗号 (,) 分隔指定。
省略fields 参数时,获取下述全部属性信息。
为提高性能,请尽量只获取必要的属性。
count
获取类集资源的响应时,可指定最多可获取的条目资源条数。
默认值为 50 条,最多可指定1000条。
为提高性能,请尽量只获取必要的条数。
startIndex
指定类集资源的开始值。省略时,自动指定 1。
sortBy
只有在获取 UserChatChannel 类集时,可使用sortBy。
指定sortBy 和 sortOrder 后,可对响应反馈的 UserChatChannel 对象类集添加排序条件。可在sortBy 值中指定排序的关键字段。
目前可指定的 sortBy 值如下表所示。
| sortBy | 说明 |
|---|---|
| updated | UserChatChannel 的更新时间 |
要指定sortBy ,需要已指定sortOrder。
sortOrder
只有在获取类集时 UserChatChannel ,可使用sortOrder。
指定sortBy 和 sortOrder 后,可对响应反馈的 UserChatChannel 对象类集添加排序条件。可在sortOrder 值中指定排序时的升序和降序。
目前可指定的 sortOrder 值如下表所示。
| sortOrder | 说明 |
|---|---|
| ascending | 升序 |
| descending | 降序 |
要指定sortOrder ,需要已指定sortBy 。
API响应
响应代码
API 的响应代码为以下中的任意一项。
| 请求 HTTP 方法 | 响应代码 | 响应信息 | 说明 |
|---|---|---|---|
| GET | 200 | OK | 获取参加人成功时 |
| GET | 400 | Bad Request | 数据格式不当时 |
| GET | 401 | Unauthorized | Authorization 报头不当时 |
| GET | 403 | Forbidden | 试图执行的操作无权限时 |
| GET | 404 | Not Found | 指定的 userId, channelId不存在时 |
| GET | 500 | Internal Server Error | 服务器端的处理出错时 |
| GET | 503 | Service Unavailable | 服务器端暂停服务时 |
样例
获取用户已参加的频道列表
请求格式
GET /social/api/restful/v2/people/@me/@self/channels?count=50&fields=id%2Cupdated&sortBy=updated&sortOrder=descending&startIndex=1
响应格式
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"entry" : [
{
"id" : "123",
"updated" : "2013-04-11T13:20:52"
},
{
"id" : "163",
"updated" : "2013-04-11T10:34:12"
}
],
"itemsPerPage" : 50,
"startIndex" : 1,
"totalResults" : 2
}
获取用户已参加的频道
请求格式
GET /social/api/restful/v2/people/@me/@self/channels/100?fields=id%2CunreadMessages%2Cupdated
响应格式
200 OK HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"id" : "100",
"unreadMessages" : 12,
"updated" : "2013-04-11T10:31:10"
}