CreateRtcMPUEventSub - 创建混流转推事件订阅

创建混流转推事件订阅。

接口说明

本接口用于创建混流转推事件订阅。在创建订阅时,您可以配置回调地址、订阅应用与频道信息等参数。

QPS 限制

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

调试

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

授权信息

当前API暂无授权信息透出。

请求参数

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

订阅的应用 ID。

说明 应用 ID 由大小写字母、数字、下划线、短划线(-)组成,最大 64 字符。
yourAppId
ChannelIdsstring

指定接收回调的混流任务的频道 ID,可以同时填多个频道 ID,多个频道 ID 之间采用英文逗号“,”隔开。

说明
  • 如果不填,则默认接收该 AppId 下所有混流转推任务的回调事件。
  • 同时填多个频道 ID 时,不能填写重复的频道 ID,最多同时填 20 个频道 ID。
  • 每个频道 ID 由大小写字母、数字、下划线、短划线(-)组成,最大 64 字符。
  • yourChannelIds
    CallbackUrlstring

    回调地址。地址格式请参见以下回调内容规范。

    说明 回调地址协议头为 HTTP、HTTPS 等,仅可包含以下字符:a-z 、A-Z、0-9、-、_、?、%、=、#、.、/ 和 +,不超过 2083 个字符。
    http://****.com/callback

    回调内容示例

    回调内容以HTTP/HTTPS POST请求发送到您的业务服务器,字符编码格式为UTF-8格式,请求体为 JSON 结构体,当您的业务服务器响应HTTP 状态码为 200时,认定为回调成功。回调内容示例如下:

    说明 建议在判断混流转推是否正常时,不仅需要根据回调通知判断,也要同时配合接入的对应 CDN 厂商提供的在线流状态判断是否正常。
    {
    	"EventType": 1,
    	"MsgId": "42bba8b5-94ab-468c-9dae-9b501dd****",
    	"AppId": "rtcdev",
    	"SubId": "Sub-9799B2C45009799B2*****",
    	"TaskId": "mpucallbacktest",
    	"CallbackTs": 1712656430476,
    	"Payload": {
    		"DstUrl": "rtmp://domain/app/stream?auth",
    		"EventTs": 1712656430384,
    		"EventCode": 1,
    		"ErrorCode": 0,
    		"ErrorMessage": ""
    	}
    }
    

    回调信息

    回调信息的 header 包括如下字段:

    属性描述
    Content-Type数据类型,固定值:application/json
    Ali-Rtc-Timestamp时间戳
    Ali-Rtc-Signature签名值

    回调信息的回调内容包括如下字段:

    属性类型描述示例值
    EventTypeInteger回调事件类型,对于混流转推回调,类型为固定值:11
    MsgIdString回调 ID,唯一表示本次回调*****973C-4529-A334*****
    AppIdString订阅的应用 IDyourAppId
    SubIdString订阅 IDSub-******9799B2C4500******
    TaskIdString旁路任务 IDyourTaskId
    CallbackTsInteger发起回调请求的毫秒时间戳1712656430476
    PayloadJSON Object回调事件信息-
    • 回调事件信息(Payload)
    属性类型描述示例值
    DstUrlString转推目的 URL 地址rtmp://domain/app/stream?auth
    EventTsInteger回调事件发生的毫秒时间戳1712656430384
    EventCodeInteger回调事件 Code1
    ErrorCodeInteger回调事件的错误码10001
    ErrorMessageString回调事件的错误原因rtmp server init failed

    回调事件 Code

    字段名含义回调频率
    MPU_STATE_PREPARING0旁路转推任务创建成功,任务被触发仅回调 1 次
    MPU_STATE_ESTABLISHING1旁路转推任务建联中每 5 秒回调 1 次
    MPU_STATE_RUNNING2旁路转推任务运行中仅回调 1 次
    MPU_STATE_RECOVERING3旁路转推异常中断,正在恢复中每 5 秒回调 1 次
    MPU_STATE_TERMINATED4旁路转推任务结束,包括正常停止、启动失败、异常退出等,通过 ErrorCode 与 ErrorMessage 区分仅回调 1 次

    回调事件的状态转移示例如下: 注意:

    1. 回调信息有可能会乱序到达您的业务服务器,您可以根据 Payload 中的 EventTs 做事件排序,如果您只关心回调事件的最新状态,可以忽略后续到达的过期事件。
    2. 对于通过 API创建混流转推任务(新)创建的混流转推任务,当房间内所有用户均离开房间后一段时间,任务会自动停止,停止时会发送一个 MPU_STATE_TERMINATED 的回调。
    3. 回调配置只影响增量任务,不影响存量任务。即:

    a. 开启回调配置前已启动的任务,不发送回调;

    b. 开启回调配置后启动的任务,会发送回调;

    c. 删除回调配置前已启动的任务,会继续发送回调直到任务结束;

    d. 删除回调配置后启动的任务,不发送回调。

    回调错误码

    当旁路转推任务结束时,通过 ErrorCode 与 ErrorMessage 标识结束的原因。

    错误码错误信息含义
    0任务正常停止
    10001rtmp server init failed建联失败,任务异常结束
    10002rtmp server internal error服务内部错误,任务异常结束
    10003task idle timeout任务空闲超时后结束

    回调鉴权说明

    事件回调鉴权功能默认开启,鉴权逻辑如下所示:

    • 阿里云视频直播服务发起回调请求时,在 HTTP(S)请求头中包含 Ali-Rtc-Timestamp 和 Ali-Rtc-Signature 字段,供回调消息接收服务端进行签名认证。Ali-Rtc-Signature 值计算方式为: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 分钟。每次重试请求均会产生对应的回调记录。

    返回参数

    名称类型描述示例值
    object
    RequestIdstring

    请求 ID。

    ******3B-0E1A-586A-AC29-742247******
    SubIdstring

    订阅 ID。

    Sub-******9799B2C4500******

    示例

    正常返回示例

    JSON格式

    {
      "RequestId": "******3B-0E1A-586A-AC29-742247******",
      "SubId": "Sub-******9799B2C4500******"
    }

    错误码

    HTTP status code错误码错误信息
    400InvalidParam%s
    400InvalidAppId%s
    403OperationDeniedYour account has not enabled the Live service
    403Forbidden%s
    404MissingParam%s
    500InternalErrorInternalError

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

    变更历史

    变更时间变更内容概要操作
    2024-07-04OpenAPI 错误码发生变更查看变更详情