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