全部产品
Search

搜索本产品

    ：创建订阅房间消息回调

    文档中心

    ：创建订阅房间消息回调

    更新时间：May 16, 2024

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

    使用说明

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

    QPS限制

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

    调试

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

    请求参数

    名称

    类型

    是否必选

    示例值

    描述
    Action String 是 CreateEventSub

    系统规定参数。取值：CreateEventSub。
    AppId String 是 9qb1****

    订阅的应用ID。
    ChannelId String 否 123333

    订阅的频道ID。您可通过调用ListEventSub接口查询订阅的频道ID。

    说明
    • 如果Users.N参数不为空，则此参数必填。
    • ChannelId为*或者不填，表示为全频道订阅，每个AppId只允许1个全频道订阅。
    • 每个AppId最多同时允许创建20个订阅。
    Users.N String 否 user1

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

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

    订阅的事件，取值：

    • ChannelEvent：频道事件。
    • UserEvent：频道内用户事件。
    CallbackUrl String 是 http://****.com/callback

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

    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用户事件

    参数

    类型

    是否必填

    描述

    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：观众。

    CurrentMedias

    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字段值进行对比，如果不一致，则请求非法。

    回调异常重试

    阿里云发起回调请求时，仅当您的业务服务器响应HTTP状态码为200时认定为回调成功。若回调失败，阿里云会重试7次，分别间隔1秒、2秒、5秒、10秒、1分钟、2分钟、5分钟。每次重试请求均会产生对应的回调记录。

    异常处理

    已经入会或者推流的客户端和阿里云的服务端有心跳保活机制，当客户端因为断网、App关闭异常等原因导致心跳保活失败（90秒未收到客户端心跳信息则认定为失败），服务端会判定客户端异常超时离开，并产生用户停止推流和离会的事件回调。

    返回数据

    名称

    类型

    示例值

    描述
    RequestId String 760bad53276431c499e30dc36f6b26be

    请求ID。
    SubscribeId String ad53276431c****

    创建的订阅ID。

    示例

    请求示例

    http(s)://[Endpoint]/?Action=CreateEventSub
&AppId=9qb1****
&ChannelId=123333
&Users=["user1"]
&Events=["ChannelEvent"]
&CallbackUrl=http://****.com/callback
&公共请求参数

    正常返回示例

    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****"
}

    错误码

    HttpCode

    错误码

    错误信息

    描述
    400 InputInvalid %s. 输入参数不合法
    400 QuotaLimitError %s. 每个AppId，最多同时允许创建20个订阅，并且只允许1个全频道订阅
    400 ErrorInvalidCallBackUrl %s. CallBackURL无效，请检查后重新尝试。
    403 NoAuth %s. 没有权限
    404 ResourceNotExist %s. 请求资源不存在，请检查后重新尝试
    500 ServerError %s. 未知错误，请稍后重试或提交工单咨询。

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