# Storage (/zh-CN/api-reference/rtm/flutter/storage) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). RTM 的 Storage 功能提供了一套动态数据库机制,可以让开发者动态设置、存储、更新、删除 Channel Metadata 和 User Metadata 等数据。 ## setChannelMetadata [#setchannelmetadata] ### 接口描述 [#接口描述] `setChannelMetadata` 方法可以为频道(Message Channel 或 Stream Channel)设置 Channel Metadata。一个频道只能有一组 Metadata,但每组 Metadata 可以有一个或多个 Metadata Item。如果多次调用该方法,SDK 会依次检索 Metadata Item 的 `key` 值,并按如下规则处理: - 如果设置的 Metadata Item `key` 值不同,则会根据调用顺序依次增加。 - 如果设置的 Metadata Item `key` 值相同,则最后一次设置的 Metadata Item 的 `value` 会覆盖之前的值。 成功设置 Channel Metadata 后,订阅该频道且开启事件监听的用户会收到 `channel` 类型的 `storage` 事件通知。详见[事件监听](/zh-CN/api-reference/rtm/flutter/configuration#事件监听)。 Channel Metadata 同时也引进了版本控制逻辑 CAS(Compare And Set),该方法提供两种独立的版本控制字段,你可以根据实际业务场景设置任意一种或多种: - 通过 `majorRevision` 属性开启整组 Channel Metadata 的版本号校验。 - 通过 `MetadataItem` 中的 `revision` 属性开启某个 Metadata Item 的版本号校验。 设置 Channel Metadata 或 Metadata Item 时,配合版本属性可以控制本次调用是否开启版本号校验,逻辑如下: - 版本属性默认为 `-1` ,本次调用不开启 CAS 验证。如果 Channel Metadata 或 Metadata Item 已存在,则该值会被最新值覆盖;如果 Channel Metadata 或 Metadata Item 不存在,则 SDK 会创建该值。 - 版本属性为正整数时,本次调用开启 CAS 验证。如果 Channel Metadata 或 Metadata Item 已存在,则 SDK 会在版本号验证成功后更新对应的值;否则 SDK 会返回错误码。 成功设置 Channel Metadata 后,订阅该频道且开启事件监听的用户会收到 `channel` 类型的 `storage` 事件通知。详见[事件监听](/zh-CN/api-reference/rtm/flutter/configuration#事件监听)。 ### 接口方法 [#接口方法] 你可以通过以下方式调用 `setChannelMetadata` 方法: ```dart Future<(RtmStatus, SetChannelMetadataResult?)> setChannelMetadata( String channelName, RtmChannelType channelType, List metadata, { int majorRevision = -1, bool recordTs = false, bool recordUserId = false, String lockName = '' } ); ``` | 参数 | 类型 | 必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `channelName` | String | 必填 | - | 频道名称。 | | `channelType` | `RtmChannelType` | 必填 | `message` | 频道类型。详见 [`RtmChannelType`](/zh-CN/api-reference/rtm/flutter/enumv#channeltype)。 | | `metadata` | `List` | 必填 | - | Metadata Item。详见 [`MetadataItem`](#metadataitem)。 | | `majorRevision` | int | 选填 | -1 | [storage-flutter-html-0-4-4 details](#table-slot-storage-flutter-html-0-4-4) | | `recordTs` | bool | 选填 | `false` | 是否记录编辑的时间戳。 | | `recordUserId` | bool | 选填 | `false` | 是否记录编辑者的用户 ID。 | | `lockName` | String | 选填 | '' | Lock 名称。设置后,只有调用 `acquireLock` 方法获取该锁的用户才能执行操作。 | **storage-flutter-html-0-4-4 details** 版本控制开关: - `-1`: 关闭版本校验。 - > `0`: 开启版本校验,只有目标版本号与此值相符才能执行操作。 ### 基本用法 [#基本用法] ```dart var item1 = MetadataItem( key: 'Apple', value: '100', revision: 174298200 ); var item2 = MetadataItem( key: 'Banana', value: '200', revision: 174298100 ); var metadata = [item1,item2]; var (status,response) = await rtmClient.getStorage.setChannelMetadata( "myChannel", RtmChannelType.message, metadata, majorRevision: 174298222, recordTs: true, recordUserId: true, lockName: "myLock" ) if (status.error == true) { print(status); } else { print(response); } ``` ### 返回值 [#返回值] 调用此方法,会返回 `Future<(RtmStatus, SetChannelMetadataResult?)>` 类型的元组数据。 - 无论该方法是否调用成功,元组的第一项都会返回一个 `RtmStatus` 类型的数据,其中字段定义如下: ```dart class RtmStatus { bool error; // 本次操作是否出错。 String errorCode; // 本次操作错误码。 String operation; // 本次操作的 API。 String reason; // 本次操作错误原因简述。 } ``` 你可以通过检索 `errorCode` 字段的[错误码](/zh-CN/realtime-media/rtm/build/troubleshooting)了解错误原因,并找到对应的解决方法。 - 如果该方法调用成功,元组的第二项将返回一个 `SetChannelMetadataResult` 类型的数据,定义如下: ```dart class SetChannelMetadataResult { final String channelName; // 当前操作的频道 final RtmChannelType channelType; // 当前操作频道类型 } ``` ## getChannelMetadata [#getchannelmetadata] ### 接口描述 [#接口描述-1] `getChannelMetadata` 方法可以获取指定频道的 Metadata。 ### 接口方法 [#接口方法-1] 你可以通过以下方式调用 `getChannelMetadata` 方法: ```dart Future<(RtmStatus, GetChannelMetadataResult?)> getChannelMetadata( String channelName, RtmChannelType channelType ); ``` | 参数 | 类型 | 必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `channelName` | String | 必填 | - | 频道名称。 | | `channelType` | `RtmChannelType` | 必填 | - | 频道类型。详见 [`RtmChannelType`](/zh-CN/api-reference/rtm/flutter/enumv#channeltype)。 | ### 接口方法 [#接口方法-2] ```dart var (status,response) = await rtmClient.getStorage.getChannelMetadata( "myChannel", RtmChannelType.message, ) if (status.error == true) { print(status); } else { print(response); } ``` ### 返回值 [#返回值-1] 调用此方法,会返回 `Future<(RtmStatus, GetChannelMetadataResult?)>` 类型的元组数据。 - 无论该方法是否调用成功,元组的第一项都会返回一个 `RtmStatus` 类型的数据,其中字段定义如下: ```dart class RtmStatus { bool error; // 本次操作是否出错。 String errorCode; // 本次操作错误码。 String operation; // 本次操作的 API。 String reason; // 本次操作错误原因简述。 } ``` 你可以通过检索 `errorCode` 字段的[错误码](/zh-CN/realtime-media/rtm/build/troubleshooting)了解错误原因,并找到对应的解决方法。 - 如果该方法调用成功,元组的第二项将返回一个 `GetChannelMetadataResult` 类型的数据,定义如下: ```dart class GetChannelMetadataResult { final String channelName; // 当前操作的频道 final RtmChannelType channelType; // 当前操作频道类型 final Metadata data; // Metadata 数据 } ``` ## removeChannelMetadata [#removechannelmetadata] ### 接口描述 [#接口描述-2] `removeChannelMetadata` 方法可以删除 Channel Metadata 或 Channel Metadata Item 数组。 删除时,配合版本属性可以控制本次调用是否开启版本号校验,逻辑如下: - 版本属性默认为 `-1` ,本次调用不开启 CAS 验证。如果 Channel Metadata 或 Metadata Item 已存在,则 SDK 会删除该值;如果 Channel Metadata 或 Metadata Item 不存在,则 SDK 会返回错误码。 - 版本属性为正整数时,本次调用开启 CAS 验证。如果 Channel Metadata 或 Metadata Item 已存在,则 SDK 会在版本号验证成功后删除对应值;否则 SDK 会返回错误码。 成功删除 Channel Metadata 或 Metadata Item 后,订阅该频道且开启事件监听的用户会收到 `channel` 类型的 `storage` 事件通知。详见[事件监听](/zh-CN/api-reference/rtm/flutter/configuration#事件监听)。 ### 接口方法 [#接口方法-3] 你可以通过以下方式调用 `removeChannelMetadata` 方法: ```dart Future<(RtmStatus, RemoveChannelMetadataResult?) removeChannelMetadata( String channelName, RtmChannelType channelType, { int majorRevision = -1, List metadata = const [], bool recordTs = false, bool recordUserId = false, String lockName = '' } ); ``` | 参数 | 类型 | 必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `channelName` | String | 必填 | - | 频道名称。 | | `channelType` | `RtmChannelType` | 必填 | - | 频道类型。详见 [`RtmChannelType`](/zh-CN/api-reference/rtm/flutter/enumv#channeltype)。 | | `majorRevision` | int | 选填 | -1 | [storage-flutter-html-2-3-4 details](#table-slot-storage-flutter-html-2-3-4) | | `metadata` | `List` | 选填 | - | Metadata Item。详见 [`MetadataItem`](#metadataitem)。 | | `lockName` | String | 选填 | - | Lock 名称。设置后,只有调用 `acquireLock` 方法获取该锁的用户才能执行操作。 | | `recordTs` | bool | 选填 | `false` | 是否记录编辑的时间戳。 | | `recordUserId` | bool | 选填 | `false` | 是否记录编辑者的用户 ID。 | **storage-flutter-html-2-3-4 details** 版本控制开关: - `-1`: 关闭版本校验。 - > `0`: 开启版本校验,只有目标版本号与此值相符才能执行操作。 ### 接口方法 [#接口方法-4] ```dart var item1 = MetadataItem( key: 'Apple', revision: 174298200 ); var item2 = MetadataItem( key: 'Banana', revision: 174298100 ); var metadata = [item1,item2]; var (status,response) = await rtmClient.getStorage.removeChannelMetadata( "myChannel", RtmChannelType.message, metadata, majorRevision: 174298222, recordTs: true, recordUserId: true, lockName: "myLock" ); if (status.error == true) { print(status); } else { print(response); } ``` ### 返回值 [#返回值-2] 调用此方法,会返回 `Future<(RtmStatus, RemoveChannelMetadataResult?)>` 类型的元组数据。 - 无论该方法是否调用成功,元组的第一项都会返回一个 `RtmStatus` 类型的数据,其中字段定义如下: ```dart class RtmStatus { bool error; // 本次操作是否出错。 String errorCode; // 本次操作错误码。 String operation; // 本次操作的 API。 String reason; // 本次操作错误原因简述。 } ``` 你可以通过检索 `errorCode` 字段的[错误码](/zh-CN/realtime-media/rtm/build/troubleshooting)了解错误原因,并找到对应的解决方法。 - 如果该方法调用成功,元组的第二项将返回一个 `RemoveChannelMetadataResult` 类型的数据,定义如下: ```dart class RemoveChannelMetadataResult { final String channelName; // 当前操作的频道 final RtmChannelType channelType; // 当前操作频道类型 } ``` ## updateChannelMetadata [#updatechannelmetadata] ### 接口描述 [#接口描述-3] `updateChannelMetadata` 方法可以更新已有的 Channel Metadata。每次调用该方法,你可以更新一个 Channel Metadata,也可以更新一个或多个 Channel Metadata Item 数组。 成功更新后,订阅该频道且开启事件监听的用户会收到 `channel` 类型的 `storage` 事件通知。详见[事件监听](/zh-CN/api-reference/rtm/flutter/configuration#事件监听)。 :::info[信息] 该方法不能对不存在的 Metadata Item 进行操作。 ::: ### 接口方法 [#接口方法-5] 你可以通过以下方式调用 `updateChannelMetadata` 方法: ```dart Future<(RtmStatus, UpdateChannelMetadataResult?)> updateChannelMetadata( String channelName, RtmChannelType channelType, List metadata = const [], { int majorRevision = -1, bool recordTs = false, bool recordUserId = false, String lockName = '' } ); ``` | 参数 | 类型 | 必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `channelName` | String | 必填 | - | 频道名称。 | | `channelType` | `RtmChannelType` | 必填 | - | 频道类型。详见 [`RtmChannelType`](/zh-CN/api-reference/rtm/flutter/enumv#channeltype)。 | | `metadata` | `List` | 选填 | - | Metadata Item。详见 [`MetadataItem`](#metadataitem)。 | | `majorRevision` | int | 选填 | -1 | [storage-flutter-html-3-4-4 details](#table-slot-storage-flutter-html-3-4-4) | | `recordTs` | bool | 选填 | `false` | 是否记录编辑的时间戳。 | | `recordUserId` | bool | 选填 | `false` | 是否记录编辑者的用户 ID。 | | `lockName` | String | 必填 | - | Lock 名称。设置后,只有调用 `acquireLock` 方法获取该锁的用户才能执行操作。 | **storage-flutter-html-3-4-4 details** 版本控制开关: - `-1`: 关闭版本校验。 - > `0`: 开启版本校验,只有目标版本号与此值相符才能执行操作。 ### 基本用法 [#基本用法-1] ```dart var item1 = MetadataItem( key: 'Apple', value: '330', revision: 174298200 ); var item2 = MetadataItem( key: 'Banana', value: '480', revision: 174298100 ); var metadata = [item1,item2]; var (status,response) = await rtmClient.getStorage.updateChannelMetadata( "myChannel", RtmChannelType.message, metadata, majorRevision: 174298222, recordTs: true, recordUserId: true, lockName: "myLock" ); if (status.error == true) { print(status); } else { print(response); } ``` 返回值 调用此方法,会返回 `Future<(RtmStatus, UpdateChannelMetadataResult?)>` 类型的元组数据。 - 无论该方法是否调用成功,元组的第一项都会返回一个 `RtmStatus` 类型的数据,其中字段定义如下: ```dart class RtmStatus { bool error; // 本次操作是否出错。 String errorCode; // 本次操作错误码。 String operation; // 本次操作的 API。 String reason; // 本次操作错误原因简述。 } ``` 你可以通过检索 `errorCode` 字段的[错误码](/zh-CN/realtime-media/rtm/build/troubleshooting)了解错误原因,并找到对应的解决方法。 - 如果该方法调用成功,元组的第二项将返回一个 ` UpdateChannelMetadataResult` 类型的数据,定义如下: ```dart class UpdateChannelMetadataResult { final String channelName; // 当前操作的频道 final RtmChannelType channelType; // 当前操作频道类型 } ``` ## setUserMetadata [#setusermetadata] ### 接口描述 [#接口描述-4] `setUserMetadata` 方法可以设置 User Metadata。如果多次调用该方法时,SDK 会依次检索 User Metadata Item 的 `key` 值,并按如下规则处理: - 如果设置的 Metadata Item key 值不同,则会根据调用顺序依次增加。 - 如果设置的 Metadata Item key 值相同,则最后一次设置的 Metadata 的 value 会覆盖之前的值。 成功设置 User Metadata 后,订阅该用户 Metadata 且开启事件监听的用户会收到 `user` 类型的 `storage` 事件通知。详见[事件监听](/zh-CN/api-reference/rtm/flutter/configuration#事件监听)。 User Metadata 同时也引进了版本控制逻辑 CAS,该方法提供两种独立的版本控制字段,你可以根据实际业务场景设置任意一种或多种: - 通过设置 `majorRevision` 属性开启整组 Channel Metadata 的版本号校验。 - 通过 `MetadataItem` 中的 `revision` 属性开启某个 Metadata Item 的版本号校验。 设置 User Metadata 时,配合版本属性可以控制本次调用是否开启版本号校验,逻辑如下: - 版本属性为 `-1` 时,本次调用不开启 CAS 验证。如果 User Metadata 或 Metadata Item 已存在,则该值会被最新值覆盖;如果 User Metadata 或 Metadata Item 不存在,则会创建该值。 - 版本属性为正整数时,本次调用开启 CAS 验证。如果 User Metadata 或 Metadata Item 已存在,则 SDK 会在版本号验证成功后更新对应的值;如果 User Metadata 或 Metadata Item 不存在,则 SDK 会返回错误码。 ### 接口方法 [#接口方法-6] 你可以通过以下方式调用 `setUserMetadata` 方法: ```dart Future<(RtmStatus, SetUserMetadataResult?)> setUserMetadata( String userId, List metadata, { int majorRevision = -1, bool recordTs = false, bool recordUserId = false } ); ``` | 参数 | 类型 | 必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `userId` | String | 必填 | - | 用户 ID。 | | `metadata` | `List` | 必填 | - | Metadata Item。详见 [`MetadataItem`](#metadataitem)。 | | `majorRevision` | int | 选填 | -1 | [storage-flutter-html-4-3-4 details](#table-slot-storage-flutter-html-4-3-4) | | `recordTs` | bool | 选填 | `false` | 是否记录编辑的时间戳。 | | `recordUserId` | bool | 选填 | `false` | 是否记录编辑者的用户 ID。 | **storage-flutter-html-4-3-4 details** 版本控制开关: - `-1`: 关闭版本校验。 - > `0`: 开启版本校验,只有目标版本号与此值相符才能执行操作。 ### 基本用法 [#基本用法-2] ```dart var item1 = MetadataItem( key: 'Name', value: 'Tony', revision: 174298200 ); var item2 = MetadataItem( key: 'Mute', value: 'true', revision: 174298100 ); var metadata = [item1,item2]; var (status,response) = await rtmClient.getStorage.setUserMetadata( "Tony", metadata, majorRevision: 174298222, recordTs: true, recordUserId: true ); if (status.error == true) { print(status); } else { print(response); } ``` ### 返回值 [#返回值-3] 调用此方法,会返回 `Future<(RtmStatus, SetUserMetadataResult?)>` 类型的元组数据。 - 无论该方法是否调用成功,元组的第一项都会返回一个 `RtmStatus` 类型的数据,其中字段定义如下: ```dart class RtmStatus { bool error; // 本次操作是否出错。 String errorCode; // 本次操作错误码。 String operation; // 本次操作的 API。 String reason; // 本次操作错误原因简述。 } ``` 你可以通过检索 `errorCode` 字段的[错误码](/zh-CN/realtime-media/rtm/build/troubleshooting)了解错误原因,并找到对应的解决方法。 - 如果该方法调用成功,元组的第二项将返回一个 ` SetUserMetadataResult` 类型的数据,定义如下: ```dart class SetUserMetadataResult { final String userId; // 当前操作的用户 ID } ``` ## getUserMetadata [#getusermetadata] ### 接口描述 [#接口描述-5] `getUserMetadata` 方法可以获取指定用户的 Metadata 和 User Metadata Item。 ### 接口方法 [#接口方法-7] 你可以通过以下方式调用 `getUserMetadata` 方法: ```dart Future<(RtmStatus, GetUserMetadataResult?)> getUserMetadata(String userId); ``` | 参数 | 类型 | 必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `userId` | String | 必填 | - | 用户 ID。 | ### 基本用法 [#基本用法-3] ```dart var (status,response) = await rtmClient.getStorage.getUserMetadata( "Tony" ); if (status.error == true) { print(status); } else { print(response); } ``` ### 返回值 [#返回值-4] 调用此方法,会返回 `Future<(RtmStatus, GetUserMetadataResult?)>` 类型的元组数据。 - 无论该方法是否调用成功,元组的第一项都会返回一个 `RtmStatus` 类型的数据,其中字段定义如下: ```dart class RtmStatus { bool error; // 本次操作是否出错。 String errorCode; // 本次操作错误码。 String operation; // 本次操作的 API。 String reason; // 本次操作错误原因简述。 } ``` 你可以通过检索 `errorCode` 字段的[错误码](/zh-CN/realtime-media/rtm/build/troubleshooting)了解错误原因,并找到对应的解决方法。 - 如果该方法调用成功,元组的第二项将返回一个 ` GetUserMetadataResult` 类型的数据,定义如下: ```dart class GetUserMetadataResult { final String userId; // 当前操作的用户 ID final Metadata data; // 用户 Metadata 数据 } ``` ## removeUserMetadata [#removeusermetadata] ### 接口描述 [#接口描述-6] `removeUserMetadata` 方法可以删除 User Metadata 或某几个 User Metadata Item。 成功删除后,订阅该用户 Metadata 且开启事件监听的用户会收到 `user` 类型的 `storage` 事件通知。详见[事件监听](/zh-CN/api-reference/rtm/flutter/configuration#事件监听)。 ### 接口方法 [#接口方法-8] 你可以通过以下方式调用 `removeUserMetadata` 方法: ```dart Future<(RtmStatus, RemoveUserMetadataResult?)> removeUserMetadata( String userId, { int majorRevision = -1, List metadata = const [], bool recordTs = false, bool recordUserId = false } ); ``` | 参数 | 类型 | 必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `userId` | String | 必填 | - | 用户 ID。 | | `majorRevision` | int | 选填 | -1 | [storage-flutter-html-6-2-4 details](#table-slot-storage-flutter-html-6-2-4) | | `metadata` | `List` | 必填 | - | Metadata Item。详见 [`MetadataItem`](#metadataitem)。 | | `recordTs` | bool | 选填 | `false` | 是否记录编辑的时间戳。 | | `recordUserId` | bool | 选填 | `false` | 是否记录编辑者的用户 ID。 | **storage-flutter-html-6-2-4 details** 版本控制开关: - `-1`: 关闭版本校验。 - > `0`: 开启版本校验,只有目标版本号与此值相符才能执行操作。 ### 基本用法 [#基本用法-4] ```dart var item1 = MetadataItem( key: 'Name', revision: 174298200 ); var item2 = MetadataItem( key: 'Mute', revision: 174298100 ); var metadata = [item1,item2]; var (status,response) = await rtmClient.getStorage.removeUserMetadata( "Tony", metadata: metadata majorRevision: 174298222, recordTs: true, recordUserId: true ); if (status.error == true) { print(status); } else { print(response); } ``` ### 返回值 [#返回值-5] 调用此方法,会返回 `Future<(RtmStatus, RemoveUserMetadataResult?)>` 类型的元组数据。 - 无论该方法是否调用成功,元组的第一项都会返回一个 `RtmStatus` 类型的数据,其中字段定义如下: ```dart class RtmStatus { bool error; // 本次操作是否出错。 String errorCode; // 本次操作错误码。 String operation; // 本次操作的 API。 String reason; // 本次操作错误原因简述。 } ``` 你可以通过检索 `errorCode` 字段的[错误码](/zh-CN/realtime-media/rtm/build/troubleshooting)了解错误原因,并找到对应的解决方法。 - 如果该方法调用成功,元组的第二项将返回一个 ` RemoveUserMetadataResult` 类型的数据,定义如下: ```dart class RemoveUserMetadataResult { final String userId; // 当前操作的用户 ID } ``` ## updateUserMetadata [#updateusermetadata] ### 接口描述 [#接口描述-7] `updateUserMetadata` 方法可以更新已有的 User Metadata 或 Metadata Item。成功更新后,订阅该 User Metadata 且开启事件监听的用户会收到 `user` 类型的 `storage` 事件通知。详见[事件监听](/zh-CN/api-reference/rtm/flutter/configuration#事件监听)。 :::info[信息] 该方法不能对不存在的 Metadata Item 进行操作。 ::: ### 接口方法 [#接口方法-9] 你可以通过以下方式调用 `updateUserMetadata` 方法: ```dart Future<(RtmStatus, UpdateUserMetadataResult?)> updateUserMetadata( String userId, List metadata, { int majorRevision = -1, bool recordTs = false, bool recordUserId = false } ); ``` | 参数 | 类型 | 必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `userId` | String | 必填 | - | 用户 ID。 | | `metadata` | `List` | 必填 | - | Metadata Item。详见 [`MetadataItem`](#metadataitem)。 | | `majorRevision` | int | 选填 | - | [storage-flutter-html-7-3-4 details](#table-slot-storage-flutter-html-7-3-4) | | `recordTs` | bool | 选填 | `false` | 是否记录编辑的时间戳。 | | `recordUserId` | bool | 选填 | `false` | 是否记录编辑者的用户 ID。 | **storage-flutter-html-7-3-4 details** 版本控制开关: - `-1`: 关闭版本校验。 - > `0`: 开启版本校验,只有目标版本号与此值相符才能执行操作。 ### 基本用法 [#基本用法-5] ```dart var item1 = MetadataItem( key: 'Name', value: 'Sara', revision: 174298200 ); var item2 = MetadataItem( key: 'Mute', value: 'false', revision: 174298100 ); var metadata = [item1,item2]; var (status,response) = await rtmClient.getStorage.updateUserMetadata( "Sara", metadata, majorRevision: 174298222, recordTs: true, recordUserId: true ); if (status.error == true) { print(status); } else { print(response); } ``` ### 返回值 [#返回值-6] 调用此方法,会返回 `Future<(RtmStatus,UpdateUserMetadataResult?)>` 类型的元组数据。 - 无论该方法是否调用成功,元组的第一项都会返回一个 `RtmStatus` 类型的数据,其中字段定义如下: ```dart class RtmStatus { bool error; // 本次操作是否出错。 String errorCode; // 本次操作错误码。 String operation; // 本次操作的 API。 String reason; // 本次操作错误原因简述。 } ``` 你可以通过检索 `errorCode` 字段的[错误码](/zh-CN/realtime-media/rtm/build/troubleshooting)了解错误原因,并找到对应的解决方法。 - 如果该方法调用成功,元组的第二项将返回一个 `UpdateUserMetadataResult` 类型的数据,定义如下: ```dart class UpdateUserMetadataResult { final String userId; // 当前操作的用户 ID } ``` ## subscribeUserMetadata [#subscribeusermetadata] ### 接口描述 [#接口描述-8] `subscribeUserMetadata` 方法可以订阅指定用户的 Metadata。成功订阅且开启事件监听后,当该用户的 Metadata 发生变更时会收到 `user` 类型的 `storage` 事件通知。详见[事件监听](/zh-CN/api-reference/rtm/flutter/configuration#事件监听)。 ### 接口方法 [#接口方法-10] 你可以通过以下方式调用 `subscribeUserMetadata` 方法: ```dart Future<(RtmStatus, SubscribeUserMetadataResult?)> subscribeUserMetadata(String userId); ``` | 参数 | 类型 | 必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `userId` | String | 必填 | - | 用户 ID。 | ### 基本用法 [#基本用法-6] ```dart var (status,response) = await rtmClient.getStorage.subscribeUserMetadata( "Sara"); if (status.error == true) { print(status); } else { print(response); } ``` ### 返回值 [#返回值-7] 调用此方法,会返回 `Future<(RtmStatus, SubscribeUserMetadataResult?)>` 类型的元组数据。 - 无论该方法是否调用成功,元组的第一项都会返回一个 `RtmStatus` 类型的数据,其中字段定义如下: ```dart class RtmStatus { bool error; // 本次操作是否出错。 String errorCode; // 本次操作错误码。 String operation; // 本次操作的 API。 String reason; // 本次操作错误原因简述。 } ``` 你可以通过检索 `errorCode` 字段的[错误码](/zh-CN/realtime-media/rtm/build/troubleshooting)了解错误原因,并找到对应的解决方法。 - 如果该方法调用成功,元组的第二项将返回一个 ` SubscribeUserMetadataResult` 类型的数据,定义如下: ```dart class SubscribeUserMetadataResult { final String userId; // 当前操作的用户 ID } ``` ## unsubscribeUserMetadata [#unsubscribeusermetadata] ### 接口描述 [#接口描述-9] 如果你不需要接收某个用户 User Metadata 的变更通知,调用 `unsubscribeUserMetadata` 方法取消订阅。 ### 接口方法 [#接口方法-11] 你可以通过以下方式调用 `unsubscribeUserMetadata` 方法: ```dart Future<(RtmStatus, UnsubscribeUserMetadataResult?)> unsubscribeUserMetadata(String userId); ``` | 参数 | 类型 | 必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `userId` | String | 必填 | - | 用户 ID。 | ### 基本用法 [#基本用法-7] ```dart var (status,response) = await rtmClient.getStorage.unsubscribeUserMetadata( "Sara"); if (status.error == true) { print(status); } else { print(response); } ``` ### 返回值 [#返回值-8] 调用此方法,会返回 `Future<(RtmStatus, UnsubscribeUserMetadataResult?)>` 类型的元组数据。 - 无论该方法是否调用成功,元组的第一项都会返回一个 `RtmStatus` 类型的数据,其中字段定义如下: ```dart class RtmStatus { bool error; // 本次操作是否出错。 String errorCode; // 本次操作错误码。 String operation; // 本次操作的 API。 String reason; // 本次操作错误原因简述。 } ``` 你可以通过检索 `errorCode` 字段的[错误码](/zh-CN/realtime-media/rtm/build/troubleshooting)了解错误原因,并找到对应的解决方法。 - 如果该方法调用成功,元组的第二项将返回一个 ` UnsubscribeUserMetadataResult` 类型的数据,定义如下: ```dart class UnsubscribeUserMetadataResult { final String userId; // 当前操作的用户 ID } ``` ## Metadata [#metadata] 设置和管理 Metadata 的数据结构。包含以下属性: | 属性 | 类型 | 是否必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `majorRevision` | int | 选填 | `-1` | Metadata 的主版本号。`-1` 表示关闭版本校验;大于 `0` 时,仅当目标版本号与该值相符时执行操作。 | | `items` | `List` | 选填 | `null` | Metadata Item 列表。 | ## MetadataItem [#metadataitem] 设置和管理 Metadata Item 的数据结构。包含以下属性: | 属性 | 类型 | 是否必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `key` | String | 选填 | - | 键。 | | `value` | String | 选填 | - | 值。 | | `authorUserId` | String | 选填 | - | 编辑者的用户 ID。该值为只读,不支持写入。 | | `revision` | int | 选填 | `-1` | [storage-flutter-html-10-4-4 details](#table-slot-storage-flutter-html-10-4-4) | | `updateTs` | int | 选填 | `0` | 更新时间戳。该值为只读,不支持写入。 | **storage-flutter-html-10-4-4 details** - 在读取操作时作为真实版本号返回。 - 在写入操作时作为版本控制开关: - `-1`: 关闭版本校验。 - > `0`: 开启版本校验,只有目标版本号与此值相符才执行操作。