配置对应的回调地址后,当发生相关事件时,视频直播将以 POST 请求的方式,主动向业务服务器发送携带事件信息的 JSON 数据包。
application/json。200 OK。视频直播仅根据 HTTP 状态码判断业务服务器是否成功接收回调消息,不关心应答体的具体内容。为确保回调消息稳定送达,当回调请求失败时,视频直播具备如下重试机制:
推流开始、推流结束、录制、截图和截图审核结果回调消息包含签名参数 sign 和 t。在回调配置中指定回调密钥后,业务服务器可根据签名参数验证请求来源的合法性。
| 参数 | 类型 | 说明 |
|---|---|---|
sign | String | 签名字符串。指定回调密钥后,业务服务器可按以下步骤计算签名,并与回调请求中的
如果计算结果与回调请求中的 说明 未指定回调密钥时,取值为空字符串。 |
t | Long | 签名过期时间,默认为回调请求发起时间的 10 分钟后。Unix 时间戳,单位为秒。 说明
|
当推流开始时,视频直播会向您设置的回调地址发送回调消息。有关如何设置回调地址,详见回调配置。
| 参数 | 类型 | 说明 |
|---|---|---|
| vhost | String | 域名空间。 |
| domain | String | 推流域名。 |
| app | String | AppName。 |
| stream | String | StreamName。 |
| event_type | String | 事件名,固定为 push_start,表示推流开始事件。 |
| sign | String | 公共安全签名参数,用于验证请求来源的合法性。详见公共安全签名参数。 |
| t | Long | 公共安全签名参数,表示请求的过期时间。详见公共安全签名参数。 |
| uniq_id | String | 事件 ID,用于事件去重。 |
| detail | Object of detail | 详细信息。 |
| 参数 | 类型 | 说明 |
|---|---|---|
| priority | Integer | 推流优先级。取值越大,优先级越高。 |
| time | Integer | 开始推流时间。Unix 时间戳,单位为秒。 |
| time_ms | Integer | 开始推流时间。Unix 时间戳,单位为毫秒。 |
transcoded | Boolean | 本次回调对应的流是否为转码流。取值如下:
说明 如需对转码流触发回调,回调配置中必须开启转码流回调,详见回调配置。 |
| fp_node_ip | String | 推流节点 IP 地址。 |
| fp_client_ip | String | 推流客户端 IP 地址。 |
| fp_user_url | String | 推流请求携带的 URL 参数。 |
| location_ip | String | 已废弃。 |
| location_port | Integer | 已废弃。 |
| push_protocol | String | 推流协议。 |
| session_id | String | 本次推流的会话 ID。 |
| sequence_id | String | 本次推流的序列 ID,是一次推流的唯一标识。 |
| stream_params | String | 平台保留参数,无特殊需求可忽略。 |
示例
{ "code": 0, "data": { "app": "live", "detail": { "fp_client_ip": "117.***.**.85", "fp_node_ip": "111.**.***.154", "fp_user_url": "", "location_ip": "10.***.***.45", "location_port": 1935, "priority": 0, "push_protocol": "rtmp", "sequence_id": "1824004938.n.cn-cn3130g1.54012_3287659", "session_id": "1045216675", "stream_params": "", "time": 1787665054, "time_ms": 1787665054820, "transcoded": false }, "domain": "push.example.com", "event_type": "push_start", "sign":"xxxxx", "t":1787747992, "stream": "test", "uniq_id": "push.example.com:live:test_on_publish_start_1045216675", "vhost": "push.example.com" }, "message": "ok" }
当推流结束时,视频直播会向您设置的回调地址发送回调消息。有关如何设置回调地址,详见回调配置。
| 参数 | 类型 | 说明 |
|---|---|---|
| vhost | String | 域名空间。 |
| domain | String | 推流域名。 |
| app | String | AppName。 |
| stream | String | StreamName。 |
| event_type | String | 事件名,固定为 push_end,表示推流结束事件。 |
| sign | String | 公共安全签名参数,用于验证请求来源的合法性。详见公共安全签名参数。 |
| t | Long | 公共安全签名参数,表示请求的过期时间。详见公共安全签名参数。 |
| uniq_id | String | 事件 ID,用于事件去重。 |
| detail | Object of detail | 详细信息。 |
| 参数 | 类型 | 说明 |
|---|---|---|
| time | Integer | 结束推流时间。Unix 时间戳,单位为秒。 |
| time_ms | Integer | 结束推流时间。Unix 时间戳,单位为毫秒。 |
| priority | Integer | 推流优先级。取值越大,优先级越高。 |
| errmsg | String | 推流结束原因。详见断流原因。 |
| err_msg_v2 | String | 推流结束原因。 |
| errcode | Integer | 推流结束码。 |
| fp_node_ip | String | 推流节点 IP 地址。 |
| fp_client_ip | String | 推流客户端 IP 地址。 |
| fp_user_url | String | 推流请求携带的 URL 参数。 |
| location_ip | String | 已废弃。 |
| location_port | Integer | 已废弃。 |
push_duration | Integer | 推流时长,单位为毫秒。该参数会在实际推流时长基础上额外计算 10 分钟的时长。例如实际推流 2 分钟,则该参数取值为 720000(即 720 秒,12 分钟)。 说明 视频直播仅会按实际推流时长计费。 |
| push_protocol | String | 推流协议。 |
| session_id | String | 本次推流的会话 ID。 |
| sequence_id | String | 本次推流的序列 ID,是一次推流的唯一标识。 |
| stream_params | String | 平台保留参数,无特殊需求可忽略。 |
transcoded | Boolean | 本次回调对应的流是否为转码流。取值如下:
说明 如需对转码流触发回调,回调配置中必须开启转码流回调,详见回调配置。 |
示例
{ "code":0, "message":"ok", "data":{ "vhost":"push.example.com", "domain":"push.example.com", "app":"live", "stream":"test", "event_type":"push_end", "sign":"xxxxxx", "t":1787747992, "uniq_id":"push.example.com:live:test_on_publish_stop_1234567890", "detail":{ "time":1640849502, "time_ms":1640849502762, "location_ip":"10.**.**.1", "location_port":1935, "transcoded":false, "priority":0, "errmsg":"func:OnStop:eof", "fp_node_ip":"10.**.**.1", "fp_client_ip":"10.**.**.2", "fp_user_url":"", "session_id":"3693930911_150.139.1.1", "stream_params":"", "sequence_id":"027-20241313130E.1231423483", "push_duration":720000, "errcode":0, "err_msg_v2":"The reason for the streaming disconnection is unknown", "push_protocol":"rtmp" } } }
当存储直播录制文件时,视频直播会向您设置的回调地址发送回调消息。有关如何设置回调地址,详见回调配置。
注意
如需存储录制文件至 TOS(对象存储),请先联系技术支持开启该功能。
| 参数 | 类型 | 说明 |
|---|---|---|
| account_id | String | 账号 ID。 |
| vhost | String | 域名空间。 |
| domain | String | 推流域名。 |
| app | String | AppName。 |
| stream | String | StreamName。 |
| event_type | String | 事件名,固定为 record_event,表示录制事件。 |
| sign | String | 公共安全签名参数,用于验证请求来源的合法性。详见公共安全签名参数。 |
| t | Long | 公共安全签名参数,表示请求的过期时间。详见公共安全签名参数。 |
| detail | Object of detail | 详细信息。 |
| 参数 | 类型 | 说明 |
|---|---|---|
tos_bucket | String | 录制文件保存在 TOS 中的 bucket 名称。 说明 仅当存储录制文件到 TOS 时有值。 |
tos_object | String | 录制文件路径。
|
uri | String | 录制文件在 VOD(点播)中的 说明 仅当存储录制文件到 VOD 时有值。 |
| duration | Integer | 录制长度,单位为毫秒。 |
| duration_ms | Integer | 已废弃。 |
| start_time | Integer | 录制开始时间。Unix 时间戳,单位为秒。 |
| start_time_ms | Integer | 已废弃。 |
| stop_time | Integer | 录制结束时间。Unix 时间戳,单位为秒。 |
format | String | 录制格式。取值如下:
|
url | String | 存储在 TOS 的录制文件地址。 说明 仅当存储录制文件到 TOS 时有值。您可通过 |
| data_source | String | 已废弃。 |
| account_id | String | 账号 ID。 |
| task_id | String | 录制任务 ID。 |
| size | Long | 录制文件的大小,单位为字节。 |
| width | Integer | 录制文件的宽度,单位为 px。 |
| height | Integer | 录制文件的高度,单位为 px。 |
| extra | String | 已废弃。 |
| s3_endpoint | String | 已废弃。 |
| codec | String | 已废弃。 |
vod_filename | String | 录制文件在 VOD 中的路径。 说明 仅当存储录制文件到 VOD 时有值。 |
示例
{ "code":0, "message":"ok", "data":{ "account_id":"10000**", "vhost":"push.example.com", "domain":"push.example.com", "app":"live", "stream":"test", "event_type":"record_event", "sign":"xxxx", "t":1787747992, "detail":{ "tos_bucket":"", "tos_object":"record/push.example.com/live/test_1640847072_1640849947_record.m3u8", "uri":"v0df17g10000ca6ut9pka0prk****pig", "duration":2868674, "duration_ms":2868674, "start_time":1640847072, "start_time_ms":0, "stop_time":1640849947, "format":"m3u8", "url":"", "data_source":"", "account_id":"10000**", "task_id":"1234", "size":28361, "width":1280, "height":720, "extra":"{}", "s3_endpoint":"", "codec":"", "vod_filename":"record/push.example.com/live/test_1640847072_1640849947_record.m3u8" } } }
{ "code": 0, "message": "ok", "data": { "account_id":"10000**", "vhost": "push.example.com", "domain": "push.example.com", "app": "live", "stream": "test", "event_type": "record_event", "sign":"xxxx", "t":1787747992, "detail": { "tos_bucket": "livetest", "tos_object": "record/record/push.example.com/live/test/1653469134_1653469220.m3u8", "uri": "", "duration": 84430, "duration_ms":84430, "start_time": 1653469134, "start_time_ms":0, "stop_time": 1653469220, "format": "m3u8", "url": "http://livetest.tos.volces.com/record/record/push.example.com/live/test/1653469134_1653469220.m3u8", "data_source":"", "account_id":"10000**", "task_id":"1234", "size": 689, "width":1280, "height":720, "extra":"{}", "s3_endpoint":"", "codec":"", "vod_filename":"" } } }
当存储直播截图时,视频直播会向您设置的回调地址发送回调消息。有关如何设置回调地址,详见回调配置。
注意
如需存储直播截图至 TOS(对象存储),请先联系技术支持开启该功能。
| 参数 | 类型 | 说明 |
|---|---|---|
| Vhost | String | 域名空间。 |
| Domain | String | 推流域名。 |
| App | String | AppName。 |
| Stream | String | StreamName。 |
| StreamURL | String | 已废弃。 |
Bucket | String | 截图保存在 TOS 中的 bucket 名称。 说明 仅当存储截图到 TOS 时返回该参数。 |
| ObjectKey | String | 截图的存储路径。 |
| Height | Integer | 图片高度,单位为 px。 |
| Width | Integer | 图片宽度,单位为 px。 |
Format | String | 图片格式。取值如下:
|
| TimeStamp | Integer | 截图时间。Unix 时间戳,单位为秒。 |
| AccountId | String | 账号 ID。 |
ImageXURI | String | 截图存储在 veImageX 时,veImageX 为图片分配的资源 URI。 说明 仅当存储截图到 veImageX 时返回该参数。 |
ServiceID | String | 截图存储在 veImageX 时,veImageX 的服务 ID。 说明 仅当存储截图到 veImageX 时返回该参数。 |
| event_type | String | 事件名,固定为 snapshot_event,表示截图事件。 |
| sign | String | 公共安全签名参数,用于验证请求来源的合法性。详见公共安全签名参数。 |
| t | Long | 公共安全签名参数,表示请求的过期时间。详见公共安全签名参数。 |
示例
{ "Vhost": "push.example.com", "Domain": "push.example.com", "App": "live", "Stream": "test", "StreamURL":"", "ObjectKey": "push.example.com/live/test/2022052510115****.jpg", "Height": 1080, "Width": 1920, "Format": "jpg", "TimeStamp": 1653473517, "AccountId": "2000****74", "event_type":"snapshot_event", "ImageXURI": "tos-cn-i-exampleid/2022052510115****.jpg", "sign":"xxxx", "t":1787747992, "ServiceID": "exampleid" }
{ "Vhost":"push.example.com", "Domain":"push.example.com", "App":"live", "Stream":"test", "StreamURL":"", "Bucket":"bucket1", "ObjectKey":"push.example.com/live/test/20211****.jpeg", "Height":864, "Width":480, "Format":"jpeg", "TimeStamp":1640849845, "AccountId": "2000****74", "event_type":"snapshot_event", "sign":"xxxx", "t":1787747992 }
当拉流转推任务开始、结束、开始转推直播或点播、发生告警或断流时,视频直播会向您设置的回调地址发送回调消息。有关如何设置回调地址,详见拉流转推。
| 参数 | 类型 | 说明 |
|---|---|---|
action | String | 触发本次回调的事件类型。
|
description | String | 简要描述导致断流或告警的原因。 说明 仅当 |
| event_time | Integer | 触发本次回调的时间。Unix 时间戳,单位为纳秒。 |
| task_id | String | 拉流转推任务 ID。 |
| dst | String | 推流地址。 |
type | Integer | 视频来源类型。取值如下:
|
cycle_mode | Integer | 点播文件的循环方式。取值如下:
说明 仅当视频来源为点播( |
| event_type | String | 事件名,固定为 live_pull_to_push,表示拉流转推事件。 |
src | String | 视频来源的地址。
|
play_progress | Float | 当前点播素材的播放时长。单位为秒,保留 2 位小数。 说明 仅当视频来源为点播( |
| msg | Object of CallbackMsg | 详细信息。 |
| 参数 | 类型 | 说明 |
|---|---|---|
type | String | 回调消息类型。
|
| error | String | 错误类型。仅当回调消息包含异常信息时返回。 |
| message | String | 错误详情。仅当回调消息包含异常信息时返回。 |
示例
{ "action":"stop", "description": "src_addr_invalid", "event_time":1650263223542095385, "task_id":"5f4c37605b7d711b51e28d73fa60****", "dst":"rtmp://push.example.com/live/teststream", "type":1, "cycle_mode":-1, "event_type": "live_pull_to_push", "src":"http://pull.example.com/live/test.m3u8", "play_progress":10.00, "msg": { "type": "PullFileFailed", "error": "HTTP_NOT_FOUND", "message": "Server returned 404 Not Found" } }
当存储直播审核截图时,视频直播会向您设置的回调地址发送回调消息。有关如何设置回调地址,详见回调配置。
| 参数 | 类型 | 说明 |
|---|---|---|
| Vhost | String | 域名空间。 |
| Domain | String | 推流域名。 |
| App | String | AppName。 |
| Stream | String | StreamName。 |
| EventType | String | 事件名,固定为 scan_screenshoot_event,表示截图审核事件。 |
| sign | String | 公共安全签名参数,用于验证请求来源的合法性。详见公共安全签名参数。 |
| t | Long | 公共安全签名参数,表示请求的过期时间。详见公共安全签名参数。 |
| EventData | Object of EventData | 详细信息。 |
| EventTime | String | 触发本次回调的时间。RFC3339 格式的时间字符串,精度为秒。 |
| EventId | String | 事件 ID,用于事件去重。 |
| CallbackURL | Array of String | 已废弃。 |
| 参数 | 类型 | 说明 |
|---|---|---|
| MediaType | Integer | 可能违规的内容类型。截图审核的默认取值为 1,表示直播截图。 |
| Image | String | 审核截图在 veImageX 的存储路径。 |
HitLabels | Array of String | 截图的违规原因。取值如下:
|
| RiskHit | Array of Risk | 命中的违规列表。 |
| RiskALL | Array of Risk | 已配置的所有模型列表。 |
Decision | String | 根据违规命中情况,给出的操作建议。取值如下:
|
| AIResultOrigin | String | 审核平台返回的响应原数据。 |
| 参数 | 类型 | 说明 |
|---|---|---|
Label | String | 截图命中的违规类型标签。取值如下:
|
| SubLabel | String | 截图命中的违规子类型标签。 |
Decision | String | 根据违规命中情况,给出的操作建议。取值如下:
|
示例
{ "Vhost": "push.example.com", "Domain": "push.example.com", "App": "live", "Stream": "test", "EventType": "scan_screenshoot_event", "sign": "xxxx", "t": 1659080320, "EventData": { "MediaType": 1, "Image":"tos-mya-i-asd****dcy/1787889583110.jpg", "HitLabels": [ "301" ], "RiskHit": [ { "Label": "301", "SubLabel": "301001", "Decision": "BLOCK" }, { "Label": "301", "SubLabel": "301002", "Decision": "BLOCK" } ], "RiskALL": [ { "Label": "301", "SubLabel": "301001", "Decision": "BLOCK" }, { "Label": "301", "SubLabel": "301002", "Decision": "BLOCK" } ], "Decision": "BLOCK", "AIResultOrigin": "{\"RequestId\":\"202207291528410102091561590F291DAA\",\"Code\":0,\"Message\":\"success\",\"Data\":{\"DataId\":\"7125691570795811116\",\"Decision\":\"BLOCK\",\"Results\":[{\"Label\":\"301\",\"SubLabel\":\"301001\",\"Decision\":\"BLOCK\",\"score\":0,\"Detail\":null,\"Frames\":null},{\"Label\":\"301\",\"SubLabel\":\"301002\",\"Decision\":\"BLOCK\",\"score\":0,\"Detail\":null,\"Frames\":null}],\"Scores\":null}}" }, "EventTime": "2022-07-29T15:28:40+08:00", "EventId": "71256915707958766**", "CallbackURL": [""] }
| 参数 | 类型 | 说明 |
|---|---|---|
| vhost | String | 域名空间。名称。 |
| app | String | 应用名称。 |
| stream | String | 流名称。 |
| event_type | String | 事件名,固定值为 record_ts,表示拉流录制任务状态回调。 |
record_status | String | 事件名。
|
| task_id | String | 任务 ID。 |
| tos_bucket | Object | 保存在对象存储中时的详细信息,见下表。 |
| vod_namespace | Object | 保存到视频点播中时的详细信息,见下表。 |
| service_id | String | 截图存储在 veImageX 时,veImageX 的服务 ID。 |
| time | Int | 回调时间,单位为秒。 |
| time_ms | Int | 回调时间,单位为毫秒。 |
msg | String | 录制状态回调消息,当
|
| 参数 | 类型 | 说明 |
|---|---|---|
| flv | String | FLV 录制的 bucket ,设置为空时不展示。 |
| hls | String | HLS 录制的 bucket ,设置为空时不展示。 |
| mp4 | String | MP4 录制的 bucket ,设置为空时不展示。 |
| 字段 | 类型 | 说明 |
|---|---|---|
| flv | String | FLV 录制的 namespace ,设置为空时不展示。 |
| hls | String | HLS 录制的 namespace ,设置为空时不展示。 |
| mp4 | String | MP4 录制的 namespace ,设置为空时不展示。 |
示例
{ "code":0, "message":"ok", "data":{ "vhost":"live.example.push.com", "app":"live", "stream":"livestream001", "event_type":"record_ts", "detail":{ "record_status":"record_stop", "task_id":"f831f3b0********1aa4dcf7621", "tos_bucket":{ // 对象存储信息为空 }, "vod_namespace":{ "hls":"live**tt" }, "time":1688717870, "time_ms":1688717870948, "msg":"CreateRelaySourceError" } } }
{ "code":0, "message":"ok", "data":{ "vhost":"push.example.com", "app":"live", "stream":"livestream001", "event_type":"record_ts", "detail":{ "record_status":"record_started", "task_id":"f831f3b0********1aa4dcf7621", "tos_bucket":{ "hls":"live-****-test1" }, "vod_namespace":{ // 点播空间内容为空 }, "time":1688717767, "time_ms":1688717767506, "msg":"" } } }
常见的断流原因如下所示。如您获取的断流原因不在下表或您无法判断处理方法,请创建工单联系技术支持进行处理。
| errmsg | 说明 |
|---|---|
| func:HandleInputPacket:net:func:Input:rtmp:FLV Signature don't match | FLV 协议解析失败导致推流断开。 |
| func:HandleInputPacket:net:func:Input:rtmp:close stream id 0 don't match 1 | RTMP 协议不兼容导致推流断开。 |
| func:conn.Read:net:local error: tls: bad record MAC | TLS 协议失败导致推流断开。 |
| func:timeout:idle_too_long | 推流端长时间没有数据传输导致超时断开。 |
| io:conn_reset_by_peer | 推流端非通过正常停止直播操作导致的推流断开,如网络中断、直接关闭推流软件等。 |
| func:conn.Read:net:read_i/o_timeout | 视频直播中心数据 I/O 错误导致的推流断开。 |
| param:Priority:priority | 被高优先级流推流导致的低优先级流推流断开。 |
| auth:JudgePublishAuth:timeout:invalid_sign | URL 鉴权参数字段无效、鉴权超时等原因导致推流断开。 |
| func:OnStatus:func:RtmpStatusCode2NssError:not_allowed | 直播流被禁用导致的推流断开。 |
| func:OnStatus:func:RtmpStatusCode2NssError:api_close | 调用 KillStream 接口断开直播。 |
| func:sendEvent:param:receiver:not_running | 视频直播中心内部错误,请联系技术支持。 |
| auth:remote_auth:not_allowed | 远程鉴权失败导致推流断开。 |
| func:conn.Read:eof | 复杂原因导致的推流断开,请联系技术支持。 |
| func:OnStop:eof | 推流端通过停止直播功能正常结束推流。 |
| func:conn.Read:net:The socket was properly connected, but the connection has been broken | 网络异常导致推流断开。 |
| func:OnStatus:func:RtmpStatusCode2NssError:duplicate | 使用相同流名称,进行推流导致推流断开。 |