API 参考
圈组

聊天室队列元素管理

更新时间: 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,默认为该聊天室的创建者
  • 若 operator 对应的帐号不存在,会返回 404 错误
  • 若指定的 operator 不在线,则添加元素成功后的通知事件中的操作者默认为聊天室的创建者
  • 若指定的 operator 在线,则通知事件的操作者为 operator
    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:不需要删除(默认)
    • 当指定该参数为 true,且所有者当前不在该聊天室内,则添加失败
    • 若批量添加的元素未配置 transient 参数,则使用该参数配置
      elements String 队列元素,JSONArray,最多 20 个
      格式如下:
      [
          {
              "key": "key01",   //元素key
              "value": "{\"priority\":10}", //元素value
              "accid":"user01", //元素所属账号
              //accid不填则默认是operator
              "transient":true //离开聊天室是否删除元素
              //transient不填则默认是transient参数
          }
      ]
      
      needNotify Boolean 是否需要发送更新通知事件,true(默认)或 false当needNotify=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当needNotify=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 禁止操作:
    • 未开启聊天室权限
    • operator 不是聊天室创建者或管理员
    • 根据对应提示信息做出处理
      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 中返回请求的状态码,状态码详情请参见状态码

      此文档是否对你有帮助?
      有帮助
      去反馈
      • API 使用限制
      • 添加或更新元素
      • 功能描述
      • URL
      • 请求参数
      • 示例
      • 请求示例(curl)
      • 请求成功返回示例
      • 请求失败返回示例
      • 状态码
      • 批量添加队列元素
      • 功能描述
      • URL
      • 请求参数
      • 示例
      • 请求示例(curl)
      • 请求成功返回示例
      • 请求失败返回示例
      • 状态码
      • 批量更新队列元素
      • 功能描述
      • URL
      • 请求参数
      • 示例
      • 请求示例(curl)
      • 请求成功返回示例
      • 请求失败返回示例
      • 状态码
      • 排序列出队列中所有元素
      • URL
      • 请求参数
      • 示例
      • 请求示例(curl)
      • 返回示例
      • 状态码
      • 从队列中取出元素
      • URL
      • 请求参数
      • 示例
      • 请求示例(curl)
      • 请求成功返回示例
      • 请求失败返回示例
      • 状态码
      • 获取指定的队列元素
      • 功能描述
      • URL
      • 请求参数
      • 示例
      • 请求示例(curl)
      • 返回示例
      • 状态码