调用CreateRtcMPUEventSub创建混流转推事件订阅。
使用说明
本接口用于创建混流转推事件订阅。在创建订阅时，您可以配置回调地址、订阅应用与频道信息等参数。
QPS限制
本接口的单用户QPS限制为50次/秒。超过限制，API调用会被限流，这可能会影响您的业务，请合理调用。更多信息，请参见QPS限制。
调试
您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。
请求参数
|
名称 |
类型 |
是否必选 |
示例值 |
描述 |
| Action | String | 是 | CreateRtcMPUEventSub | 系统规定参数。取值：CreateRtcMPUEventSub。 |
| AppId | String | 是 | yourAppId | 订阅的应用ID。 说明 应用ID由大小写字母、数字、下划线、短划线（-）组成，最大64字符。 |
| ChannelIds | String | 否 | yourChannelIds | 指定接收回调的混流任务的频道ID，可以同时填多个频道ID，多个频道ID之间采用英文逗号“,”隔开。 说明
|
| CallbackUrl | String | 是 | http://****.com/callback | 回调地址。地址格式请参见以下回调内容规范。 说明 回调地址协议头为HTTP、HTTPS等，仅可包含以下字符：a-z 、A-Z、0-9、-、_、?、%、=、#、.、/ 和 +，不超过2083个字符。 |
回调内容示例
回调内容以HTTP/HTTPS POST请求发送到您的业务服务器，字符编码格式为UTF-8格式，请求体为JSON结构体，当您的业务服务器响应HTTP状态码为200时，认定为回调成功。回调内容示例如下：
{
"EventType": 1,
"MsgId": "42bba8b5-94ab-468c-9dae-9b501dd6cb6e",
"AppId": "rtcdev",
"SubId": "Sub-9799B2C45009799B2C4500",
"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 |
签名值 |
回调信息的回调内容包括如下字段：
属性 |
类型 |
描述 |
示例值 |
EventType |
Integer |
回调事件类型，对于混流转推回调，类型为固定值：1 |
1 |
MsgId |
String |
回调ID，唯一表示本次回调 |
***973C-4529-A334*** |
AppId |
String |
订阅的应用ID |
yourAppId |
SubId |
String |
订阅ID |
Sub-****9799B2C4500**** |
TaskId |
String |
旁路任务ID |
yourTaskId |
CallbackTs |
Integer |
发起回调请求的毫秒时间戳 |
1712656430476 |
Payload |
JSON Object |
回调事件信息 |
- |
- 回调事件信息（Payload）
属性 |
类型 |
描述 |
示例值 |
DstUrl |
String |
转推目的URL地址 |
rtmp://domain/app/stream?auth |
EventTs |
Integer |
回调事件发生的毫秒时间戳 |
1712656430384 |
EventCode |
Integer |
回调事件Code |
1 |
ErrorCode |
Integer |
回调事件的错误码 |
10001 |
ErrorMessage |
String |
回调事件的错误原因 |
rtmp server init failed |
回调事件Code
字段名 |
值 |
含义 |
回调频率 |
MPU_STATE_PREPARING |
0 |
旁路转推任务创建成功，任务被触发 |
仅回调1次 |
MPU_STATE_ESTABLISHING |
1 |
旁路转推任务建联中 |
每5秒回调1次 |
MPU_STATE_RUNNING |
2 |
旁路转推任务运行中 |
仅回调1次 |
MPU_STATE_RECOVERING |
3 |
旁路转推异常中断，正在恢复中 |
每5秒回调1次 |
MPU_STATE_TERMINATED |
4 |
旁路转推任务结束，包括正常停止、启动失败、异常退出等，通过ErrorCode与ErrorMessage区分 |
仅回调1次 |
回调事件的状态转移示例如下：
注意：
1. 回调信息有可能会乱序到达您的业务服务器，您可以根据 Payload 中的 EventTs 做事件排序，如果您只关心回调事件的最新状态，可以忽略后续到达的过期事件。
2. 对于通过API创建混流转推任务（新）创建的混流转推任务，当房间内所有用户均离开房间后一段时间，任务会自动停止，停止时会发送一个MPU_STATE_TERMINATED的回调。
3. 回调配置只影响增量任务，不影响存量任务。即：
a. 开启回调配置前已启动的任务，不发送回调；
b. 开启回调配置后启动的任务，会发送回调；
c. 删除回调配置前已启动的任务，会继续发送回调直到任务结束；
d. 删除回调配置后启动的任务，不发送回调。
回调错误码
当旁路转推任务结束时，通过ErrorCode与ErrorMessage标识结束的原因。
错误码 |
错误信息 |
含义 |
0 |
任务正常停止 |
|
10001 |
rtmp server init failed |
建联失败，任务异常结束 |
10002 |
rtmp server internal error |
服务内部错误，任务异常结束 |
回调鉴权说明
事件回调鉴权功能默认开启，鉴权逻辑如下所示：
- 阿里云视频直播服务发起回调请求时，在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分钟。每次重试请求均会产生对应的回调记录。
返回数据
名称 |
类型 |
示例值 |
描述 |
| RequestId | String | ******3B-0E1A-586A-AC29-742247****** | 请求ID。 |
| SubId | String | Sub-******9799B2C4500****** | 订阅ID。 |
示例
请求示例
http(s)://[live.aliyuncs.com]/?Action=CreateRtcMPUEventSub
&AppId=yourAppId
&ChannelIds=yourChannelIds
&CallbackUrl=http://****.com/callback
&公共请求参数正常返回示例
XML格式
HTTP/1.1 200 OK
Content-Type:application/xml
<CreateRtcMPUEventSubResponse>
<RequestId>******3B-0E1A-586A-AC29-742247******</RequestId>
<SubId>Sub-******9799B2C4500******</SubId>
</CreateRtcMPUEventSubResponse>JSON格式
HTTP/1.1 200 OK
Content-Type:application/json
{
"RequestId" : "******3B-0E1A-586A-AC29-742247******",
"SubId" : "Sub-******9799B2C4500******"
}错误码
访问错误中心查看更多错误码。