创建订阅房间消息回调

更新时间: 2023-08-04 18:45:51

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

使用说明

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

QPS限制

本接口的单用户QPS限制为100次/秒。超过限制,API调用会被限流,这可能会影响您的业务,请合理调用。

调试

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

请求参数

名称

类型

是否必选

示例值

描述

Action String CreateEventSub

系统规定参数。取值:CreateEventSub

AppId String 9qb1****

订阅的应用ID。

ChannelId String 123333

订阅的频道ID。

说明

如果Users.N参数不为空,则此参数必填。

Users.N String user1

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

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

订阅的事件,取值:

  • ChannelEvent:频道事件。

  • UserEvent:频道内用户事件。

CallbackUrl String http://****.com/callback

回调地址。回调内容请参见以下回调内容示例。

ClientToken String 123e4567-e89b-12d3-a456-42665544****

客户端创建订阅的幂等标识。

Role Integer 1

用户角色,取值:

  • 1:订阅频道中的主播消息。

  • 2:订阅频道中的观众消息。

  • 空或其他值:不进行角色过滤,订阅频道中的所有角色的消息。

NeedCallbackAuthorization Boolean false

是否开启回调鉴权,取值:

  • true:开启。

  • fasle(默认值):关闭。

CallBack

通过用户传入的CallbackUrl,回调用户的内容,示例如下所示:

Request:

POST /callbackURL

Body
application/json

{
    "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, //  角色类型, 主播,观众
          "CurrentMedias":"1,2,3"// 推流类型:用户推了哪些流
        }
      },
      {
        "Event": "ChannelEvent",//订阅的事件:频道事件
        "ChannelEvent": {
          "ChannelId": "8888889999",
          "EventTag": "Open",   // 频道事件,包括开启与关闭Open, Close
          "Timestamp": 1609854530 // 事件发生Unix 时间戳
        }
      }
   ]
}

Response 
HTTP STATUS 200

UserEvent用户事件

参数类型是否必填描述
UserIdstring用户ID。
SessionIdstring用户SessionID。
EventTagstring事件类型,取值:
Join:入会。
Leave:离会。
PublishVideo:开始推视频流。
PublishAudio:开始推音频流。
PublishScreen:开始屏幕共享。
UnpublishVideo:停止推视频流。
UnpublishAudio:停止推音频流。
UnpublishScreen:停止屏幕共享。
Roleupdate:角色切换。
Timestampnumber事件发生的时间戳。
Reasoninteger入会、离会原因(仅Join事件有),取值:
1:正常入会、离会。
2:重连入会(当前会中已有该用户实例,该用户再次入会)。
3:跨频道转推。
4:超时离会。
5:用户启用新的会话,当前会话被挤下线。
6:被踢出。
7:频道解散。
Roleinteger角色类型,取值:
1:主播。
2:观众。
CurrentMediasinteger推流类型,取值:
1:音频。
2:视频。
3:屏幕共享。

ChannelEvent频道事件

参数类型是否必填描述
EventTagstring事件类型,取值:
Open:会议开始。
Close:会议结束。
Timestampnumber事件发生的时间戳。

回调鉴权说明

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

  • 阿里云视频直播服务发起回调请求时在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字段值进行对比,如果不一致,则请求非法。

返回数据

名称

类型

示例值

描述

RequestId String 760bad53276431c499e30dc36f6b26be

请求ID。

SubscribeId String ad53276431c****

创建的订阅ID。

示例

请求示例

http(s)://live.aliyuncs.com/?Action=CreateEventSub
&AppId=9qb1****
&ChannelId=123333
&Users=["user1"]
&Events=["ChannelEvent"]
&CallbackUrl=http://****.com/callback
&ClientToken=123e4567-e89b-12d3-a456-42665544****
&Role=1
&公共请求参数

正常返回示例

XML格式

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

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

JSON格式

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

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

错误码

访问错误中心查看更多错误码。

阿里云首页 视频直播 相关技术圈