Chat Member
概要
为对聊天参加人进行管理的 API 。
信息
关于游戏聊天的使用方法,请见这里的教程。
注意
- 1 个用户创建1 个聊天室,禁止只向特定用户发送信息(游戏通知)的行为。
- 1个应用软件可生成通道的最大条数为 1,000,000 条。
ChatMember 对象字段
表示参加人的对象。
| 值 | 说明 | 类型 | 补充 |
|---|---|---|---|
| id | 全局对象 ID | xs:string | 格式为 id = objectType + ':' + localId |
| objectType | ChatMember 对象的类型 | xs:string | 只能指定"person" |
| localId | 本地 ID | xs:string | 按objectType 分配的唯一性标识符(与People 的 userId 的 localId 同义) |
| joined | 参加时间 | xs:date | 参加时间 (ISO8601, GMT格式) |
API 请求
HTTP 方法
Authorization Code Grant
- GET 获取参加人列表,获取参加人
- POST 添加参加人
- DELETE 删除参加人
Client Credentials Grant
- GET 获取参加人列表,获取参加人
- POST 添加参加人
- DELETE 删除参加人
端点 URL
-
Sandbox 环境
https://sb-app.mobage.jp/social/api/restful/v2/chat/{appId}/channels/{channelId}/members/{-prefix|/|id}正式环境
https://app.mobage.jp/social/api/restful/v2/chat/{appId}/channels/{channelId}/members/{-prefix|/|id}
URI Template 参数
appId
在appId 参数中,指定下述任意一项的值。
| 值 | 说明 | 备注 |
|---|---|---|
| @app | 当前执行的应用软件 ID | 必须 |
channelId
在channelId 参数中,指定下述任意一项的值。
| 值 | 说明 | 备注 |
|---|---|---|
| {channelId} | 通道 ID | 必须 |
id
在id 参数中,指定下述任意一项的值。
| 值 | 说明 | 备注 |
|---|---|---|
| {id} | ChatMember 对象的 ID | 任意 |
查询参数
可指定下述查询参数。
format
可指定响应格式。
| 值 | 说明 | 备注 |
|---|---|---|
| json | "application/json; charset=utf8" | 任意、默认值 |
fields
可指定想要获取的通道信息。关于可指定的字段名,请参见 ChatMember 对象字段。
要指定多个时,使用不带空格的逗号 (,) 分隔指定。
省略fields 参数时,获取下述全部属性信息。
为提高性能,请尽量只获取必要的属性。
count
获取类集资源的响应时,可指定最多可获取的条目资源条数。
默认值为 50 条,最多可指定1000条。
为提高性能,请尽量只获取必要的条数。
startIndex
指定类集资源的开始值。省略时,自动指定 1。
sortBy
只有在获取ChatMember 类集时,可使用sortBy。
指定sortBy 和 sortOrder 后,可对响应反馈的 ChatMember 对象类集添加排序条件。可在sortBy 值中指定排序的关键字段。
目前可指定的 sortBy 值如下表所示。
| sortBy | 说明 |
|---|---|
| joined | ChatMember 的参加时间 |
要指定sortBy ,需要已指定sortOrder。
sortOrder
只有在获取 Channel 类集时,可使用sortOrder。
指定sortBy 和 sortOrder 后,可对响应反馈的 ChatMember 对象类集添加排序条件。可在sortOrder 值中指定排序时的升序和降序。
目前可指定的 sortOrder 值如下表所示。
| sortOrder | 说明 |
|---|---|
| ascending | 升序 |
| descending | 降序 |
要指定sortOrder ,需要已指定sortBy。
API 响应
API 的响应代码为以下中的任意一项。
| 请求 HTTP 方法 | 响应代码 | 响应信息 | 说明 |
|---|---|---|---|
| GET | 200 | OK | 获取参加人成功时 |
| POST | 201 | Created | 添加参加人成功时 |
| DELETE | 204 | No Content | 添加/删除参加人成功时 |
| POST/DELETE | 207 | Multi-Status | 添加/删除多个参加人成功时 |
| GET/POST/DELETE | 400 | Bad Request | 数据格式不当时 |
| GET/POST/DELETE | 401 | Unauthorized | Authorization 报头不当时 |
| GET/POST/DELETE | 403 | Forbidden | 试图执行的操作无权限时 |
| GET/POST/DELETE | 404 | Not Found | 指定的 appId, channelId, id 不存在时 |
| POST | 409 | Conflict | 试图添加已存在的成员时 |
| POST | 422 | Unprocessable Entity | 试图添加第101位以上的成员时 |
| GET/POST/DELETE | 500 | Internal Server Error | 服务器端的处理出错时 |
| GET/POST/DELETE | 503 | Service Unavailable | 服务器端暂停服务时 |
样例
获取参加人列表
请求格式
GET /social/api/restful/v2/chat/@app/channels/100/members?count=50&fields=id%2CobjectType%2ClocalId%2Cjoined&sortBy=joined&sortOrder=descending&startIndex=1
响应格式
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"entry" : [
{
"id" : "person:11030",
"objectType" : "person",
"localId" : "11030",
"joined" : "2013-03-30T21:21:26"
},
{
"id" : "person:11031",
"objectType" : "person",
"localId" : "11031",
"joined" : "2013-03-30T18:34:46"
}
],
"itemsPerPage" : 50,
"startIndex" : 1,
"totalResults" : 2
}
获取参加人
请求格式
GET /social/api/restful/v2/chat/@app/channels/100/members/person%3A11031?fields=id%2CobjectType%2ClocalId%2Cjoined
响应格式
200 OK HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"id" : "person:11031",
"objectType" : "person",
"localId" : "11031",
"joined" : "2013-03-30T18:38:16"
}
添加参加人
请求格式
POST /social/api/restful/v2/chat/@app/channels/110/members
Content-Type: application/json; charset=utf8
{
"objectType" : "person",
"localId" : "34127"
}
响应格式
201 Created
Content-Type: application/json; charset=utf-8
{
"id" : "person:34127",
"objectType" : "person",
"localId" : "34127",
"joined" : "2013-03-30T15:15:21"
}
添加多个参加人
请求格式
POST /social/api/restful/v2/chat/@app/channels/110/members
Content-Type: application/json; charset=utf8
[
{
"objectType" : "person",
"localId" : "34127"
},
{
"objectType" : "person",
"localId" : "67349"
}
]
响应格式
207 Multi-Status
Content-Type: application/json; charset=utf-8
[
{
"id" : "person:34127",
"status" : 201,
"entity" : {
"id" : "person:34127",
"objectType" : "person",
"localId" : "34127",
"joined" : "2013-04-08T13:13:44"
}
},
{
"id" : "person:67349",
"status" : 409
}
]
删除参加人
请求格式
DELETE /social/api/restful/v2/chat/12000129/channels/768/members/person%3A11231
响应格式
204 No Content
删除多个参加人
请求格式
DELETE /social/api/restful/v2/chat/12000129/channels/273/members/person%3A11231,person%3A11461,person%3A53411
响应格式
207 Multi-Status
Content-Type: application/json; charset=utf8
[
{
"id" : "person:11231",
"status" : 204
},
{
"id" : "person:11461",
"status" : 404
},
{
"id" : "person:53411",
"status" : 204
}
]