调用CreateEventSubscribe创建订阅房间消息的回调。

使用说明

本接口用于创建订阅房间消息的回调。例如：在创建回调时，您可以配置回调地址、事件类型等参数。

QPS限制

本接口的单用户QPS限制为1000次/分钟。超过限制，API调用会被限流，这可能会影响您的业务，请合理调用。更多信息，请参见QPS限制。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

请求参数

名称 类型 是否必选 示例值 描述
Action String 是 CreateEventSubscribe

系统规定参数。取值：CreateEventSubscribe。

AppId String 是 9qb1****

订阅的应用ID。
ChannelId String 否 123333

订阅的频道ID。

说明 如果Users.N参数不为空，则此参数必填。
CallbackUrl String 是 http://****.com/callback

回调地址。回调内容请参见以下回调内容示例。
ClientToken String 是 123e4567-e89b-12d3-a456-42665544****

客户端创建订阅的幂等标识。
NeedCallbackAuth Boolean 否 false

是否开启回调鉴权，取值：

  • true：开启。
  • fasle（默认值）：关闭。

详细信息请参见以下回调鉴权说明。
Role Long 否 1

用户角色，取值：

  • 1：订阅频道中的主播消息。
  • 2：订阅频道中的观众消息。
  • 空或其他值：不进行角色过滤，订阅频道中的所有角色的消息。
Users.N String 否 user1

订阅哪些用户的消息，参数为空表示订阅该房间全部用户（包含主播和观众）。格式如下所示：


Users.1=****
Users.2=****
......
Events.N String 是 ChannelEvent

订阅的事件，取值：

  • ChannelEvent：频道事件。
  • UserEvent：频道内用户事件。

详细信息请参见以下表格说明。

CallBack

RTC通过用户传入的CallbackUrl，回调用户的内容，示例如下所示：


Request:

POST /callbackURL

Body
(x-www-form-urlencoded)

{
    "MsgId": "消息ID",
    "MsgTimestamp": 12312324, // 消息发送时的Unix时间戳
    "SubscribeID": "订阅ID",
    "AppId":"",     // 产生该消息的appid 
    "ChannelID":"", // 产生该消息的频道
    "Contents": [
      {
        "Event": "UserEvent",//订阅的事件：频道内用户事件
        "UserEvent": {
          "UserId": "80331631628db0d1",    // 用户ID
          "EventTag": "Publish",    // 事件，包括Join, Leave, Publish, Unpublish, Roleupdate
          "SessionId": "0dr15rrnhkz0jnvz6o8sxo01hoondhu1", // 产生该事件的SessionID
          "Timestamp": 1609854786,    // 事件发生Unix 时间戳
          "Reason": 1, // 入会、离会原因，仅Join事件有
          "Role": 1, //  角色类型, 主播，观众
          "TerminalType": 1, // 终端类型, win, android
          "UserType":1, // 用户类型，native sdk, applete, webrtc
          "Medias":[1,2,3] // 推流类型：用户推了哪些流
        }
      },
      {
        "Event": "ChannelEvent",//订阅的事件：频道事件
        "ChannelEvent": {
          "ChannelId": "8888889999",
          "EventTag": "Open",   // 频道事件，包括开启与关闭Open, Close
          "Timestamp": 1609854530 // 事件发生Unix 时间戳
        }
      }
   ]
}

Response 
HTTP STATUS 200

UserEvent用户事件

参数

类型

是否必须

描述

UserId

string

是

用户ID。

SessionId

string

是

用户SessionID。

EventTag

string

是

事件类型，取值：

  • Join：入会。
  • Leave：离会。
  • PublishVideo：开始推视频流。
  • PublishAudio：开始推音频流。
  • PublishScreen：开始屏幕共享。
  • UnpublishVideo：停止推视频流。
  • UnpublishAudio：停止推音频流。
  • UnpublishScreen：停止屏幕共享。
  • Roleupdate：角色切换。

Timestamp

number

是

事件发生的时间戳。

Reason

integer

是

入会、离会原因（仅Join事件有），取值：

  • 1：正常入会、离会。
  • 2：重连入会（当前会中已有该用户实例，该用户再次入会）。
  • 3：跨频道转推。
  • 4：超时离会。
  • 5：用户启用新的会话，当前会话被挤下线。
  • 6：被踢出。
  • 7：频道解散。

Role

integer

是

角色类型，取值：

  • 1：主播。
  • 2：观众。

TerminalType

integer

是

终端类型，取值：

  • 1：Windows设备。
  • 2：Android设备。
  • 3：Mac设备。
  • 4：iOS设备。
  • 5：Linux设备。
  • 6：其他（只有Native SDK入会可以解析终端类型)。

UserType

integer

是

用户类型，取值：

  • 1：Native SDK。
  • 2：WebRTC(非小程序，非Native都归为WebRTC)。
  • 3：小程序。

Medias

integer

是

推流类型，取值：

  • 1：音频。
  • 2：视频。
  • 3：屏幕共享。

ChannelEvent频道事件

参数

类型

是否必须

描述

EventTag

string

是

事件类型，取值：

  • Open：会议开始。
  • Close：会议结束。

Timestamp

number

是

事件发生的时间戳。

回调鉴权说明

事件回调鉴权功能默认关闭，用户可在创建事件回调时启用鉴权。启用鉴权后，鉴权逻辑如下所示：

  • 阿里云音视频通信服务发起回调请求时在HTTP(S)请求头中包含Ali-Rtc-Timestamp和 Ali-Rtc-Signature字段，供回调消息接收服务端进行签名认证。Ali-Rtc-Timestamp值计算方式为：Ali-Rtc-Signature=MD5SUM(MD5CONTENT)。其中，MD5CONTENT=回调域名|Ali-Rtc-Timestamp取值|鉴权Key；回调域名指配置回调URL的域名，鉴权Key指用户创建AppId时生成的AppKey。
  • 回调消息接收服务端接收回调消息时，将回调域名、Ali-Rtc-Timestamp取值、鉴权Key进行拼接后计算MD5值，得到加密字符串，再将计算出的加密字符串与音视频通信服务发起的HTTP(S)请求头中的Ali-Rtc-Signature字段值进行对比，如果不一致，则请求非法。

返回数据

名称 类型 示例值 描述
SubscribeId String ad53276431c****

创建的订阅ID。
RequestId String 760bad53276431c499e30dc36f6b26be

请求ID。

示例

请求示例

http(s)://rtc.aliyuncs.com/?Action=CreateEventSubscribe
&AppId=9qb1****
&CallbackUrl=http://****.com/callback
&ClientToken=123e4567-e89b-12d3-a456-42665544****
&Events.1=ChannelEvent
&<公共请求参数>

正常返回示例

XML格式 

HTTP/1.1 200 OK
Content-Type:application/xml

<CreateEventSubscribeResponse>
<RequestId>760bad53276431c499e30dc36f6b26be</RequestId>
<SubscribeId>ad53276431c****</SubscribeId>
</CreateEventSubscribeResponse>

JSON格式 

HTTP/1.1 200 OK
Content-Type:application/json

{
  "RequestId" : "760bad53276431c499e30dc36f6b26be",
  "SubscribeId" : "ad53276431c****"
}