跳到主要内容

状态回调

融云的云端截图服务，支持将截图的状态变化实时通知您的服务器。

您可以在控制台的云端截图页面，填写接收 HTTP 回调的 URL，配置后 30 分钟内生效。

回调地址示例：http(s)://your.app.server/any-url-path

配置完成后，您的 App 内所有房间的截图有任何状态变更，均会通过 HTTP 请求，实时回调您的服务器。

使用说明：

注意

必须已开通音视频服务和云端截图服务。您填写回调 URL 必须是公网可访问的 URL 地址。

回调方法​

POST：<your-receiving-server-url>

数据格式：application/json

回调地址 <your-receiving-server-url> 是您在控制台为当前 App Key 和服务所配置的回调接收地址。请务必配置可正常访问的回调接收地址。如果您的网络有 IP 访问限制，请务必配置 IP 白名单，否则无法正常接收服务端回调。

为了验证数据有效性并确保调用者为融云 Server，每个请求前添加数据签名。回调签名规则详见服务端回调。

状态回调公共字段说明​

字段名称类型说明
typeNumber1:开始截图；3：截图结束；4：上传文件
sessionIdString这次会话的ID
extraString扩展字段，回调时候透传
appKeyString用户申请的AppKey
roomIdString所在房间ID
imageIdString截图会话 ID
codeNumber状态码
errorMessageString状态描述

截图开始的回调​

云端截图服务会在截图开始时，回调此次截图任务的模式、配置、封装文件格式等信息。

具体字段说明如下：

字段名称类型说明
config.triggerString标志截图服务：手动出发还是自动触发
config.slicesSecString截图间隔
config.renderModeNumber截图模式
config.picResolutionString截图生成的分辨率

回调 Body 示例如下。

请求示例​

POST /any-url-path HTTP/1.1
Host: your.app.server
Content-Type: application/json

{
   "timestamp": 1530027865231,
   "type": 1,
   "appKey": "e0x9wycfx7flq",
   "sessionId": "lSA2G6CUf9A-6nnoNwXCx8",
   "roomId": "111",
   "imageId": "SJGOSOIOAIJFOJAOJOE",
   "extra":"", //扩展字段
   "config": {
       "trigger": 0,
       "slicesSec": 30,
       "renderMode": 1,
       "picResolution": "640x480"
   },
   "code": 200,
   "errorMessage": "Success"
}

截图结束的回调​

云端截图服务在截图完成时会回调相关信息，具体字段说明如下。

字段名称类型说明
config.triggerString标志截图服务：手动出发还是自动触发
config.slicesSecString截图间隔
config.renderModeNumber截图模式
config.picResolutionString截图生成的分辨率

请求示例​

POST /any-url-path HTTP/1.1
Host: your.app.server
Content-Type: application/json

{
   "timestamp": 1530027865231,
   "type": 3,
   "appKey": "e0x9wycfx7flq",
   "sessionId": "lSA2G6CUf9A-6nnoNwXCx8",
   "roomId": "111",
   "imageId": "SJGOSOIOAIJFOJAOJOE",
   "extra":"", //扩展字段
   "config": {
       "trigger": 0,
       "slicesSec": 30,
       "renderMode": 1,
       "picResolution": "640x480"
   },
   "code": 200,
   "errorMessage": "Success"
}

上传文件的回调​

云端截图服务截图完成时会自动上传到您配置的第三方存储。上传成功或失败都会回调相关状态。

具体字段说明如下。

字段名称类型说明
参数说明备注
output.fileNameString缓存的文件名
文件名规则见
output.fileUrlString已上传到的第三方存储的 URL。

请求示例​

POST /any-url-path HTTP/1.1
Host: your.app.server
Content-Type: application/json

{
   "timestamp": 1530027865231,
   "type": 4,
   "appKey": "e0x9wycfx7flq",
   "imageId": "SJGOSOIOAIJFOJAOJOE",
   "sessionId": "lSA2G6CUf9A-6nnoNwXCx8",
   "roomId": "111",
   "tag":"",
   "extra":"", //扩展字段
   "output": {
       "fileName": "1.jpg",
       "fileUrl": "http://oss/record/1.jpg",
       "fileState": "10000", // string，向后兼容
       "fileMsg": "ok"
   },
   "code": 200,  //如果output.fileState为 10000，则返回200，其他与output.fileState保持一致
   "errorMessage": "Success"    //与 output.fileMsg 内容一样
}

截图文件命名规则​

截图模式图片格式（jpg）
视频 single 模式Sessionid_RoomId_Userid_streamId_时间戳.文件格式
例：--05oNAPhi9CtbD7FzeVI7_2972_1860099998888_tag98_11128382862.jpg
文件名中字段说明说明
SessionId当前通话的会话 ID。如果使用 RTCLib，可以在创建房间后从房间对象上获取。如果使用 CallLib，可以在建立通话后从当前 call sesion 上获取。
RoomId通话所在的房间 ID。
如您使用 RTCLib，RoomId 为加入房间方法的入参；
如您使用 CallLib，可以通过 getCallId 接口获取 RoomId
UserId通话的用户 ID。
StreamId用户发布视频流的流 ID
时间戳Unix 时间戳，单位为毫秒

注意

以上命名规则仅供参考，不建议您解析具体字段。

响应回调请求​

您的服务在收到 HTTP 回调之后，需要返回 200 OK 表示接收成功。

回调状态码说明：

  • 当第三方存储服务出现故障时，截图的文件会在融云截图服务器上暂存，并会每隔 10s 重试一次。融云暂存时间最长为 24 小时，超出后暂存数据会被清除。
  • 建议在您收到失败回调后检查第三方存储的服务状态。如服务商出现故障，您可以及时配置为新的存储单元，降低您的损失（配置生效时间为 30 分钟）。
最后于 更新