全部产品
Search

搜索本产品

    视频直播：CreateEventSub - 创建订阅房间消息回调

    文档中心

    视频直播：CreateEventSub - 创建订阅房间消息回调

    更新时间：Nov 14, 2024

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

    接口说明

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

    QPS 限制

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

    调试

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

    授权信息

    下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

    • 操作：是指具体的权限点。
    • 访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
    • 资源类型：是指操作中支持授权的资源类型。具体说明如下：
      • 对于必选的资源类型，用背景高亮的方式表示。
      • 对于不支持资源级授权的操作，用全部资源表示。
    • 条件关键字：是指云产品自身定义的条件关键字。
    • 关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。
    操作访问级别资源类型条件关键字关联操作
    live:CreateEventSub
    *Rtc
    acs:live::{#accountId}:rtc/{#AppId}
      无
    		无

    请求参数

    名称类型必填描述示例值
    AppIdstring是

    订阅的应用 ID。

    		9qb1****
    ChannelIdstring否

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

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

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

    Users.1=****
Users.2=****
......
    string否

    用户 ID。

    		user1
    Eventsarray是

    订阅事件。

    string是

    订阅的事件，取值：

    • ChannelEvent：频道事件。

    • UserEvent：频道内用户事件。

    		ChannelEvent
    CallbackUrlstring是

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

    		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": "80331631628*****",    // 用户 ID
          "EventTag": "Publish",    // 事件，包括 Join, Leave, Publish, Unpublish, Roleupdate
          "SessionId": "0dr15rrnhkz0jnvz6o8sxo0*****", // 产生该事件的 SessionID
          "Timestamp": 1609854786,    // 事件发生 Unix 时间戳
          "Reason": 1, // 入会、离会原因，仅 Join 事件有
          "Role": 1, //  角色类型, 主播，观众
          "CurrentMedias":"1,2,3"// 推流类型：用户推了哪些流
        }
      },
      {
        "Event": "ChannelEvent",//订阅的事件：频道事件
        "ChannelEvent": {
          "ChannelId": "88888****",
          "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 字段值进行对比，如果不一致，则请求非法。

    回调异常重试

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

    异常处理

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

    返回参数

    名称类型描述示例值
    object

    Schema of Response

    RequestIdstring

    请求 ID。

    		760bad53276431c499e30dc36f6b****
    SubscribeIdstring

    创建的订阅 ID。

    		ad53276431c****

    示例

    正常返回示例

    JSON格式

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

    错误码

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

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

    变更历史

    变更时间变更内容概要操作
    2023-11-21OpenAPI 错误码发生变更查看变更详情
    2023-11-21OpenAPI 错误码发生变更、OpenAPI 入参发生变更查看变更详情
    2023-08-31OpenAPI 错误码发生变更查看变更详情
    2023-08-04OpenAPI 入参发生变更查看变更详情