2026/02/12 16:16:25

User Metadata

Storage 服务为你提供了 User Metadata 的能力，可以用来存储和分发你的应用中关于用户的上下文数据，例如：姓名、年龄、头像连接等一切自定义数据。User Metadata 在被设置、更新和删除的时候会触发 storage 事件通知，订阅此 User Metadata 的用户会在 100ms 内收到此信息。

需要注意的是，User Metadata 属于永久存储，一旦被设置将会长期保存在 RTM 数据库，不会因为你的用户注销而丢失，直到你手动删除它们为止。知道这一点非常重要，因为它将影响你的存储计费项，详见计费规则。

设置 User Metadata

你可以为指定的用户设置一组 User Metadata 用以实现业务上用户级别的数据存储和实时通知，例如用户的姓名、年级、头像链接、自我介绍等任何自定义数据。每个用户只能有一组 User Metadata，但每组 User Metadata 可以包含一个或多个 Metadata Item，相关限制详见 API 使用限制。每个 Metadata Item 包含有 key、value、revision 预定义字段。

如果当前 User Metadata 或者 Metadata Item 不存在，该方法将为指定用户新增属性；如果 User Metadata 或者 Metadata Item 存在，则会使用新值覆盖原有值。

以下示例代码展示了如何置 User Metadata:

TypeScript
import { MetadataItem, MetadataOptions } from '@shengwang/rtm-full';
import { RtmError } from '@shengwang/rtm-full';

const metadata: MetadataItem[] = [
  { key: "Name", value: "Tony" },
  { key: "Age", value: "40" },
  { key: "Avatar", value: "https://your-domain/avatar/tong.png" }
];

const options: MetadataOptions = {
  recordTs: true,
  recordUserId: true
};

try {
  const result = await rtmClient.storage.setUserMetadata(
    "Tony",
    {
      majorRevision: -1,
      items: metadata
    },
    options
  );
  console.log("User metadata set successfully:", result.userId);
} catch (error) {
  console.error("setUserMetadata failed:", error);
  if (error instanceof RtmError) {
    console.error(`setUserMetadata failed: ${error.reason} (code: ${error.errorCode})`);
  }
}

上述示例代码中，我们为用户 Tony 设置了一组 User Metadata，其中包含三个 Metadata Item，分别为 Name、Age 和 Avatar。同时我们设置了 options 参数要求 RTM 服务在存储上述三个 Metadata Item 时额外添加上时间戳和修改者信息。

关于 setUserMetadata 接口详见 Storage API 参考。

当上述操作成功后，RTM SDK 会返回如下数据结构：

TypeScript
{
    userId: "Tony"   // 用户名
}

同时，RTM 还会触发一个 UPDATE 类型的 storage 事件通知，并在 100 ms 内通知到订阅了此 User Metadata 的其他人，详见事件通知。

获取 User Metadata

你可以通过调用 getUserMetadata 方法获得指定用户的全部属性数据。以下示例代码展示如何获取 User Metadata：

TypeScript
import { RtmError } from '@shengwang/rtm-full';

try {
  const result = await rtmClient.storage.getUserMetadata("Tony");
  console.log("User metadata retrieved:");
  console.log("  User ID:", result.userId);
  console.log("  Major revision:", result.data.majorRevision);
  console.log("  Items:");
  result.data.items.forEach(item => {
    console.log(`    ${item.key}: ${item.value}`);
    console.log(`      Revision: ${item.revision}`);
    console.log(`      Author: ${item.authorUserId}`);
    console.log(`      Updated at: ${item.updateTs}`);
  });
} catch (error) {
  console.error("getUserMetadata failed:", error);
  if (error instanceof RtmError) {
    console.error(`getUserMetadata failed: ${error.reason} (code: ${error.errorCode})`);
  }
}

当上述操作成功后，RTM SDK 会返回如下数据结构：

TypeScript
{
    userId: "Tony",
    data: {
        majorRevision: 734874892,
        items: [
            {
                key: "Name",
                value: "Tony",
                revision: 734874872,
                updateTs: 1688978391900,
                authorUserId: "Tony"
            },
            {
                key: "Age",
                value: "40",
                revision: 734874862,
                updateTs: 1688978390900,
                authorUserId: "Tony"
            },
            {
                key: "Avatar",
                value: "https://your-domain/avatar/tong.png",
                revision: 734874812,
                updateTs: 1688978382900,
                authorUserId: "Tony"
            }
        ]
    }
}

更新 User Metadata

你可以使用 updateUserMetadata 来更新已存在的 User Metadata。如果该 User Metadata 不存在，则会返回错误。该接口可用于需要权限控制的业务场景，例如：应用的设置者预定义了 User Metadata 的数据字段和格式，用户只具备更新的权限。

以下示例代码展示了如何更新用户 Metadata Item：

TypeScript
import { MetadataItem, MetadataOptions } from '@shengwang/rtm-full';
import { RtmError } from '@shengwang/rtm-full';

const metadata: MetadataItem[] = [
  { key: "Age", value: "45" }
];

const options: MetadataOptions = {
  recordTs: true,
  recordUserId: true
};

try {
  const result = await rtmClient.storage.updateUserMetadata(
    "Tony",
    {
      majorRevision: -1,
      items: metadata
    },
    options
  );
  console.log("User metadata updated successfully:", result.userId);
} catch (error) {
  console.error("updateUserMetadata failed:", error);
  if (error instanceof RtmError) {
    console.error(`updateUserMetadata failed: ${error.reason} (code: ${error.errorCode})`);
  }
}

上述示例代码将 key 为 Age 的年龄数据更新为 45。

当上述操作成功后，RTM SDK 会返回如下数据结构：

TypeScript
{
    userId: "Tony"   // 用户名
}

同时，RTM 还会触发一个 UPDATE 类型的 storage 事件通知，并在 100ms 内通知到订阅此 User Metadata 的其他人。storage 详见事件通知。

删除 User Metadata

当你不再需要指定用户的 User Metadata 或者某几个 Metadata Item，你可以进行删除操作。以下示例代码展示了如何使用 removeUserMetadata 进行删除操作：

TypeScript
import { MetadataItem } from '@shengwang/rtm-full';
import { RtmError } from '@shengwang/rtm-full';

const metadata: MetadataItem[] = [
  { key: "Age", value: "" }  // value is ignored for remove
];

try {
  await rtmClient.storage.removeUserMetadata(
    "Tony",
    {
      majorRevision: -1,
      items: metadata
    }
  );
  console.log("User metadata removed successfully");
} catch (error) {
  console.error("removeUserMetadata failed:", error);
  if (error instanceof RtmError) {
    console.error(`removeUserMetadata failed: ${error.reason} (code: ${error.errorCode})`);
  }
}

以上示例代码中 value 不论为何值都没有影响。

如果你传入空的 items 数组，则会删除指定用户的整组 User Metadata。参照以下示例代码：

TypeScript
import { RtmError } from '@shengwang/rtm-full';

try {
  // Empty items array = remove all metadata
  await rtmClient.storage.removeUserMetadata(
    "Tony",
    {
      majorRevision: -1,
      items: []  // 空数组表示删除所有元数据
    }
  );
  console.log("All user metadata removed successfully");
} catch (error) {
  console.error("removeUserMetadata failed:", error);
  if (error instanceof RtmError) {
    console.error(`removeUserMetadata failed: ${error.reason} (code: ${error.errorCode})`);
  }
}

销毁用户账户的过程中，经常见到删除整组 User Metadata 的操作。User Metadata 数据一旦被删除将无法恢复，如果你对数据具有恢复的需求，那么你需要谨慎使用该方法并做好数据备份。

同时，RTM 还会触发一个 UPDATE 类型的 storage 事件通知，并在 100ms 内通知到订阅此 User Metadata 的其他人。storage 详见事件通知。

订阅 User Metadata

与订阅 Channel Metadata 类似，如果你需要关注某个用户的属性更新，那么你可以订阅该用户的 User Metadata，参照以下示例代码：

TypeScript
import { RtmError } from '@shengwang/rtm-full';

try {
  const result = await rtmClient.storage.subscribeUserMetadata("Tony");
  console.log("Subscribed to user metadata:", result.userId);
} catch (error) {
  console.error("subscribeUserMetadata failed:", error);
  if (error instanceof RtmError) {
    console.error(`subscribeUserMetadata failed: ${error.reason} (code: ${error.errorCode})`);
  }
}

以上示例中我们订阅了用户名为 Tony 的 User Metadata，当 Tony 的 User Metadata 变化时 RTM 会触发一个 UPDATE 类型的 storage 事件通知，并在 100 ms 内通知到你。

取消订阅 User Metadata

如果你对不再关注某个用户的 User Metadata 变更，可以取消订阅，参照以下示例代码：

TypeScript
import { RtmError } from '@shengwang/rtm-full';

try {
  const result = await rtmClient.storage.unsubscribeUserMetadata("Tony");
  console.log("Unsubscribed from user metadata:", result.userId);
} catch (error) {
  console.error("unsubscribeUserMetadata failed:", error);
  if (error instanceof RtmError) {
    console.error(`unsubscribeUserMetadata failed: ${error.reason} (code: ${error.errorCode})`);
  }
}

操作成功后，你将不再会收到此 User Metadata 变更通知。

CAS 控制

User Metadata 与 Channel Metadata 类似，也存在 CAS 控制机制。该方法提供两种独立的版本控制字段，你可以根据实际业务场景设置任意一种或多种：

通过 Metadata 中的 majorRevision 属性开启整组 User Metadata 的版本号校验。

通过 MetadataItem 中的 revision 属性开启某个 Metadata Item 的版本号校验。

你可以在需要权限控制的场景中应用 CAS 控制，例如：在交友 App 中同时只允许一位观众与主播连麦，在多人同时发起请求时，只有最先操作的人会成功。

以下示例代码展示了如何使用 majorRevision 和 revision 更新 User Metadata 和 Metadata Item：

TypeScript
import { Metadata, RtmError } from '@shengwang/rtm-full';

// Define metadata with revision control
const metadata: Metadata = {
  majorRevision: 734874892,
  items: [
    { key: 'Avatar', value: 'https://your-domain/avatar/tony.png', revision: 734874812 }
  ]
};

try {
  const result = await rtmClient.storage.updateUserMetadata(
    'Tony',
    metadata,
    {
      recordTs: true,
      recordUserId: true
    }
  );
  console.log('Update user metadata success:', result.userId);
} catch (error) {
  if (error instanceof RtmError) {
    console.error('Update user metadata failed:', error.errorCode, error.reason);
  }
}

上述例子中，我们对 User Metadata 和 Metadata Item Avatar 开启 CAS 验证并设置 majorRevision 为 734874892。服务器在接收到接口调用请求后，会首先验证接口调用提供的 majorRevision 与数据库最新值是否匹配，如果不匹配，则返回错误；如果匹配，则继续验证 Metadata Item 的 revision，逻辑与验证 User Metadata 相同。

如果你开启了版本控制能力，那么你需要关注 storage 事件通知以获取 majorRevision 和 revision 更新后的值，以便于在接口调用时提供最新值。

设置 User Metadata​

获取 User Metadata​

更新 User Metadata​

删除 User Metadata​

订阅 User Metadata​

取消订阅 User Metadata​

CAS 控制​

设置 User Metadata

获取 User Metadata

更新 User Metadata

删除 User Metadata

订阅 User Metadata

取消订阅 User Metadata

CAS 控制