本地截图上传

在实时音视频场景下，声网 SDK 支持按照你设置的频率对频道内的视频流截图，并将图片上传至你指定的第三方云存储。

本文介绍如何实现本地截图上传功能。

信息

本地截图上传为收费服务，计费方式详见本地截图上传计费。

技术原理

调用 API 开启本地截图上传功能后，SDK 会根据你设置的频率对本地用户发送的视频进行截图和上传。截图完成后，声网云端服务器会以 HTTPS 请求的形式，向你的服务器发送回调通知，并将所有截图发送至你指定的第三方云存储。

前提条件

实现声网本地截图上传功能前，请确保已在你的项目中集成 Web SDK 4.14.0 或以上版本，加入频道并发布视频流。详见快速开始。

开通本地截图上传服务

本地截图上传服务可以在声网控制台自助开通和配置。

1. 开通本地截图上传服务

   在声网控制台-项目管理-项目配置-服务配置中开启声网本地截图上传服务。

   

2. 配置第三方云存储

   点击卡片上的配置进入本地截图上传配置页面。

   

   信息

   目前声网本地截图上传服务仅支持使用 Amazon S3 和阿里云 OSS 作为储存截图的第三方云存储，如果你想使用其他第三方云存储供应商，请联系技术支持。

   在本地截图上传配置页面，根据你使用的第三方云存储供应商查看配置方式：

   Amazon S3

   

   你需要填写以下内容：

   • 截图回调地址：截图回调地址，用于接收本地截图上传结果的服务器地址。
   • 存储：第三方云存储供应商。请选择 AWS。
   • 区域：第三方云存储数据中心区域设置，详见 AWS 官方文档。
   • Access Key：String 类型，第三方云存储的 access key。在一般情况下，建议提供只写权限的访问密钥。
   • Secret Key：String 类型，第三方云存储的 secret key。
   • Bucket name：String 类型，第三方云存储的 bucket 名称，bucket 名称需要符合对应第三方云存储服务的命名规则。
   • End point：指定 bucket 的访问域名 (Endpoint)，详见 AWS 官方文档。
   • Filename prefix：（选填）JSON Array 类型，由多个字符串组成的数组，截图在第三方云存储中的存储位置。举个例子，fileNamePrefix = ["directory1","directory2"]，将在截图文件名前加上前缀 "directory1/directory2/"，即 directory1/directory2/xxx.jpg。前缀长度（包括斜杠）不得超过 128 个字符。字符串中不得出现斜杠、下划线、括号等符号字符。以下为支持的字符集范围：
     • 26 个小写英文字母 a-z
     • 26 个大写英文字母 A-Z
     • 10 个数字 0-9

   填写示例

   • 截图回调地址：https://webhook.site/2e75da2d-xxxx-xxxx-xxx-a0ef44a5259d
   • 存储：AWS
   • 区域：cn-north-1
   • accessKey：12345678
   • secretKey：abcd123
   • Bucket name：test-artifacts
   • End point：s3.cn-north-1.amazonaws.com.cn
   • Filename prefix：test

   阿里云 OSS

   

   • 截图回调地址：截图回调地址，用于接收本地截图上传结果的服务器地址。
   • 存储：第三方云存储供应商。请选择阿里云。
   • Access Key：String 类型，第三方云存储的 access key。在一般情况下，建议提供只写权限的访问密钥。
   • Secret Key：String 类型，第三方云存储的 secret key。
   • Bucket name：String 类型。第三方云存储的 bucket 名称，bucket 名称需要符合对应第三方云存储服务的命名规则。
   • End point：指定 bucket 的访问域名 (Endpoint)。详见阿里云官方文档。
   • Filename prefix：（选填）JSON Array 类型，由多个字符串组成的数组，截图在第三方云存储中的存储位置。举个例子，fileNamePrefix = ["directory1","directory2"]，将在截图文件名前加上前缀 "directory1/directory2/"，即 directory1/directory2/xxx.jpg。前缀长度（包括斜杠）不得超过 128 个字符。字符串中不得出现斜杠、下划线、括号等符号字符。以下为支持的字符集范围：
     • 26 个小写英文字母 a-z
     • 26 个大写英文字母 A-Z
     • 10 个数字 0-9

   填写示例

   • 截图回调地址：https://webhook.site/2e75da2d-xxxx-xxxx-xxx-a0ef44a5259d
   • 存储：阿里云
   • accessKey：12345678
   • secretKey：abcd123
   • Bucket name：test-artifacts
   • End point：oss-accelerate.aliyuncs.com
   • Filename prefix：test

实现本地截图上传

在本地用户已加入频道，本地视频轨道已经发布且正在播放时，调用 enableContentInspect 方法开启本地截图上传功能。成功开启本地截图上传功能后，SDK 会按照设定的频率进行截图，并上传截图至声网云端服务器。示例代码如下：

JavaScript

const inspectConfig = {
  // 设置视频截图的间隔为 2000 毫秒（2 秒），最小值为 1000
  interval: 2000,
  // （可选）设置第三方云存储的地址前缀
  ossFilePrefix: "https://your-cloud-storage.com/",
  // （可选）添加附加信息
  extraInfo: "This is some additional information for content inspection.",
  // 设置功能类型为 "supervise"
  inspectType: ["supervise"]
};

// 调用 enableContentInspect 方法并传入 inspectConfig
client.enableContentInspect(inspectConfig)
  .then(() => {
    console.log("Content inspection enabled successfully.");
  })
  .catch((error) => {
    console.error("Failed to enable content inspection:", error);
  });

接收消息通知回调

截图成功并上传至声网云端服务器后，声网服务器会以 HTTPS POST 请求的形式向你的应用服务器发送消息通知回调。

请求格式

数据格式为 JSON，字符编码为 UTF-8。

请求头

字段名	值
Content-Type	application/json;charset=utf-8

请求包体

请求包体为 JSON Object 类型，包含以下字段：

字段	类型	描述
requestId	String	回调通知 ID，标识来自声网业务服务器的一次事件通知。
callbackParam	JSON Object	在回调中自定义传入的字段，目前仅包括 cname 字段，即频道名。
callbackData	String	SDK 本地截图上传模块透传的字符串数据。
checksum	String	由 callbackAddr、code、object 和 requestId 四个参数值计算出的 MD5 值，用于校验此次回调通知是否来自于本地截图上传服务。
object	String	截图文件的名称。该文件的命名规则为：<OSS前缀>/<年月日>/<sid>_<cname>__uid_s_<uid>__uid_e_<type>_utc.jpg。文件名中各字段含义如下： <sid>：截图 ID。该 ID 是一次截图的唯一标识。 <cname>：被截图用户所属的频道名。 <uid>：用户 ID。加入频道时设置的 user ID。 <type>: 文件类型，只支持 video。 <utc>：此次截图的 Unix 时间戳。UTC 时间，由年、月、日、小时、分钟、秒和毫秒组成。例如，utc 等于 20190611073246073，表示该切片文件的开始时间为 UTC 2019 年 6 月 11 日 7 点 32 分 46 秒 73 毫秒。
code	Number	此次截图的状态码。200 表示截图完成。其它详见 HTTP 状态码。
msg	String	此次截图的状态。"Supervise complete" 表示此次截图完成。
channelName	String	此次被截图用户所属的频道名。与 object.cname 一致。
userId	String	此次被截图用户的 user ID。与 object.uid 一致。
timestamp	Int	此次截图 Unix 时间戳（毫秒）。UTC 时间，与 object.utc 一致。

请求示例

JSON

{
    "requestId": "38f8e3cfdcXXXXXXXXX1ceba380d7e1a_1652693284_b5813fe2ae4fa5cdfe5abd8fef82526f",
    "callbackParam": {
        "cname": "httpClient463224"
    },
    "callbackData": "",
    "checksum": "75ee988XXXXXXc2ad4ec2aef58f178fd8",
    "object": "test/20201216/38f8e3cfdc474cd56fc1ceba380d7e1a_httpClient463224__uid_s_91__uid_e_video_20200413081128672.jpg",
    "code": 200,
    "msg": "Supervise complete",
    "channelName": "httpClient463224",
    "userId": "91",
    "timestamp": 20190611073246070
}

响应格式

收到消息通知后，你的应用服务器需要进行响应，响应的包体格式为 JSON。在以下任意一种情况下，声网服务都会认为通知失败：

• 发送消息通知后，5 秒内没有收到你的服务器的响应。
• 响应的 HTTP 状态码不是 200，或响应包体格式不是 JSON。

声网服务会在第一次通知失败后立即重试，再次发送消息通知，一共会尝试三次通知。

参考信息

API 参考

• enableContentInspect

HTTP 状态码

应用服务器响应的 HTTP 状态码参考如下：

状态码	描述
200	请求成功。
201	成功请求并创建了新的资源。
206	整个截图过程中没有用户发流，或部分截图文件没有上传到第三方云存储。
400	请求的语法错误（如参数错误），服务器无法理解。
401	未经授权的（App ID/Customer Certificate 匹配错误）。
404	服务器无法根据请求找到资源（网页）。
500	服务器内部错误，无法完成请求。
504	服务器内部错误。充当网关或代理的服务器未从远端服务器获取请求。