云录制 RESTful API 回调服务

云端录制（Jocloud-Cloud-Recording）具备回调通知的功能，具体是：业务可配置一个接收回调的 HTTP/HTTPS 服务器地址，当录制事件发生时，云端录制服务会将事件的消息发送给回调服务器，然后回调服务器会以 HTTP/HTTPS 请求的方式，把事件消息通知给指定的业务服务器以实现云端录制的回调通知。

回调通知配置

满足以下任意一种情况即可使用回调功能：

startrecord 启动录制任务时通过参数 callbackurl 指定接收回调的 HTTP/HTTPS 服务器地址。

回调通知内容

在完成回调配置后，云端录制服务会通过回调服务器以 HTTP/HTTPS 请求向指定的地址发送回调消息。回调消息的具体内容在 POST 请求包体中是以 JSON 对象的形式返回，并且会根据事件类型的不同，对应的字段也不相同。

请求方法：POST
Head：
- Content-type 为 application/json
请求包体中的字段，例如：

{
    "msgid":"RECORD-ec0b460a0000b5794f66e14d5ab7d4ab9c166-17394cfdc6f",
    "product":1,
    "msgtype":2,
    "notifytime":1595929517000,
    "context":{
        "msgname":"recordtask_m3u8_info",
        "appid":123123,
        "roomid":"abcabc",
        "uid":[
            "0"
        ],
        "recordid":"ec0b460a0000b5794f66e14d5ab7d4ab9c166",
        "filetype":"m3u8",
        "duration":9000,
        "fileaddress":"http://xxxxx.m3u8",
        "starttime":1595929495000
    }
}

云录制回调请求的公共字段，所有录制回调中都包含这些字段。
公共字段说明：

名称	类型	含义
msgid	string	云录制回调通知 ID，标识来自云录制服务器的一次事件通知。
product	int	业务 ID 1：云录制取值范围：1
msgtype	int	云端录制事件类型 1：录制任务状态变更事件 2：录制结果事件取值范围：1,2
notifytime	int	回调请求的 Unix 时间戳，单位为毫秒。

云端录制回调请求的 context 字段，内容格式取决于 msgtype 事件类型。

context 字段

context 字段是一个 JSON 对象，包含事件的具体内容。

1 recordtask_status

msgtype 类型为 1 表示录制任务状态变更事件，示例：

{
    "msgid":"RECORD-ee0b460a0000a3994f66e14d5ab7d4b902923-17394cfdb7e",
    "product":1,
    "msgtype":1,
    "notifytime":1595929516926,
    "context":{
        "msgname":"recordtask_status",
        "appid":123123,
        "roomid":"abcabc",
        "uid":[
            "0"
        ],
        "recordid":"ee0b460a0000a3994f66e14d5ab7d4b902923",
        "status":2
    }
}

context 字段：

名称	类型	含义
msgname	string	消息名称，即 "recordtask_status"
appid	int	你的项目使用的appid
roomid	string	录制任务的房间号
uid	JSON Array	录制任务的 uid Note: 混流录制为 "0"
recordid	string	录制任务id
status	int	录制任务状态 0: 初始化完成 1: 任务启动 2: 任务停止
endreason	int	录制任务停止原因 1: 主动停止任务 2: 没数据，任务超时停止 3: 频道无流，任务超时停止 Note: 只有在录制任务停止，该字段才有效

2 recordtask_m3u8_info

msgtype 类型为 2 表示录制结果事件，示例：

{
    "msgid":"RECORD-ec0b460a0000b5794f66e14d5ab7d4ab9c166-17394cfdc6f",
    "product":1,
    "msgtype":2,
    "notifytime":1595929517000,
    "context":{
        "msgname":"recordtask_m3u8_info",
        "appid":123123,
        "roomid":"abcabc",
        "uid":[
            "0"
        ],
        "recordid":"ec0b460a0000b5794f66e14d5ab7d4ab9c166",
        "filetype":"m3u8",
        "duration":9000,
        "fileaddress":"http://xxxxx.m3u8",
        "starttime":1595929495000
    }
}

context 字段：

名称	类型	含义
msgname	string	消息名称，即 "recordtask_m3u8_info"
appid	int	你的项目使用的appid
roomid	string	录制任务的房间号
uid	JSON Array	录制任务的 uid Note: 混流录制为 "0"
recordid	string	录制任务id
filetype	string	录制文件格式，当前只支持"m3u8"
duration	unsigned int	录制文件m3u8的时长，单位毫秒
fileaddress	string	录制文件m3u8的链接
starttime	int	录制文件里最早的帧的时间戳，单位毫秒
upload_status	int	m3u8地址为空时的原因 0：无ts文件 2：文件上传超时 >100：文件HTTP上传返回码，比如：拒绝访问等，可参考具体OSS厂商的错误码

Note:

当录制失败时，录制结果回调事件里的 duration 为 0 ，starttime 为 0 ，fileaddress 为空字符串。此时可检查 upload_status 字段或者主播的上行情况。
当业务只关心录制结果回调事件时，业务可根据 msgtype 类型为 2 来对回调事件做过滤处理。
如果 startrecord 和 stoprecord 的调用时间点很接近，recordtask_m3u8_info 的回调事件可能不会被触发。

注意事项

回调服务器就会在通知失败后马上重试，再次发送回调通知，最多尝试三次。在以下任意一种情况下，回调服务器会认为回调失败：

发送消息通知后，5 秒内没有收到响应。

收到响应的状态码不是 HTTP 200。

事件发生的顺序和业务服务器收到的回调顺序不一定完全一致。
考虑到可靠性，每次事件可能会有多次通知，业务服务器需要能处理重复的回调通知。