聊天室属性（KV）管理

聊天室属性（KV）管理接口用于在指定聊天室中设置自定义属性。

在语音直播聊天室场景中，可利用此功能记录聊天室中各麦位的属性；或在狼人杀等卡牌类游戏场景中记录用户的角色和牌局状态等。

功能局限

提示

• 聊天室销毁后，聊天室中的自定义属性同时销毁。
• 每个聊天室中，最多允许设置 100 个属性信息，以 Key-Value 的方式进行存储。
• 客户端 SDK 未针对聊天室属性 KV 的操作频率进行限制。建议每个聊天室，每秒钟操作 Key-Value 频率保持在 100 次及以下（一秒内单次操作 100 个 KV 等同于操作 100 次）。

开通服务

使用聊天室属性（KV）接口要求开通聊天室属性自定义设置服务。您可以前往控制台的免费基础功能页面开启服务。

如果配置了服务端回调 URL，融云服务端会将应用下的聊天室属性变化（设置，删除，全部删除等操作）同步到指定的回调地址。详见服务端文档聊天室属性同步（KV）。

添加聊天室 KV

方法

int addChatRoomEntry(
  string targetId,
  string key,
  string value,
  bool deleteWhenLeft,
  bool overwrite
)

参数说明

参数	类型	说明
targetId	string	聊天室 ID
key	string	聊天室属性名称，Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式，最大长度 128 个字符
value	string	聊天室属性对应的值，最大长度 4096 个字符
deleteWhenLeft	bool	用户掉线或退出时，是否自动删除该 Key、Value 值
overwrite	bool	如果当前 key 存在，是否进行覆盖

返回值

返回值	描述
int	当次接口操作状态码，并不代表最终操作结果，状态码详细信息

代码示例

int code = engine.addChatRoomEntry(
  targetId,
  key,
  value,
  deleteWhenLeft,
  overwrite
);

回调方法

• onChatRoomEntryAdded

delegate void OnChatRoomEntryAddedDelegate(int code,
  string targetId,
  string key);

OnChatRoomEntryAddedDelegate onChatRoomEntryAdded;

参数说明

参数	类型	说明
code	int	接口回调的状态码，0 代表成功，非 0 代表出现异常
targetId	string	聊天室 ID
key	string	聊天室属性名称

代码示例

engine.onChatRoomEntryAdded = delegate(
  int code,
  string targetId,
  string key
) {

添加多个聊天室 KV

方法

int addChatRoomEntries(
  string targetId,
  Dictionary<string, string> entries,
  bool deleteWhenLeft,
  bool overwrite
)

参数说明

参数	类型	说明
targetId	string	聊天室 ID
entries	Dictionary<string, string>	聊天室属性，键值对
deleteWhenLeft	bool	用户掉线或退出时，是否自动删除该 Key、Value 值
overwrite	bool	如果当前 key 存在，是否进行覆盖

返回值

返回值	描述
int	当次接口操作状态码，并不代表最终操作结果，状态码详细信息

代码示例

int code = engine.addChatRoomEntries(
  targetId,
  entries,
  deleteWhenLeft,
  overwrite
);

回调方法

• setOnChatRoomEntriesAddedListener

delegate void OnChatRoomEntriesAddedDelegate(int code,
  string targetId,
  Dictionary<string, string> entries,
  Dictionary<string, int> errorEntries);

OnChatRoomEntriesAddedDelegate onChatRoomEntriesAdded;

参数说明

参数	类型	说明
code	int	接口回调的状态码，0 代表成功，非 0 代表出现异常
targetId	string	聊天室 ID
entries	Dictionary<string, string>	聊天室属性
errorEntries	Dictionary<string, int>	发生错误的属性

代码示例

engine.onChatRoomEntriesAdded = delegate(
  int code,
  string targetId,
  Dictionary<string, string> entries,
  Dictionary<string, int> entries
)
{

}

加载聊天室 KV

方法

int loadChatRoomEntry(
  string targetId,
  string key
)

参数说明

参数	类型	说明
targetId	string	聊天室 ID
key	string	聊天室属性键值

返回值

返回值	描述
int	当次接口操作状态码，并不代表最终操作结果，状态码详细信息

代码示例

int code = engine.loadChatRoomEntry(
  targetId,
  key
);

回调方法

• onChatRoomEntryLoaded

delegate void OnChatRoomEntryLoadedDelegate(int code,
  string targetId,
  Dictionary<string, string> entries);

OnChatRoomEntryLoadedDelegate onChatRoomEntryLoaded;

参数说明

参数	类型	说明
code	int	接口回调的状态码，0 代表成功，非 0 代表出现异常
targetId	string	聊天室 ID
entries	Dictionary<string, string>	聊天室属性

代码示例

engine.onChatRoomEntryLoaded = delegate(
  int code,
  string targetId,
  Dictionary<string, string> entries
)
{

}

加载某个聊天室所有 KV

方法

int loadAllChatRoomEntries(
  string targetId
)

参数说明

参数	类型	说明
targetId	string	聊天室 ID

返回值

返回值	描述
int	当次接口操作状态码，并不代表最终操作结果，状态码详细信息

代码示例

int code = engine.loadAllChatRoomEntries(
  targetId
);

回调方法

• onAllChatRoomEntriesLoaded

delegate void OnAllChatRoomEntriesLoadedDelegate(int code,
  string targetId,
  Dictionary<string, string> entries);

OnAllChatRoomEntriesLoadedDelegate onAllChatRoomEntriesLoaded;

参数说明

参数	类型	说明
code	int	接口回调的状态码，0 代表成功，非 0 代表出现异常
targetId	string	聊天室 ID
entries	Dictionary<string, string>	聊天室属性

代码示例

engine.onAllChatRoomEntriesLoaded = delegate(
  int code,
  string targetId,
  Dictionary<string, string> entries
)
{

}

移除聊天室 KV

方法

int removeChatRoomEntry(
  string targetId,
  string key,
  bool force
)

参数说明

参数	类型	说明
targetId	string	聊天室 ID
key	string	要移除的聊天室属性名称
force	string	是否强制删除

返回值

返回值	描述
int	当次接口操作状态码，并不代表最终操作结果，状态码详细信息

示例代码

int code = engine.removeChatRoomEntry(
  targetId,
  key,
  force
);

回调方法

• onChatRoomEntryRemoved

delegate void OnChatRoomEntryRemovedDelegate(int code,
  string targetId,
  string key);

OnChatRoomEntryRemovedDelegate onChatRoomEntryRemoved;

参数说明

参数	类型	说明
code	int	接口回调的状态码，0 代表成功，非 0 代表出现异常
targetId	string	聊天室 ID
key	string	移除的聊天室属性键值

代码示例

engine.onChatRoomEntryRemoved = delegate(
  int code,
  string targetId,
  string key
)
{

}

移除聊天室多个 KV

方法

int removeChatRoomEntries(
  string targetId,
  List<string> keys,
  bool force
)

参数说明

参数	类型	说明
targetId	string	聊天室 ID
keys	List<string>	要删除的聊天室属性集合
force	bool	是否强制删除

返回值

返回值	描述
int	当次接口操作状态码，并不代表最终操作结果，状态码详细信息

代码示例

int code = engine.removeChatRoomEntries(
  targetId,
  keys,
  force
);

回调方法

• onChatRoomEntriesRemoved

delegate void OnChatRoomEntriesRemovedDelegate(int code,
  string targetId,
  List<string> keys);

OnChatRoomEntriesRemovedDelegate onChatRoomEntriesRemoved;

参数说明

参数	类型	说明
code	int	接口回调的状态码，0 代表成功，非 0 代表出现异常
targetId	string	聊天室 ID
keys	List<string>	移除的聊天室属性键值集合

代码示例

engine.onChatRoomEntriesRemoved = delegate(
  int code,
  string targetId,
  List<string> keys
)
{

}

聊天室时 KV 同步完成的回调

刚加入聊天室时 KV 同步完成的回调

方法

delegate void OnChatRoomEntriesSyncedDelegate(string roomId);

OnChatRoomEntriesSyncedDelegate onChatRoomEntriesSynced;

参数说明

参数	类型	说明
roomId	string	聊天室 ID

代码示例

engine.onChatRoomEntriesSynced = delegate(
  string roomId
)
{

}

聊天室 KV 变化的回调

如果刚进入聊天室时存在 KV，会通过此回调将所有 KV 返回，再次回调时为其他人设置或者修改 KV

方法

delegate void OnChatRoomEntriesChangedDelegate(
  RCIMChatRoomEntriesOperationType operationType,
  string roomId,
  Dictionary<string, string> entries);

OnChatRoomEntriesChangedDelegate onChatRoomEntriesChanged;

参数说明

参数	类型	说明
operationType	RCIMChatRoomEntriesOperationType	KV 变化的操作类型
roomId	string	聊天室 ID
entries	Dictionary<string, string>	发生变化的 KV 集合

代码示例

engine.onChatRoomEntriesChanged = delegate(
  RCIMChatRoomEntriesOperationType operationType,
  string roomId,
  Dictionary<string, string> entries
)
{

}