聊天室队列元素管理
更新时间: 2024/07/17 17:57:35
网易云信 IM 支持聊天室队列中的元素管理功能。
通过定义队列中 key 和 value 的值,来定义聊天室队列中的元素,可以对元素进行多样化的管理。
API 使用限制
目前聊天室队列通知(消息)的接收,有以下流控机制。
-
针对普通通知(消息),聊天室用户每秒至多可接收 20 条,超过部分会因为流控随机丢弃。为避免丢失重要消息(通常为服务端消息),可将下文请求参数中的
highPriority
参数设置为true
实现高优先级接收服务端消息,进而保证高优先级消息流控上限内的重要消息不丢失。 - 针对高优先级通知(消息),每秒至多接收 10 条,超过部分无法保证不丢失。可通过下文请求参数中的
highPriorityPolicy
参数设置超出限制后自动转为普通消息或者超出后返回 416 错误码。
添加或更新元素
功能描述
用户可以在聊天室有序队列中添加或更新元素。
若该元素由用户 A 添加,之后再由用户 B 更新,则该元素的所有者为用户 B。
URL
POST https://api.netease.im/nimserver/chatroom/queueOffer.action HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=utf-8
请求参数
- POST 请求中 Headers 的设置请参考接口概述。
- POST 请求中 Body 的设置如下:
参数 | 类型 | 必须 | 说明 |
---|---|---|---|
roomid | Long | 是 | 聊天室 ID |
key | String | 是 | elementKey,新元素的 UniqKey,最大长度 128 位字符 |
value | String | 是 | elementValue,新元素内容,最大长度 4096 位字符 |
operator | String | 否 | 提交新元素的操作者,accid,默认为该聊天室的创建者
|
transient | Boolean | 否 | 当该新元素的提交者 operator 的所有聊天室连接从该聊天室掉线或者离开该聊天室时,提交的元素是否需要删除 true:需要删除;false:不需要删除(默认) 当指定该参数为 true 时,若 operator 当前不在该聊天室内,则会返回 302 错误 |
highPriority | Integer | 否 | 是否设置为高优先级消息 0:否(默认);1:是高优先级消息 |
highPriorityPolicy | Integer | 否 | 高优先级消息策略:针对高优先级消息,超过流控后是自动降级为普通消息还是直接返回 416 错误码 0:降级为普通消息(默认);1:返回 416 错误码 |
示例
请求示例(curl)
curlcurl -X POST -H "CheckSum: 32dc17d0190f37***9bbf049c9367e7" -H "AppKey: fe416640***47ad2547" -H "Nonce: 1" -H "CurTime: 1451200147" -H "Cache-Control: no-cache" -H "Postman-Token: b9550dce-74c1-9606-0084-71dd8ec201b6" -H "Content-Type: application/x-www-form-urlencoded" -d 'roomid=36&key=1111&value=66666' "https://api.netease.im/nimserver/chatroom/queueOffer.action"
请求成功返回示例
json"Content-Type": "application/json; charset=utf-8"
{
"desc": {
},
"code": 200
}
请求失败返回示例
"Content-Type": "application/json; charset=utf-8"
{
"code": 414, // 参数错误
"desc": "roomid not exsit"
}
状态码
该接口在 HTTPS Body 中返回请求的状态码,以下仅列出与接口业务相关的状态码。完整状态码请参见状态码。
状态码 | 说明 | 处理建议 |
---|---|---|
200 | 请求成功 | - |
302 | operator 当前不在该聊天室内 | - |
403 | 禁止操作: 未开启聊天室权限 |
开通聊天室功能 |
404 | operator 对应的帐号不存在 | - |
414 | 参数错误 | 根据提示信息,检查传入参数的格式和限制条件 |
416 | 频控限制或异常错误 | 降低访问频率 |
500 | 服务出错 | - |
批量添加队列元素
功能描述
用户可以在聊天室队列中批量添加元素。
- 若聊天室队列未初始化,则自动初始化队列,并收到队列初始化抄送信息。
- 若队列元素所属账号不在线且非聊天室创建者,则添加元素失败。
URL
POST https://api.netease.im/nimserver/chatroom/queueBatchOffer.action HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=utf-8
请求参数
- POST 请求中 Headers 的设置请参考接口概述。
- POST 请求中 Body 的设置如下:
参数 | 类型 | 必须 | 说明 |
---|---|---|---|
roomid | Long | 是 | 聊天室 ID |
operator | String | 否 | 批量添加队列元素的操作者,accid,不填默认为聊天室创建者 |
transient | Boolean | 否 | 队列元素所有者掉线或者离开该聊天室时,提交的元素是否需要删除 true:需要删除;false:不需要删除(默认)
|
elements | String | 是 | 队列元素,JSONArray,最多 20 个 格式如下: [ { "key": "key01", //元素key "value": "{\"priority\":10}", //元素value "accid":"user01", //元素所属账号 //accid不填则默认是operator "transient":true //离开聊天室是否删除元素 //transient不填则默认是transient参数 } ] |
needNotify | Boolean | 否 | 是否需要发送更新通知事件,true(默认)或 false |
notifyExt | String | 否 | 通知事件扩展字段,最大长度 2048 位字符 |
highPriority | Integer | 否 | 是否设置为高优先级消息 0:否(默认);1:是高优先级消息 |
highPriorityPolicy | Integer | 否 | 高优先级消息策略:针对高优先级消息,超过流控后是自动降级为普通消息还是直接返回 416 错误码 0:降级为普通消息(默认);1:返回 416 错误码 |
示例
请求示例(curl)
curlcurl -X POST -H 'appkey: fe416640***47ad2547' -H 'cache-control: no-cache' -H 'checksum: 18f54***f75265495034' -H 'content-type: application/x-www-form-urlencoded' -H 'curtime: 1508481877' -H 'nonce: 12345' --data-urlencode 'roomid=64' --data-urlencode 'operator=user01' --data-urlencode 'transient=false' --data-urlencode 'needNotify=false' --data-urlencode 'elements=[{"key":"key01","value":"{\"priority\":10}","accid":"user01","transient":true}]' "https://api.netease.im/nimserver/chatroom/queueBatchOffer.action"
请求成功返回示例
json
"Content-Type": "application/json; charset=utf-8"
{
"code": 200,
"desc": {
}
}
json
"Content-Type": "application/json; charset=utf-8"
{
"code": 200,
"desc": {
"failedKeys": [ //添加失败的元素key
"key01"
]
}
}
请求失败返回示例
"Content-Type": "application/json; charset=utf-8"
{
"code": 414, // 参数错误
"desc": "roomid not exsit"
}
状态码
该接口在 HTTPS Body 中返回请求的状态码,以下仅列出与接口业务相关的状态码。完整状态码请参见状态码。
状态码 | 说明 | 处理建议 |
---|---|---|
200 | 请求成功 | - |
403 | 禁止操作: 未开启聊天室权限 |
开通聊天室功能 |
414 | 参数错误 | 根据提示信息,检查传入参数的格式和限制条件 |
416 | 频控限制或异常错误 | 降低访问频率 |
500 | 服务出错 | - |
批量更新队列元素
功能描述
用户可以在聊天室队列中批量更新元素。
若该元素由用户 A 添加,之后再由用户 B 更新,则该元素的所有者为用户 B。
URL
POST https://api.netease.im/nimserver/chatroom/queueBatchUpdateElements.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8
请求参数
- POST 请求中 Headers 的设置请参考接口概述。
- POST 请求中 Body 的设置如下:
参数 | 类型 | 必须 | 说明 |
---|---|---|---|
roomid | Long | 是 | 聊天室 ID |
operator | String | 是 | 批量更新元素的操作者,accid,必须是管理员或创建者 |
elements | String | 是 | 更新的元素 key-value 对,最多 200 个 示例:{"k1":"v1","k2":"v2"} |
needNotify | String | 否 | 是否需要发送更新通知事件,true(默认)或 false |
notifyExt | String | 否 | 通知事件扩展字段,最大长度 2048 位字符 |
highPriority | Integer | 否 | 是否设置为高优先级消息 0:否(默认);1:是高优先级消息 |
highPriorityPolicy | Integer | 否 | 高优先级消息策略:针对高优先级消息,超过流控后是自动降级为普通消息还是直接返回 416 错误码 0:降级为普通消息(默认);1:返回 416 错误码 |
示例
请求示例(curl)
curlcurl -X POST -H 'appkey: fe4166***47ad2547' -H 'cache-control: no-cache' -H 'checksum: 18f5435a***75265495034' -H 'content-type: application/x-www-form-urlencoded' -H 'curtime: 1508481877' -H 'nonce: 12345' -d 'roomid=18&operator=zhouliangwei&elements=%7b%22k1%22%3a%22v1%22%2c%22k2%22%3a%22v2%22%7d' "https://api.netease.im/nimserver/chatroom/queueBatchUpdateElements.action"
请求成功返回示例
json
"Content-Type": "application/json; charset=utf-8"
{
"code": 200,
"desc":{
"noExistElementKey":[
"k1"
]
}
}
请求失败返回示例
"Content-Type": "application/json; charset=utf-8"
{
"code": 414, // 参数错误
"desc": "roomid not exsit"
}
状态码
该接口在 HTTPS Body 中返回请求的状态码,以下仅列出与接口业务相关的状态码。完整状态码请参见状态码。
状态码 | 说明 | 处理建议 |
---|---|---|
200 | 请求成功 | - |
403 | 禁止操作: |
根据对应提示信息做出处理 |
414 | 参数错误 | 根据提示信息,检查传入参数的格式和限制条件 |
416 | 频控限制或异常错误 | 降低访问频率 |
500 | 服务出错 | - |
排序列出队列中所有元素
URL
POST https://api.netease.im/nimserver/chatroom/queueList.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8
请求参数
- POST 请求中 Headers 的设置请参考接口概述。
- POST 请求中 Body 的设置如下:
参数 | 类型 | 必须 | 说明 |
---|---|---|---|
roomid | long | 是 | 聊天室id |
示例
请求示例(curl)
curlcurl -X POST -H "CheckSum: 37dc87d***kbf049c9367e7" -H "AppKey: fe416640c8e8a7***47ad2547" -H "Nonce: 1" -H "CurTime: 1451200147" -H "Content-Type: application/x-www-form-urlencoded" -d 'roomid=36' "https://api.netease.im/nimserver/chatroom/queueList.action"
返回示例
json
"Content-Type": "application/json; charset=utf-8"
{
"desc": {
"list": [
{
"33333": "33333"
}
]
},
"code": 200
}
状态码
上述接口在 HTTPS Body 中返回请求的状态码,状态码详情请参见状态码。
从队列中取出元素
URL
POST https://api.netease.im/nimserver/chatroom/queuePoll.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8
请求参数
- POST 请求中 Headers 的设置请参考接口概述。
- POST 请求中 Body 的设置如下:
参数 | 类型 | 必须 | 说明 |
---|---|---|---|
roomid | Long | 是 | 聊天室 ID |
key | String | 否 | 元素的 elementKey ,最大长度 128 位字符 不填表示取出队列的第一个元素 |
highPriority | Integer | 否 | 是否设置为高优先级消息 0:否(默认);1:是高优先级消息 |
highPriorityPolicy | Integer | 否 | 高优先级消息策略:针对高优先级消息,超过流控后是自动降级为普通消息还是直接返回 416 错误码 0:降级为普通消息(默认);1:返回 416 错误码 |
示例
请求示例(curl)
curlcurl -X POST -H "CheckSum: 32dc17d0190f3**bbf049c9367e7" -H "AppKey: fe416640c8e8a7***47ad2547" -H "Nonce: 1" -H "CurTime: 1451200147" -H "Cache-Control: no-cache" -H "Postman-Token: b9550dce-74c1-9606-0084-71dd8ec201b6" -H "Content-Type: application/x-www-form-urlencoded" -d 'roomid=36&key=333334444' "https://api.netease.im/nimserver/chatroom/queuePoll.action"
请求成功返回示例
json
"Content-Type": "application/json; charset=utf-8"
{
"desc": {
"value": "66666",
"key": "1111"
},
"code": 200
}
请求失败返回示例
"Content-Type": "application/json; charset=utf-8"
{
"code": 414, // 参数错误
"desc": "roomid not exsit"
}
状态码
该接口在 HTTPS Body 中返回请求的状态码,以下仅列出与接口业务相关的状态码。完整状态码请参见状态码。
状态码 | 说明 | 处理建议 |
---|---|---|
200 | 请求成功 | - |
403 | 禁止操作: 未开启聊天室权限 |
开通聊天室功能 |
414 | 参数错误 | 根据提示信息,检查传入参数的格式和限制条件 |
416 | 频控限制或异常错误 | 降低访问频率 |
500 | 服务出错 | - |
获取指定的队列元素
功能描述
根据指定的聊天室队列元素 key 列表获取元素信息。
URL
POST https://api.netease.im/nimserver/chatroom/queueMultiGet.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8
请求参数
- POST 请求中 Headers 的设置请参考接口概述。
- POST 请求中 Body 的设置如下:
参数 | 类型 | 必须 | 说明 |
---|---|---|---|
roomid | long | 是 | 聊天室id |
keys | JsonArray | 是 | 需要查询的队列元素key列表,最大100个,示例:["key1","key2","key3"] |
示例
请求示例(curl)
curlcurl -X POST -H 'appkey: fe4***d2547' -H 'cache-control: no-cache' -H 'checksum: 18f5***65495034' -H 'content-type: application/x-www-form-urlencoded' -H 'curtime: 1508481877' -H 'nonce: 12345' -d 'roomid=64&keys=%5B%22key1%22%2C%22key2%22%2C%22key3%22%5D' "https://api.netease.im/nimserver/chatroom/queueMultiGet.action"
返回示例
json
"Content-Type": "application/json; charset=utf-8"
{
"code": 200,
"desc": {
"list": [
{
"key1": "value1"
},
{
"key2": "value2"
},
{
"key3": "value3"
}
]
}
}
状态码
上述接口在 HTTPS Body 中返回请求的状态码,状态码详情请参见状态码。
此文档是否对你有帮助?