全部文档

更新时间: 2021-01-26

可在指定聊天室中设置自定义属性，用于语音直播聊天室场景的会场属性同步或狼人杀等卡牌类游戏场景中记录用户的角色和牌局状态等。

  1. 每个聊天室中，最多允许设置 100 个属性信息，以 Key-Value 的方式进行存储。
  2. 每个聊天室中，每秒钟最多允许操作 Key-Value 100 次。
  3. 聊天室销毁后，聊天室中的自定义属性同时销毁。
  4. 使用此功能需要在开发者后台免费基础功能中开通 聊天室属性自定义设置 (opens new window)功能。

# 设置属性

# 功能接口

请求地址： https://数据中心域名/chatroom/entry/set.json

请求方法： POST

签名规则： 所有请求融云服务端 API 接口的请求均需要进行规则校验，详细请参考 通用 API 接口签名规则

# 输入参数
参数 类型 必传 说明
chatroomId String 是 聊天室 Id
userId String 是 操作用户 Id。通过 Server API 非聊天室中用户可以进行设置。
key String 是 聊天室属性名称，Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式，大小写敏感。最大长度 128 字符
value String 是 聊天室属性对应的值，最大长度 4096 个字符
autoDelete Boolean 否 用户退出聊天室后，是否删除此 Key 值。为 true 时删除此 Key 值，为 false 时用户退出后不删除此 Key，默认为 false
objectName String 否 通知消息类型，设置属性后是否发送通知消息，如需要发送则设置为 RC:chrmKVNotiMsg 或其他自定义消息，为空或不传时不向聊天室发送通知消息，默认为不发送。
content String 否 通知消息内容，JSON 结构，当 objectName 为 RC:chrmKVNotiMsg 时，content 必须包含 type、key、value 属性，详细查看 RC:chrmKVNotiMsg 结构说明。
# 返回结果
返回值 返回类型 说明
code Int 返回码，200 为正常。
# 示例代码

Request：

POST /chatroom/entry/set.json HTTP/1.1
Host: api-cn.ronghub.com
App-Key: uwd1c0sxdlx2
Nonce: 14314
Timestamp: 1408710653491
Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8
Content-Type: application/x-www-form-urlencoded

chatroomId=kvchatroom2&userId=Lnq9MJsPY&key=huihui&value=555&autoDelete=true&objectName=RC%3AchrmKVNotiMsg&content=%7B%22key%22%3A%22keyli%22%2C%22value%22%3A%225%22%2C%22type%22%3A%221%22%7D&extra=111111

已复制
1
2
3
4
5
6
7
8
9

Response：

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"code":200}

已复制
1
2
3
4

# 删除属性

# 功能接口

请求地址： https://数据中心域名/chatroom/entry/remove.json

请求方法： POST

签名规则： 所有请求融云服务端 API 接口的请求均需要进行规则校验，详细请参考 通用 API 接口签名规则

# 输入参数
参数 类型 必传 说明
chatroomId String 是 聊天室 Id
userId String 是 操作用户 Id。通过 Server API 非聊天室中用户可以进行设置。
key String 是 聊天室属性名称，Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式，大小写敏感。最大长度 128 字
objectName String 否 通知消息类型，设置属性后是否发送通知消息，如需要发送则设置为 RC:chrmKVNotiMsg 或其他自定义消息，为空或不传时不向聊天室发送通知消息，默认为不发送。（可选）
content String 否 通知消息内容，JSON 结构，当 objectName 为 RC:chrmKVNotiMsg 时，content 必须包含 type、key、value 属性，详细查看 RC:chrmKVNotiMsg 结构说明。
# 返回结果
返回值 返回类型 说明
code Int 返回码，200 为正常。
# 示例代码

Request：

POST /chatroom/entry/remove.json HTTP/1.1
Host: api-cn.ronghub.com
App-Key: uwd1c0sxdlx2
Nonce: 14314
Timestamp: 1408710653491
Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8
Content-Type: application/x-www-form-urlencoded

chatroomId=kvchatroom2&userId=jrT1igbKr

已复制
1
2
3
4
5
6
7
8
9

Response：

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"code":200}

已复制
1
2
3
4

# 获取属性

# 功能接口

请求地址： https://数据中心域名/chatroom/entry/query.json

请求方法： POST

签名规则： 所有请求融云服务端 API 接口的请求均需要进行规则校验，详细请参考 通用 API 接口签名规则

# 输入参数
参数 类型 必传 说明
chatroomId String 是 聊天室 Id
keys String 否 批量获取指定聊天室中的 Key 值，最多上限为 100 个，不传时获取全部 key 值。
# 返回结果
返回值 返回类型 说明
code Int 返回码，200 为正常。
key String 设置的属性名。
value String 属性对应的内容。
userId String 最后一次设置此 Key 的用户 Id。
autoDelete Int 用户退出聊天室后是否删除此 Key，0 为不删除、1为删除。
lastSetTime String 最近一次设置 Key 的时间。
# 示例代码

Request：

POST /chatroom/entry/query.json HTTP/1.1
Host: api-cn.ronghub.com
App-Key: uwd1c0sxdlx2
Nonce: 14314
Timestamp: 1408710653491
Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8
Content-Type: application/x-www-form-urlencoded

chatroomId=kvchatroom2&keys=Lnq9MJsPY&keys=Lnq88JsPY

已复制
1
2
3
4
5
6
7
8
9

Response：

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
	"code":200,
	"keys":
	[{"key":"key1","value":"value1","userId":"2121","autoDelete":0,"lastSetTime":"2121"},
	{"key":"key2","value":"value2","userId":"4343","autoDelete":1," lastSetTime":"2121"}]
}

已复制
1
2
3
4
5
6
7
8
9

# 通知消息

# 聊天室属性通知消息
ObjectName 存储属性 计数属性 离线属性 推送属性 推送内容
RC:chrmKVNotiMsg 存储 不计数 存储 不推送 无

消息结构：

发送聊天室属性通知消息时 content 参数的 JSON 结构如下：

{
 "type":1,
 "key":"name",
 "value":"主播",
 "extra":""
}

已复制
1
2
3
4
5
6
名称 类型 必传 说明
type Int 是 聊天室中对属性操作后发送通知的类型，1 为设置属性内容、2 为删除属性内容。
key String 是 聊天室中属性名称，大小不超过 128 个字符。
value String 是 属性对应的内容，大小不超过 4096 个字符。
extra String 否 通过消息中携带的附加信息，对应到设置属性接口中的 notificationExtra 值。

# 注意事项

1、在聊天室中消息量超大的情况下，为确保业务正常运行，会将聊天室中部分消息丢弃，详细查看聊天室消息丢弃策略 (opens new window)，如要确保设置属性通知消息不被丢弃，可将该消息类型加入聊天室消息白名单中。

文档是否解决您的问题 ?

如果遇到产品相关问题，您可 提交工单 寻求帮助