# Topic (/zh-CN/api-reference/rtm/unity/topic) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). **Topic** 是 Stream Channel 中的数据流管理机制。用户可以在 Stream Channel 中利用此特性进行数据流的订阅、分发、事件通知等。 :::info[信息] Topic 只存在于 Stream Channel。所以用户在使用相关特性之前,需要先创建一个 `IStreamChannel` 对象实例。 ::: 想要了解 Topic 的更多特性,可以查看: - [Topic](/zh-CN/realtime-media/rtm/build/channels-and-topics/topics/topic-basic) ## JoinTopicAsync [#jointopicasync] ### 接口描述 [#接口描述] 加入 Topic 操作让用户注册成为此 Topic 的消息发布者(publisher)之一,让其具备发送消息的能力。执行此操作与否并不影响此用户是否成为此 Topic 的订阅者。 :::info[信息] - 当前 RTM 支持单客户端在同一个 Stream Channel 中同时加入 8 个 Topic。 - 在执行此操作之前,用户需要首先创建 `IStreamChannel` 对象实例,并调用 `JoinAsync` 方法加入频道,详见[频道](/zh-CN/realtime-media/rtm/build/channels-and-topics/channel-basic)。 ::: 成功加入 Topic 后,订阅该 Topic 并添加事件监听的用户会收到 `REMOTE_JOIN` 类型的 `OnTopicEvent` 事件通知。 ### 接口方法 [#接口方法] 你可以通过以下方式调用 `JoinTopicAsync` 方法: ```csharp RtmResult JoinTopicAsync(string topic, JoinTopicOptions options); ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | ------ | --------------- | ----- | ------ | -------------- | | `topic` | string | 必填 | - | Topic 名称。 | | `options` | `JoinTopicOptions` | 选填 | - | 加入 Topic 选项。 | `JoinTopicOptions` 包含以下属性: | 属性 | 类型 | 是否必填 | 默认值 | 描述 | | ------------ | -------------- | ----- | -------------- | ---------- | | `qos` | `RTM_MESSAGE_QOS` | 选填 | `ORDERED` | 定义此 Topic 中传输数据是否保序。详见 [`RTM_MESSAGE_QOS`](/zh-CN/api-reference/rtm/unity/enumv#messageqos)。 | | `priority` | `RTM_MESSAGE_PRIORITY` | 选填 | `NORMAL` | 定义此 Topic 中传输数据的优先级(相比于同频道中的其他 Topic)。详见 [`RTM_MESSAGE_PRIORITY`](/zh-CN/api-reference/rtm/unity/enumv#messagepriority)。 | | `meta` | string | 选填 | - | 加入 Topic 时携带的其他辅助信息。 | | `syncWithMedia` | Bool | 选填 | `false` | 此 Topic 中发送的数据是否与共频道的 RTC 音视频数据流实现数据同步(时间戳对齐)。 | ### 基本用法 [#基本用法] ```cs var options = new JoinTopicOptions(); options.qos = RTM_MESSAGE_QOS.ORDERED; var (status,response) = await streamChannel.JoinTopicAsync(topic, options); if (status.Error) { Debug.Log(string.Format("{0} is failed, ErrorCode: {1}, because of: {2}", status.Operation, status.ErrorCode, status.Reason)); } else { Debug.Log(string.Format("User:{0} Join Topic:{1} success! at Channel:{2}", response.UserId, response.Topic, response.ChannelName)); } ``` ### 返回值 [#返回值] `JoinTopicAsync` 操作返回一个 `RtmResult` 类型数据结构的返回值,其中包含: | 属性 | 类型 | 描述 | | ------- | -------------- | ------- | | `Status` | `RtmStatus` | 无论操作是否成功,都返回一个 `RtmStatus` 类型的数据结构,其中包含本次操作的状态。 | | `Response` | `JoinTopicResult` | 操作成功后,返回一个 `JoinTopicResult` 类型的数据结构,其中包含本次操作的执行结果。 | `RtmStatus` 包含以下属性: | 属性 | 类型 | 描述 | | ------- | -- | ------- | | `Error` | bool | 本次操作是否出错。 | | `ErrorCode` | string | 错误码 | | `Operation` | string | 本次操作类型。 | | `Reason` | string | 本次操作出错原因。 | 你可以通过检索 `errorCode` 字段的[错误码](/zh-CN/realtime-media/rtm/build/troubleshooting)了解错误原因,并找到对应的解决方法。 `JoinTopicResult` 包含以下属性: | 属性 | 类型 | 描述 | | ---------- | --- | --------- | | `ChannelName` | string | 频道名称。 | | `UserId` | string | 用户 ID。 | | `Topic` | string | Topic 名称。 | | `Meta` | string | 本次操作设置的附加信息。 | ## PublishTopicMessageAsync [#publishtopicmessageasync] ### 接口描述 [#接口描述-1] `PublishTopicMessageAsync` 方法用于向 Stream Channel 中的 Topic 发送消息,频道中订阅此 Topic 及此消息发布者的用户会在 100 毫秒内收到此消息。调用 `PublishTopicMessageAsync` 方法需要用户首先加入 Stream Channel 并且通过调用 `JoinTopicAsync` 方法注册成为该 Topic 的消息发布者。 用户发送的消息在传输的过程中会被 TLS 加密,数据链路加密默认开启且无法关闭。用户也可以在出初始化的时候开启端侧加密,以获得更高的数据安全等级,详见[初始配置](/zh-CN/api-reference/rtm/unity/configuration)。 ### 接口方法 [#接口方法-1] 你可以通过以下方式调用 `PublishTopicMessageAsync`[1/2] 和 `PublishTopicMessageAsync`[2/2] 方法: ```csharp // PublishTopicMessageAsync[1/2] RtmResult PublishTopicMessageAsync(string topic, byte[] message, TopicMessageOptions option); ``` ```csharp // PublishTopicMessageAsync[2/2] RtmResult PublishTopicMessageAsync(string topic, string message, TopicMessageOptions option); ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | ------ | ---- | ----- | --- | ------------ | | `topic` | string | 必填 | - | Topic 名称。 | | `message` | string/byte[] | 必填 | - | 消息负载。你需要在 `PublishTopicMessageAsync`[1/2] 中填入字节数组类型的消息,或在 `PublishTopicMessageAsync`[2/2] 中填入字符串类型的消息。 | | `options` | `TopicMessageOptions` | 选填 | - | 发布消息的选项。 | `TopicMessageOptions` 包含以下属性: | 属性 | 类型 | 是否必填 | 默认值 | 描述 | | --------- | --- | ----- | --- | ---- | | `sendTs` | UInt64 | 选填 | 0 | 消息端侧发送时间戳,配合 `syncwithMedia` 功能一起使用,当开启音画同步功能时,如果用户此值填 `0`,SDK 将自动帮助用户填写正确时间戳,如果不填 `0`,则按照用户填写的时间戳作为端侧对齐基准。 | | `customType` | string | 选填 | `null` | 用户自定义字段。仅支持字符串型。 | ### 基本用法 [#基本用法-1] ```cs var message = "Hello World"; var topic = "Motion"; var options = new TopicMessageOptions(); options.customType = "PlainText"; var (status,response) = await streamChannel.PublishTopicMessageAsync(topic, message, options); if (status.Error) { Debug.Log(string.Format("{0} is failed, ErrorCode: {1}, due to: {2}", status.Operation, status.ErrorCode, status.Reason)); } ``` ### 返回值 [#返回值-1] `PublishTopicMessageAsync` 操作返回一个 `RtmResult` 类型数据结构的返回值,其中包含: | 属性 | 类型 | 描述 | | ------- | --- | ----- | | `Status` | `RtmStatus` | 无论操作是否成功,都返回一个 `RtmStatus` 类型的数据结构,其中包含本次操作的状态。 | | `Response` | `PublishTopicMessageResult` | 操作成功后,返回一个 `PublishTopicMessageResult` 类型的数据结构,其中包含本次操作的执行结果。当前没有任何数据,用户可以忽略。 | `RtmStatus` 包含以下属性: | 属性 | 类型 | 描述 | | ------- | -- | ------- | | `Error` | bool | 本次操作是否出错。 | | `ErrorCode` | string | 错误码 | | `Operation` | string | 本次操作类型。 | | `Reason` | string | 本次操作出错原因。 | 你可以通过检索 `errorCode` 字段的[错误码](/zh-CN/realtime-media/rtm/build/troubleshooting)了解错误原因,并找到对应的解决方法。 ## LeaveTopicAsync [#leavetopicasync] ### 接口描述 [#接口描述-2] 当你不再需要向某个 Topic 发布消息,你可以调用 `LeaveTopicAsync` 方法取消注册为该 Topic 的消息发布者,从而释放资源。该方法不影响你是否订阅该 Topic,也不影响其他用户对该 Topic 的任何操作。 成功调用该方法后,订阅该频道并开启事件监听的用户会收到 `REMOTE_LEAVE` 类型的 `OnTopicEvent` 事件通知,详见 [事件监听](/zh-CN/api-reference/rtm/unity/configuration#事件监听)。 ### 接口方法 [#接口方法-2] 你可以通过以下方式调用 `LeaveTopicAsync` 方法: ```cs RtmResult LeaveTopicAsync(string topic); ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | ---- | --- | ----- | --- | --------- | | `topic` | string | 必填 | - | Topic 名称。 | ### 接口方法 [#接口方法-3] ```cs var (status,response) = await streamChannel.LeaveTopicAsync("Motion"); if (status.Error) { Debug.Log(string.Format("{0} is failed, ErrorCode: {1}, due to: {2}", status.Operation, status.ErrorCode, status.Reason)); } else { Debug.Log(string.Format("User:{0} Join Topic:{1} success! at Channel:{2}", response.UserId, response.Topic, response.ChannelName)); } ``` ### 返回值 [#返回值-2] `LeaveTopicAsync` 操作返回一个 `RtmResult` 类型数据结构的返回值,其中包含: | 属性 | 类型 | 描述 | | ------- | --------------- | -------- | | `Status` | `RtmStatus` | 无论操作是否成功,都返回一个 `RtmStatus` 类型的数据结构,其中包含本次操作的状态。 | | `Response` | `LeaveTopicResult` | 操作成功后,返回一个 `LeaveTopicResult` 类型的数据结构,其中包含本次操作的执行结果。 | `RtmStatus` 包含以下属性: | 属性 | 类型 | 描述 | | ------- | -- | ------- | | `Error` | bool | 本次操作是否出错。 | | `ErrorCode` | string | 错误码 | | `Operation` | string | 本次操作类型。 | | `Reason` | string | 本次操作出错原因。 | 你可以通过检索 `errorCode` 字段的[错误码](/zh-CN/realtime-media/rtm/build/troubleshooting)了解错误原因,并找到对应的解决方法。 `LeaveTopicResult` 包含以下属性: | 属性 | 类型 | 描述 | | ---------- | --- | --------- | | `ChannelName` | string | 频道名称 | | `UserId` | string | 用户 ID | | `Topic` | string | Topic 名称。 | | `Meta` | string | 本次操作设置的附加信息。 | ## SubscribeTopicAsync [#subscribetopicasync] ### 接口描述 [#接口描述-3] 加入频道后,你可以调用 `SubscribeTopicAsync` 方法订阅该频道中 Topic 的消息发布者。 `SubscribeTopicAsync` 为增量方法。例如,第一次调用该方法时,订阅消息发布者列表为 `[UserA, UserB]`,第二次调用该方法时,订阅消息发布者列表为 `[UserB, UserC]`,则最后成功订阅的结果是 `[UserA, UserB, UserC]`。 同一个用户在同一个频道中最多只能同时订阅 50 个 Topic,且每个 Topic 中最多只能订阅 64 个消息发布者。详见 [API 调用限制](/zh-CN/realtime-media/rtm/reference/usage-limits-and-errors/api-limits)。 ### 接口方法 [#接口方法-4] 你可以通过以下方式调用 `SubscribeTopicAsync` 方法: ```csharp RtmResult SubscribeTopicAsync(string topic, TopicOptions options); ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | ------ | ---------------- | ----- | --- | -------------- | | `topic` | string | 必填 | - | Topic 名称。 | | `options` | `TopicOptions` | 选填 | - | 订阅 Topic 选项。 | `TopicOptions` 中包含以下属性: | 属性 | 类型 | 是否必填 | 默认值 | 描述 | | ---- | ----- | ----- | --- | ------ | | `users` | string[] | 选填 | - | 需要订阅的消息发布者(Publisher)的 `UserId` 列表,如果不设置,则默认随机订阅不超过 64 个用户。 | ### 基本用法 [#基本用法-2] ```cs List userList = new List(); userList.Add("Tony"); userList.Add("Marry"); var options = new TopicOptions(); options.users = userList.ToArray(); var (status,response) = await streamChannel.SubscribeTopicAsync(subtopic, options); if (status.Error) { Debug.Log(string.Format("{0} is failed, ErrorCode: {1}, due to: {2}", status.Operation, status.ErrorCode, status.Reason)); } else { Debug.Log(string.Format("User:{0} Join Topic:{1} success! at Channel:{2}", response.UserId, response.Topic, response.ChannelName)); } ``` ### 返回值 [#返回值-3] `SubscribeTopicAsync` 操作返回一个 `RtmResult` 类型数据结构的返回值,其中包含: | 属性 | 类型 | 描述 | | ------- | ----- | ------------ | | `Status` | `RtmStatus` | 无论操作是否成功,都返回一个 `RtmStatus` 类型的数据结构,其中包含本次操作的状态。 | | `Response` | `SubscribeTopicResult` | 操作成功后,返回一个 `SubscribeTopicResult` 类型的数据结构,其中包含本次操作的执行结果。 | `RtmStatus` 包含以下属性: | 属性 | 类型 | 描述 | | ------- | -- | ------- | | `Error` | bool | 本次操作是否出错。 | | `ErrorCode` | string | 错误码 | | `Operation` | string | 本次操作类型。 | | `Reason` | string | 本次操作出错原因。 | 你可以通过检索 `errorCode` 字段的[错误码](/zh-CN/realtime-media/rtm/build/troubleshooting)了解错误原因,并找到对应的解决方法。 `SubscribeTopicResult` 包含以下属性: | 属性 | 类型 | 描述 | | ----------- | ------- | --------- | | `ChannelName` | string | 频道名称。 | | `UserId` | string | 用户 ID。 | | `Topic` | string | Topic 名称。 | | `SucceedUsers` | string[] | 本次订阅成功的用户列表。 | | `FailedUsers` | string[] | 本次订阅失败的用户列表。 | ## UnsubscribeTopicAsync [#unsubscribetopicasync] ### 接口描述 [#接口描述-4] 如果你对一个或多个 Topic 不再感兴趣,或者不再需要订阅 Topic 中的一个或多个消息发布者,你可以调用 `UnsubscribeTopicAsync` 方法取消订阅该 Topic 或取消订阅该 Topic 中指定的消息发布者。 ### 接口方法 [#接口方法-5] 你可以通过以下方式调用 `UnsubscribeTopicAsync` 方法: ```csharp RtmResult UnsubscribeTopicAsync(string topic, TopicOptions options); ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | ------ | ---------------- | ----- | --- | ----- | | `topic` | string | 必填 | - | Topic 名称。 | | `options` | `TopicOptions` | 选填 | - | 取消订阅 Topic 选项。 | `TopicOptions` 中包含以下属性: | 属性 | 类型 | 是否必填 | 默认值 | 描述 | | ---- | ----- | ----- | --- | ---- | | `users` | string[] | 选填 | - | 需要取消订阅的消息发布者的用户 ID 列表。如果不设置,则取消整个 Topic 的订阅。 | ### 基本用法 [#基本用法-3] ```cs List userList = new List(); userList.Add("Tony"); userList.Add("Marry"); var options = new TopicOptions(); topicOptions.users = userList.ToArray(); var (status,response) = await streamChannel.UnsubscribeTopicAsync(subtopic, options); if (status.Error) { Debug.Log(string.Format("{0} is failed, ErrorCode: {1}, due to: {2}", status.Operation, status.ErrorCode, status.Reason)); } ``` ### 返回值 [#返回值-4] `UnsubscribeTopicAsync` 操作返回一个 `RtmResult` 类型数据结构的返回值,其中包含: | 属性 | 类型 | 描述 | | ------- | ---- | --------- | | `Status` | `RtmStatus` | 无论操作是否成功,都返回一个 `RtmStatus` 类型的数据结构,其中包含本次操作的状态。 | | `Response` | `UnsubscribeTopicResult` | 操作成功后,返回一个 `UnsubscribeTopicResult` 类型的数据结构,其中包含本次操作的执行结果。当前没有任何数据,用户可以忽略。 | `RtmStatus` 包含以下属性: | 属性 | 类型 | 描述 | | ------- | -- | ------- | | `Error` | bool | 本次操作是否出错。 | | `ErrorCode` | string | 错误码 | | `Operation` | string | 本次操作类型。 | | `Reason` | string | 本次操作出错原因。 | 你可以通过检索 `errorCode` 字段的[错误码](/zh-CN/realtime-media/rtm/build/troubleshooting)了解错误原因,并找到对应的解决方法。