调用CreateRtcMPUEventSub创建混流转推事件订阅。
接口说明
本接口用于创建混流转推事件订阅。在创建订阅时,您可以配置回调地址、订阅应用与频道信息等参数。
QPS 限制
本接口的单用户 QPS 限制为 50 次/秒。超过限制,API 调用会被限流,这可能会影响您的业务,请合理调用。更多信息,请参见 QPS 限制。
调试
您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。
授权信息
请求参数
名称 | 类型 | 必填 | 描述 | 示例值 |
---|---|---|---|---|
AppId | string | 是 | 订阅的应用 ID。 说明
应用 ID 由大小写字母、数字、下划线、短划线(-)组成,最大 64 字符。
| yourAppId |
ChannelIds | string | 否 | 指定接收回调的混流任务的频道 ID,可以同时填多个频道 ID,多个频道 ID 之间采用英文逗号“,”隔开。 说明
| yourChannelIds |
CallbackUrl | string | 是 | 回调地址。地址格式请参见以下回调内容规范。 说明
回调地址协议头为 HTTP、HTTPS 等,仅可包含以下字符:a-z 、A-Z、0-9、-、_、?、%、=、#、.、/ 和 +,不超过 2083 个字符。
| http://****.com/callback |
回调内容示例
回调内容以HTTP/HTTPS POST请求发送到您的业务服务器,字符编码格式为UTF-8格式,请求体为 JSON 结构体,当您的业务服务器响应HTTP 状态码为 200时,认定为回调成功。回调内容示例如下:
{
"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 | 签名值 |
回调信息的回调内容包括如下字段:
属性 | 类型 | 描述 | 示例值 |
---|---|---|---|
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 次 |
回调事件的状态转移示例如下: 注意:
- 回调信息有可能会乱序到达您的业务服务器,您可以根据 Payload 中的 EventTs 做事件排序,如果您只关心回调事件的最新状态,可以忽略后续到达的过期事件。
- 对于通过 API创建混流转推任务(新)创建的混流转推任务,当房间内所有用户均离开房间后一段时间,任务会自动停止,停止时会发送一个 MPU_STATE_TERMINATED 的回调。
- 回调配置只影响增量任务,不影响存量任务。即:
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 分钟。每次重试请求均会产生对应的回调记录。
返回参数
示例
正常返回示例
JSON
格式
{
"RequestId": "******3B-0E1A-586A-AC29-742247******",
"SubId": "Sub-******9799B2C4500******"
}
错误码
HTTP status code | 错误码 | 错误信息 |
---|---|---|
400 | InvalidParam | %s |
400 | InvalidAppId | %s |
403 | OperationDenied | Your account has not enabled the Live service |
403 | Forbidden | %s |
404 | MissingParam | %s |
500 | InternalError | InternalError |
访问错误中心查看更多错误码。
变更历史
变更时间 | 变更内容概要 | 操作 |
---|---|---|
2024-07-04 | OpenAPI 错误码发生变更 | 查看变更详情 |