# 本地截图上传 (/zh-CN/realtime-media/rtc/build/video/content-inspect) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). <_PlatformTabsGroup> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="android" /> 在实时互动场景下,声网 SDK 支持按照你设置的频率对频道内的视频流截图,并将图片上传至你指定的第三方云存储。本文介绍如何实现本地截图上传功能。 :::info[信息] 本地截图上传为收费服务,计费方式详见[本地截图上传计费](/zh-CN/realtime-media/rtc/reference/billing-strategy#本地截图上传)。 ::: ## 技术原理 [#技术原理] 调用 API 开启本地截图上传功能后,SDK 会根据你设置的频率对本地用户发送的视频进行截图和上传。截图完成后,声网云端服务器会以 HTTPS 请求的形式,向你的服务器发送回调通知,并将所有截图发送至你指定的第三方云存储。 ## 前提条件 [#前提条件] 实现声网本地截图上传功能前,请确保已完成以下步骤: 1. **开通本地截图上传服务** 登录[声网控制台](https://console.shengwang.cn/),在左上角下拉框中选择想要开通本地截图上传服务的项目,然后在左侧菜单中选择**全部产品**-**扩展能力**-**媒体服务**-**本地截图上传**,进入**功能配置**,点击**状态**按钮,启用本地截图上传功能。 ![开启本地截图上传](https://web-cdn.agora.io/docs-portal/img/rtc/content-inspect-open-service.png) 2. **配置第三方云存储** 在**功能配置**的**本地截图上传配置**中选择你使用的第三方云存储供应商,并进行配置: :::info[信息] 目前声网本地截图上传服务仅支持使用 Amazon S3 和阿里云 OSS 作为储存截图的第三方云存储,如果你想使用其他第三方云存储供应商,请[联系技术支持](https://ticket.shengwang.cn)。 ::: Amazon S3 阿里云 OSS ![配置 AWS 存储](https://web-cdn.agora.io/docs-portal/img/rtc/content-inspect-aws.png) 你需要填写以下内容: - **截图回调地址**:截图回调地址,用于接收本地截图上传结果的服务器地址。 - **存储**:第三方云存储供应商。请选择 AWS。 - **区域**:第三方云存储数据中心区域设置,详见 [AWS 官方文档](https://docs.aws.amazon.com/general/latest/gr/s3.html)。 - **Access Key**:String 类型,第三方云存储的 access key。在一般情况下,建议提供只写权限的访问密钥。 - **Secret Key**:String 类型,第三方云存储的 secret key。 - **Bucket name**:String 类型,第三方云存储的 bucket 名称,bucket 名称需要符合对应第三方云存储服务的命名规则。 - **End point**:指定 bucket 的访问域名 (Endpoint),详见 [AWS 官方文档](https://docs.aws.amazon.com/general/latest/gr/s3.html)。 - **Filename prefix**:(选填)String 类型,截图在第三方云存储中的存储位置。举个例子,`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` ![配置阿里云存储](https://web-cdn.agora.io/docs-portal/img/rtc/content-inspect-aliyun.png) - **截图回调地址**:截图回调地址,用于接收本地截图上传结果的服务器地址。 - **存储**:第三方云存储供应商。请选择阿里云。 - **Access Key**:String 类型,第三方云存储的 access key。在一般情况下,建议提供只写权限的访问密钥。 - **Secret Key**:String 类型,第三方云存储的 secret key。 - **Bucket name**:String 类型。第三方云存储的 bucket 名称,bucket 名称需要符合对应第三方云存储服务的命名规则。 - **End point**:指定 bucket 的访问域名 (Endpoint)。详见[阿里云官方文档](https://help.aliyun.com/zh/oss/user-guide/regions-and-endpoints?spm=a2c4g.11186623.0.0.7ac5667aLnjEtX)。 - **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` 3. **集成 SDK** 已在你的项目中集成实时互动 SDK(包含本地截图上传动态库),加入频道并发布视频流。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start#集成-sdk)。 ## 实现本地截图上传 [#实现本地截图上传] 调用 `enableContentInspect` 方法开启本地截图上传功能。成功开启本地截图上传功能后,SDK 会按照设定的频率进行截图,并上传截图至声网云端服务器。示例代码如下: ```java ContentInspectConfig config = new ContentInspectConfig(); config.extraInfo = "YourExtraInfo"; config.moduleCount = 1; // 功能模块的类型为本地截图上传 config.modules[0].type = ContentInspectConfig.CONTENT_INSPECT_TYPE_SUPERVISE; // 本地截图上传的频率为 2 秒一次 config.modules[0].interval = 2; mRtcEngine.enableContentInspect(true, config); ``` ## HTTP 通知回调 [#http-通知回调] 截图成功并上传至声网云端服务器后,声网服务会以 HTTPS POST 请求的形式向你的应用服务器发送消息通知回调。数据格式为 JSON,字符编码为 UTF-8。 收到消息通知后,你的应用服务器需要进行响应,响应的包体格式为 JSON。在以下任意一种情况下,声网服务都会认为通知失败: - 发送消息通知后,5 秒内没有收到你的服务器的响应。 - 响应的 HTTP 状态码不是 `200`,或响应包体格式不是 JSON。 声网服务会在第一次通知失败后立即重试,再次发送消息通知,一共会尝试三次通知。 ### 请求 Header [#请求-header] | 字段名 | 值 | | :------------- | :------------------------------- | | `Content-Type` | `application/json;charset=utf-8` | ### 请求 Body [#请求-body] 请求 Body 为 JSON Object 类型,包含以下字段: | 字段 | 类型 | 描述 | | --- | --- | --- | | `requestId` | String | 回调通知 ID,标识来自声网业务服务器的一次事件通知。 | | `callbackParam` | JSON Object | 在回调中自定义传入的字段,目前仅包括 `cname` 字段,即频道名。 | | `callbackData` | String | SDK 本地截图上传模块透传的字符串数据。 | | `checksum` | String | 由 `callbackAddr`、`code`、`object` 和 `requestId` 四个参数值计算出的 MD5 值,用于校验此次回调通知是否来自于本地截图上传服务。 | | `object` | String | [content-inspect-ios-android-windows-macos-rn-electron-markdown-1-5-2 details](#table-slot-content-inspect-ios-android-windows-macos-rn-electron-markdown-1-5-2) | | `code` | Number | 此次截图的状态码。`200` 表示截图完成。 | | `msg` | String | 此次截图的状态。`"Supervise complete"` 表示此次截图完成。 | | `channelName` | String | 此次被截图用户所属的频道名。与 `object.cname` 一致。 | | `userId` | String | 此次被截图用户的 user ID。与 `object.uid` 一致。 | | `timestamp` | Int | 此次截图 Unix 时间戳(毫秒)。UTC 时间,与 `object.utc` 一致。 | **content-inspect-ios-android-windows-macos-rn-electron-markdown-1-5-2 details** 截图文件的名称。该文件的命名规则为:`/<年月日>/___uid_s___uid_e__utc.jpg`。文件名中各字段含义如下: - ``:截图 ID。该 ID 是一次截图的唯一标识。 - ``:被截图用户所属的频道名。 - ``:用户 ID。加入频道时设置的 user ID。 - ``: 文件类型,只支持 `video`。 - ``:此次截图的 Unix 时间戳。UTC 时间,由年、月、日、小时、分钟、秒和毫秒组成。例如,`utc` 等于 `20190611073246073`,表示该切片文件的开始时间为 UTC 2019 年 6 月 11 日 7 点 32 分 46 秒 73 毫秒。 ### 请求示例 [#请求示例] ```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 } ``` ## 参考信息 [#参考信息] ### API 参考 [#api-参考] [`enableContentInspect`](/zh-CN/api-reference/rtc/android/video/video-prenpro/snapshot#api_irtcengine_enablecontentinspect) ### 本地截图上传动态库 [#本地截图上传动态库] 本地截图上传动态库名称及集成后 App 增加的体积详见[减小 App 体积](/zh-CN/realtime-media/rtc/build/optimize-and-operate/reduce-app-size)。 ### HTTP 状态码 [#http-状态码] 应用服务器响应的 HTTP 状态码参考如下: | 状态码 | 描述 | | :----- | :----------------------------------------------------------- | | `200` | 请求成功。 | | `201` | 成功请求并创建了新的资源。 | | `206` | 整个截图过程中没有用户发流,或部分截图文件没有上传到第三方云存储。 | | `400` | 请求的语法错误(如参数错误),服务器无法理解。 | | `401` | 未经授权的(App ID/Customer Certificate 匹配错误)。 | | `404` | 服务器无法根据请求找到资源(网页)。 | | `500` | 服务器内部错误,无法完成请求。 | | `504` | 服务器内部错误。充当网关或代理的服务器未从远端服务器获取请求。 | <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="ios" /> 在实时互动场景下,声网 SDK 支持按照你设置的频率对频道内的视频流截图,并将图片上传至你指定的第三方云存储。 本文介绍如何实现本地截图上传功能。 :::info[信息] 本地截图上传为收费服务,计费方式详见[本地截图上传计费](/zh-CN/realtime-media/rtc/reference/billing-strategy#本地截图上传)。 ::: ## 技术原理 [#技术原理-1] 调用 API 开启本地截图上传功能后,SDK 会根据你设置的频率对本地用户发送的视频进行截图和上传。截图完成后,声网云端服务器会以 HTTPS 请求的形式,向你的服务器发送回调通知,并将所有截图发送至你指定的第三方云存储。 ## 前提条件 [#前提条件-1] 实现声网本地截图上传功能前,请确保已完成以下步骤: 1. **开通本地截图上传服务** 登录[声网控制台](https://console.shengwang.cn/),在左上角下拉框中选择想要开通本地截图上传服务的项目,然后在左侧菜单中选择**全部产品**-**扩展能力**-**媒体服务**-**本地截图上传**,进入**功能配置**,点击**状态**按钮,启用本地截图上传功能。 ![开启本地截图上传](https://web-cdn.agora.io/docs-portal/img/rtc/content-inspect-open-service.png) 2. **配置第三方云存储** 在**功能配置**的**本地截图上传配置**中选择你使用的第三方云存储供应商,并进行配置: :::info[信息] 目前声网本地截图上传服务仅支持使用 Amazon S3 和阿里云 OSS 作为储存截图的第三方云存储,如果你想使用其他第三方云存储供应商,请[联系技术支持](https://ticket.shengwang.cn)。 ::: Amazon S3 阿里云 OSS ![配置 AWS 存储](https://web-cdn.agora.io/docs-portal/img/rtc/content-inspect-aws.png) 你需要填写以下内容: - **截图回调地址**:截图回调地址,用于接收本地截图上传结果的服务器地址。 - **存储**:第三方云存储供应商。请选择 AWS。 - **区域**:第三方云存储数据中心区域设置,详见 [AWS 官方文档](https://docs.aws.amazon.com/general/latest/gr/s3.html)。 - **Access Key**:String 类型,第三方云存储的 access key。在一般情况下,建议提供只写权限的访问密钥。 - **Secret Key**:String 类型,第三方云存储的 secret key。 - **Bucket name**:String 类型,第三方云存储的 bucket 名称,bucket 名称需要符合对应第三方云存储服务的命名规则。 - **End point**:指定 bucket 的访问域名 (Endpoint),详见 [AWS 官方文档](https://docs.aws.amazon.com/general/latest/gr/s3.html)。 - **Filename prefix**:(选填)String 类型,截图在第三方云存储中的存储位置。举个例子,`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` ![配置阿里云存储](https://web-cdn.agora.io/docs-portal/img/rtc/content-inspect-aliyun.png) - **截图回调地址**:截图回调地址,用于接收本地截图上传结果的服务器地址。 - **存储**:第三方云存储供应商。请选择阿里云。 - **Access Key**:String 类型,第三方云存储的 access key。在一般情况下,建议提供只写权限的访问密钥。 - **Secret Key**:String 类型,第三方云存储的 secret key。 - **Bucket name**:String 类型。第三方云存储的 bucket 名称,bucket 名称需要符合对应第三方云存储服务的命名规则。 - **End point**:指定 bucket 的访问域名 (Endpoint)。详见[阿里云官方文档](https://help.aliyun.com/zh/oss/user-guide/regions-and-endpoints?spm=a2c4g.11186623.0.0.7ac5667aLnjEtX)。 - **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` 3. **集成 SDK** 已在你的项目中集成实时互动 SDK(包含本地截图上传动态库),加入频道并发布视频流。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start#集成-sdk)。 ## 实现本地截图上传 [#实现本地截图上传-1] 调用 `enableContentInspect` 方法开启本地截图上传功能。成功开启本地截图上传功能后,SDK 会按照设定的频率进行截图,并上传截图至声网云端服务器。示例代码如下: ## HTTP 通知回调 [#http-通知回调-1] 截图成功并上传至声网云端服务器后,声网服务会以 HTTPS POST 请求的形式向你的应用服务器发送消息通知回调。数据格式为 JSON,字符编码为 UTF-8。 收到消息通知后,你的应用服务器需要进行响应,响应的包体格式为 JSON。在以下任意一种情况下,声网服务都会认为通知失败: - 发送消息通知后,5 秒内没有收到你的服务器的响应。 - 响应的 HTTP 状态码不是 `200`,或响应包体格式不是 JSON。 声网服务会在第一次通知失败后立即重试,再次发送消息通知,一共会尝试三次通知。 ### 请求 Header [#请求-header-1] | 字段名 | 值 | | :------------- | :------------------------------- | | `Content-Type` | `application/json;charset=utf-8` | ### 请求 Body [#请求-body-1] 请求 Body 为 JSON Object 类型,包含以下字段: | 字段 | 类型 | 描述 | | --- | --- | --- | | `requestId` | String | 回调通知 ID,标识来自声网业务服务器的一次事件通知。 | | `callbackParam` | JSON Object | 在回调中自定义传入的字段,目前仅包括 `cname` 字段,即频道名。 | | `callbackData` | String | SDK 本地截图上传模块透传的字符串数据。 | | `checksum` | String | 由 `callbackAddr`、`code`、`object` 和 `requestId` 四个参数值计算出的 MD5 值,用于校验此次回调通知是否来自于本地截图上传服务。 | | `object` | String | [content-inspect-ios-android-windows-macos-rn-electron-markdown-1-5-2 details](#table-slot-content-inspect-ios-android-windows-macos-rn-electron-markdown-1-5-2-1) | | `code` | Number | 此次截图的状态码。`200` 表示截图完成。 | | `msg` | String | 此次截图的状态。`"Supervise complete"` 表示此次截图完成。 | | `channelName` | String | 此次被截图用户所属的频道名。与 `object.cname` 一致。 | | `userId` | String | 此次被截图用户的 user ID。与 `object.uid` 一致。 | | `timestamp` | Int | 此次截图 Unix 时间戳(毫秒)。UTC 时间,与 `object.utc` 一致。 | **content-inspect-ios-android-windows-macos-rn-electron-markdown-1-5-2 details** 截图文件的名称。该文件的命名规则为:`/<年月日>/___uid_s___uid_e__utc.jpg`。文件名中各字段含义如下: - ``:截图 ID。该 ID 是一次截图的唯一标识。 - ``:被截图用户所属的频道名。 - ``:用户 ID。加入频道时设置的 user ID。 - ``: 文件类型,只支持 `video`。 - ``:此次截图的 Unix 时间戳。UTC 时间,由年、月、日、小时、分钟、秒和毫秒组成。例如,`utc` 等于 `20190611073246073`,表示该切片文件的开始时间为 UTC 2019 年 6 月 11 日 7 点 32 分 46 秒 73 毫秒。 ### 请求示例 [#请求示例-1] ```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 } ``` ## 参考信息 [#参考信息-1] ### API 参考 [#api-参考-1] [`enableContentInspect`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/snapshot#api_irtcengine_enablecontentinspect) ### 本地截图上传动态库 [#本地截图上传动态库-1] 本地截图上传动态库名称及集成后 App 增加的体积详见[减小 App 体积](/zh-CN/realtime-media/rtc/build/optimize-and-operate/reduce-app-size)。 ### HTTP 状态码 [#http-状态码-1] 应用服务器响应的 HTTP 状态码参考如下: | 状态码 | 描述 | | :----- | :----------------------------------------------------------- | | `200` | 请求成功。 | | `201` | 成功请求并创建了新的资源。 | | `206` | 整个截图过程中没有用户发流,或部分截图文件没有上传到第三方云存储。 | | `400` | 请求的语法错误(如参数错误),服务器无法理解。 | | `401` | 未经授权的(App ID/Customer Certificate 匹配错误)。 | | `404` | 服务器无法根据请求找到资源(网页)。 | | `500` | 服务器内部错误,无法完成请求。 | | `504` | 服务器内部错误。充当网关或代理的服务器未从远端服务器获取请求。 | <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="macos" /> 在实时互动场景下,声网 SDK 支持按照你设置的频率对频道内的视频流截图,并将图片上传至你指定的第三方云存储。 本文介绍如何实现本地截图上传功能。 :::info[信息] 本地截图上传为收费服务,计费方式详见[本地截图上传计费](/zh-CN/realtime-media/rtc/reference/billing-strategy#本地截图上传)。 ::: ## 技术原理 [#技术原理-2] 调用 API 开启本地截图上传功能后,SDK 会根据你设置的频率对本地用户发送的视频进行截图和上传。截图完成后,声网云端服务器会以 HTTPS 请求的形式,向你的服务器发送回调通知,并将所有截图发送至你指定的第三方云存储。 ## 前提条件 [#前提条件-2] 实现声网本地截图上传功能前,请确保已完成以下步骤: 1. **开通本地截图上传服务** 登录[声网控制台](https://console.shengwang.cn/),在左上角下拉框中选择想要开通本地截图上传服务的项目,然后在左侧菜单中选择**全部产品**-**扩展能力**-**媒体服务**-**本地截图上传**,进入**功能配置**,点击**状态**按钮,启用本地截图上传功能。 ![开启本地截图上传](https://web-cdn.agora.io/docs-portal/img/rtc/content-inspect-open-service.png) 2. **配置第三方云存储** 在**功能配置**的**本地截图上传配置**中选择你使用的第三方云存储供应商,并进行配置: :::info[信息] 目前声网本地截图上传服务仅支持使用 Amazon S3 和阿里云 OSS 作为储存截图的第三方云存储,如果你想使用其他第三方云存储供应商,请[联系技术支持](https://ticket.shengwang.cn)。 ::: Amazon S3 阿里云 OSS ![配置 AWS 存储](https://web-cdn.agora.io/docs-portal/img/rtc/content-inspect-aws.png) 你需要填写以下内容: - **截图回调地址**:截图回调地址,用于接收本地截图上传结果的服务器地址。 - **存储**:第三方云存储供应商。请选择 AWS。 - **区域**:第三方云存储数据中心区域设置,详见 [AWS 官方文档](https://docs.aws.amazon.com/general/latest/gr/s3.html)。 - **Access Key**:String 类型,第三方云存储的 access key。在一般情况下,建议提供只写权限的访问密钥。 - **Secret Key**:String 类型,第三方云存储的 secret key。 - **Bucket name**:String 类型,第三方云存储的 bucket 名称,bucket 名称需要符合对应第三方云存储服务的命名规则。 - **End point**:指定 bucket 的访问域名 (Endpoint),详见 [AWS 官方文档](https://docs.aws.amazon.com/general/latest/gr/s3.html)。 - **Filename prefix**:(选填)String 类型,截图在第三方云存储中的存储位置。举个例子,`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` ![配置阿里云存储](https://web-cdn.agora.io/docs-portal/img/rtc/content-inspect-aliyun.png) - **截图回调地址**:截图回调地址,用于接收本地截图上传结果的服务器地址。 - **存储**:第三方云存储供应商。请选择阿里云。 - **Access Key**:String 类型,第三方云存储的 access key。在一般情况下,建议提供只写权限的访问密钥。 - **Secret Key**:String 类型,第三方云存储的 secret key。 - **Bucket name**:String 类型。第三方云存储的 bucket 名称,bucket 名称需要符合对应第三方云存储服务的命名规则。 - **End point**:指定 bucket 的访问域名 (Endpoint)。详见[阿里云官方文档](https://help.aliyun.com/zh/oss/user-guide/regions-and-endpoints?spm=a2c4g.11186623.0.0.7ac5667aLnjEtX)。 - **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` 3. **集成 SDK** 已在你的项目中集成实时互动 SDK(包含本地截图上传动态库),加入频道并发布视频流。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start#集成-sdk)。 ## 实现本地截图上传 [#实现本地截图上传-2] 调用 `enableContentInspect` 方法开启本地截图上传功能。成功开启本地截图上传功能后,SDK 会按照设定的频率进行截图,并上传截图至声网云端服务器。示例代码如下: ```swift let inspectExtraConfig = AgoraContentInspectConfig() inspectExtraConfig.extraInfo = "YourExtraInfo" var modules = [AgoraContentInspectModule]() let module1 = AgoraContentInspectModule() // 功能模块的类型为本地截图上传 module1.type = .supervise // 本地截图上传的频率为 2 秒一次 module1.interval = 2 modules.append(module1) inspectExtraConfig.modules = modules agoraKit.enableContentInspect(true, config:inspectExtraConfig) ``` ## HTTP 通知回调 [#http-通知回调-2] 截图成功并上传至声网云端服务器后,声网服务会以 HTTPS POST 请求的形式向你的应用服务器发送消息通知回调。数据格式为 JSON,字符编码为 UTF-8。 收到消息通知后,你的应用服务器需要进行响应,响应的包体格式为 JSON。在以下任意一种情况下,声网服务都会认为通知失败: - 发送消息通知后,5 秒内没有收到你的服务器的响应。 - 响应的 HTTP 状态码不是 `200`,或响应包体格式不是 JSON。 声网服务会在第一次通知失败后立即重试,再次发送消息通知,一共会尝试三次通知。 ### 请求 Header [#请求-header-2] | 字段名 | 值 | | :------------- | :------------------------------- | | `Content-Type` | `application/json;charset=utf-8` | ### 请求 Body [#请求-body-2] 请求 Body 为 JSON Object 类型,包含以下字段: | 字段 | 类型 | 描述 | | --- | --- | --- | | `requestId` | String | 回调通知 ID,标识来自声网业务服务器的一次事件通知。 | | `callbackParam` | JSON Object | 在回调中自定义传入的字段,目前仅包括 `cname` 字段,即频道名。 | | `callbackData` | String | SDK 本地截图上传模块透传的字符串数据。 | | `checksum` | String | 由 `callbackAddr`、`code`、`object` 和 `requestId` 四个参数值计算出的 MD5 值,用于校验此次回调通知是否来自于本地截图上传服务。 | | `object` | String | [content-inspect-ios-android-windows-macos-rn-electron-markdown-1-5-2 details](#table-slot-content-inspect-ios-android-windows-macos-rn-electron-markdown-1-5-2-2) | | `code` | Number | 此次截图的状态码。`200` 表示截图完成。 | | `msg` | String | 此次截图的状态。`"Supervise complete"` 表示此次截图完成。 | | `channelName` | String | 此次被截图用户所属的频道名。与 `object.cname` 一致。 | | `userId` | String | 此次被截图用户的 user ID。与 `object.uid` 一致。 | | `timestamp` | Int | 此次截图 Unix 时间戳(毫秒)。UTC 时间,与 `object.utc` 一致。 | **content-inspect-ios-android-windows-macos-rn-electron-markdown-1-5-2 details** 截图文件的名称。该文件的命名规则为:`/<年月日>/___uid_s___uid_e__utc.jpg`。文件名中各字段含义如下: - ``:截图 ID。该 ID 是一次截图的唯一标识。 - ``:被截图用户所属的频道名。 - ``:用户 ID。加入频道时设置的 user ID。 - ``: 文件类型,只支持 `video`。 - ``:此次截图的 Unix 时间戳。UTC 时间,由年、月、日、小时、分钟、秒和毫秒组成。例如,`utc` 等于 `20190611073246073`,表示该切片文件的开始时间为 UTC 2019 年 6 月 11 日 7 点 32 分 46 秒 73 毫秒。 ### 请求示例 [#请求示例-2] ```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 } ``` ## 参考信息 [#参考信息-2] ### API 参考 [#api-参考-2] [`enableContentInspect`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/snapshot#api_irtcengine_enablecontentinspect) ### 本地截图上传动态库 [#本地截图上传动态库-2] 本地截图上传动态库名称及集成后 App 增加的体积详见[减小 App 体积](/zh-CN/realtime-media/rtc/build/optimize-and-operate/reduce-app-size)。 ### HTTP 状态码 [#http-状态码-2] 应用服务器响应的 HTTP 状态码参考如下: | 状态码 | 描述 | | :----- | :----------------------------------------------------------- | | `200` | 请求成功。 | | `201` | 成功请求并创建了新的资源。 | | `206` | 整个截图过程中没有用户发流,或部分截图文件没有上传到第三方云存储。 | | `400` | 请求的语法错误(如参数错误),服务器无法理解。 | | `401` | 未经授权的(App ID/Customer Certificate 匹配错误)。 | | `404` | 服务器无法根据请求找到资源(网页)。 | | `500` | 服务器内部错误,无法完成请求。 | | `504` | 服务器内部错误。充当网关或代理的服务器未从远端服务器获取请求。 | <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="web" /> 在实时音视频场景下,声网 SDK 支持按照你设置的频率对频道内的视频流截图,并将图片上传至你指定的第三方云存储。 本文介绍如何实现本地截图上传功能。 :::info[信息] 本地截图上传为收费服务,计费方式详见[本地截图上传计费](/zh-CN/realtime-media/rtc/reference/billing-strategy#本地截图上传)。 ::: ## 技术原理 [#技术原理-3] 调用 API 开启本地截图上传功能后,SDK 会根据你设置的频率对本地用户发送的视频进行截图和上传。截图完成后,声网云端服务器会以 HTTPS 请求的形式,向你的服务器发送回调通知,并将所有截图发送至你指定的第三方云存储。 ![视频截图原理](https://web-cdn.agora.io/docs-files/1670232424041) ## 前提条件 [#前提条件-3] 实现声网本地截图上传功能前,请确保已在你的项目中集成 Web SDK **4.14.0 或以上版本**,加入频道并发布视频流。详见[快速开始](/zh-CN/realtime-media/rtc/get-started/quick-start/web)。 ## 开通本地截图上传服务 [#开通本地截图上传服务] 本地截图上传服务可以在声网控制台自助开通和配置。 1. **开通本地截图上传服务** 在[声网控制台](https://console.shengwang.cn/)-**项目管理**-**项目配置**-**服务配置**中开启声网本地截图上传服务。 ![开启本地截图上传](https://web-cdn.agora.io/docs-portal/img/rtc/content-inspect-open-service.png) 2. **配置第三方云存储** 点击卡片上的**配置**进入本地截图上传配置页面。 ![本地截图上传配置页面](https://web-cdn.agora.io/docs-files/1695893256796) :::info[信息] 目前声网本地截图上传服务仅支持使用 Amazon S3 和阿里云 OSS 作为储存截图的第三方云存储,如果你想使用其他第三方云存储供应商,请[联系技术支持](https://ticket.shengwang.cn)。 ::: 在本地截图上传配置页面,根据你使用的第三方云存储供应商查看配置方式: Amazon S3 阿里云 OSS ![配置 AWS 存储](https://web-cdn.agora.io/docs-portal/img/rtc/content-inspect-aws.png) 你需要填写以下内容: - **截图回调地址**:截图回调地址,用于接收本地截图上传结果的服务器地址。 - **存储**:第三方云存储供应商。请选择 AWS。 - **区域**:第三方云存储数据中心区域设置,详见 [AWS 官方文档](https://docs.aws.amazon.com/general/latest/gr/s3.html)。 - **Access Key**:String 类型,第三方云存储的 access key。在一般情况下,建议提供只写权限的访问密钥。 - **Secret Key**:String 类型,第三方云存储的 secret key。 - **Bucket name**:String 类型,第三方云存储的 bucket 名称,bucket 名称需要符合对应第三方云存储服务的命名规则。 - **End point**:指定 bucket 的访问域名 (Endpoint),详见 [AWS 官方文档](https://docs.aws.amazon.com/general/latest/gr/s3.html)。 - **Filename prefix**:(选填)String 类型,截图在第三方云存储中的存储位置。举个例子,`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` ![配置阿里云存储](https://web-cdn.agora.io/docs-portal/img/rtc/content-inspect-aliyun.png) - **截图回调地址**:截图回调地址,用于接收本地截图上传结果的服务器地址。 - **存储**:第三方云存储供应商。请选择阿里云。 - **Access Key**:String 类型,第三方云存储的 access key。在一般情况下,建议提供只写权限的访问密钥。 - **Secret Key**:String 类型,第三方云存储的 secret key。 - **Bucket name**:String 类型。第三方云存储的 bucket 名称,bucket 名称需要符合对应第三方云存储服务的命名规则。 - **End point**:指定 bucket 的访问域名 (Endpoint)。详见[阿里云官方文档](https://help.aliyun.com/zh/oss/user-guide/regions-and-endpoints?spm=a2c4g.11186623.0.0.7ac5667aLnjEtX)。 - **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` ## 实现本地截图上传 [#实现本地截图上传-3] 在本地用户已加入频道,本地视频轨道已经发布且正在播放时,调用 `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。 #### 请求 Header [#请求-header-3] | 字段名 | 值 | | :------------- | :------------------------------- | | `Content-Type` | `application/json;charset=utf-8` | #### 请求 Body [#请求-body-3] 请求 Body 为 JSON Object 类型,包含以下字段: | 字段 | 类型 | 描述 | | --- | --- | --- | | `requestId` | String | 回调通知 ID,标识来自声网业务服务器的一次事件通知。 | | `callbackParam` | JSON Object | 在回调中自定义传入的字段,目前仅包括 `cname` 字段,即频道名。 | | `callbackData` | String | SDK 本地截图上传模块透传的字符串数据。 | | `checksum` | String | 由 `callbackAddr`、`code`、`object` 和 `requestId` 四个参数值计算出的 MD5 值,用于校验此次回调通知是否来自于本地截图上传服务。 | | `object` | String | [content-inspect-javascript-markdown-1-5-2 details](#table-slot-content-inspect-javascript-markdown-1-5-2) | | `code` | Number | 此次截图的状态码。`200` 表示截图完成。其它详见 [HTTP 状态码](#http-状态码-3)。 | | `msg` | String | 此次截图的状态。`"Supervise complete"` 表示此次截图完成。 | | `channelName` | String | 此次被截图用户所属的频道名。与 `object.cname` 一致。 | | `userId` | String | 此次被截图用户的 user ID。与 `object.uid` 一致。 | | `timestamp` | Int | 此次截图 Unix 时间戳(毫秒)。UTC 时间,与 `object.utc` 一致。 | **content-inspect-javascript-markdown-1-5-2 details** 截图文件的名称。该文件的命名规则为:`/<年月日>/___uid_s___uid_e__utc.jpg`。文件名中各字段含义如下: - ``:截图 ID。该 ID 是一次截图的唯一标识。 - ``:被截图用户所属的频道名。 - ``:用户 ID。加入频道时设置的 user ID。 - ``: 文件类型,只支持 `video`。 - ``:此次截图的 Unix 时间戳。UTC 时间,由年、月、日、小时、分钟、秒和毫秒组成。例如,`utc` 等于 `20190611073246073`,表示该切片文件的开始时间为 UTC 2019 年 6 月 11 日 7 点 32 分 46 秒 73 毫秒。 #### 请求示例 [#请求示例-3] ```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。 声网服务会在第一次通知失败后立即重试,再次发送消息通知,一共会尝试三次通知。 ## 参考信息 [#参考信息-3] ### API 参考 [#api-参考-3] - [`enableContentInspect`](/zh-CN/api-reference/rtc/web/interfaces/iagorartcclient#enablecontentinspect) ### HTTP 状态码 [#http-状态码-3] 应用服务器响应的 HTTP 状态码参考如下: | 状态码 | 描述 | | :----- | :----------------------------------------------------------- | | `200` | 请求成功。 | | `201` | 成功请求并创建了新的资源。 | | `206` | 整个截图过程中没有用户发流,或部分截图文件没有上传到第三方云存储。 | | `400` | 请求的语法错误(如参数错误),服务器无法理解。 | | `401` | 未经授权的(App ID/Customer Certificate 匹配错误)。 | | `404` | 服务器无法根据请求找到资源(网页)。 | | `500` | 服务器内部错误,无法完成请求。 | | `504` | 服务器内部错误。充当网关或代理的服务器未从远端服务器获取请求。 | <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="windows" /> 在实时互动场景下,声网 SDK 支持按照你设置的频率对频道内的视频流截图,并将图片上传至你指定的第三方云存储。 本文介绍如何实现本地截图上传功能。 :::info[信息] 本地截图上传为收费服务,计费方式详见[本地截图上传计费](/zh-CN/realtime-media/rtc/reference/billing-strategy#本地截图上传)。 ::: ## 技术原理 [#技术原理-4] 调用 API 开启本地截图上传功能后,SDK 会根据你设置的频率对本地用户发送的视频进行截图和上传。截图完成后,声网云端服务器会以 HTTPS 请求的形式,向你的服务器发送回调通知,并将所有截图发送至你指定的第三方云存储。 ## 前提条件 [#前提条件-4] 实现声网本地截图上传功能前,请确保已完成以下步骤: 1. **开通本地截图上传服务** 登录[声网控制台](https://console.shengwang.cn/),在左上角下拉框中选择想要开通本地截图上传服务的项目,然后在左侧菜单中选择**全部产品**-**扩展能力**-**媒体服务**-**本地截图上传**,进入**功能配置**,点击**状态**按钮,启用本地截图上传功能。 ![开启本地截图上传](https://web-cdn.agora.io/docs-portal/img/rtc/content-inspect-open-service.png) 2. **配置第三方云存储** 在**功能配置**的**本地截图上传配置**中选择你使用的第三方云存储供应商,并进行配置: :::info[信息] 目前声网本地截图上传服务仅支持使用 Amazon S3 和阿里云 OSS 作为储存截图的第三方云存储,如果你想使用其他第三方云存储供应商,请[联系技术支持](https://ticket.shengwang.cn)。 ::: Amazon S3 阿里云 OSS ![配置 AWS 存储](https://web-cdn.agora.io/docs-portal/img/rtc/content-inspect-aws.png) 你需要填写以下内容: - **截图回调地址**:截图回调地址,用于接收本地截图上传结果的服务器地址。 - **存储**:第三方云存储供应商。请选择 AWS。 - **区域**:第三方云存储数据中心区域设置,详见 [AWS 官方文档](https://docs.aws.amazon.com/general/latest/gr/s3.html)。 - **Access Key**:String 类型,第三方云存储的 access key。在一般情况下,建议提供只写权限的访问密钥。 - **Secret Key**:String 类型,第三方云存储的 secret key。 - **Bucket name**:String 类型,第三方云存储的 bucket 名称,bucket 名称需要符合对应第三方云存储服务的命名规则。 - **End point**:指定 bucket 的访问域名 (Endpoint),详见 [AWS 官方文档](https://docs.aws.amazon.com/general/latest/gr/s3.html)。 - **Filename prefix**:(选填)String 类型,截图在第三方云存储中的存储位置。举个例子,`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` ![配置阿里云存储](https://web-cdn.agora.io/docs-portal/img/rtc/content-inspect-aliyun.png) - **截图回调地址**:截图回调地址,用于接收本地截图上传结果的服务器地址。 - **存储**:第三方云存储供应商。请选择阿里云。 - **Access Key**:String 类型,第三方云存储的 access key。在一般情况下,建议提供只写权限的访问密钥。 - **Secret Key**:String 类型,第三方云存储的 secret key。 - **Bucket name**:String 类型。第三方云存储的 bucket 名称,bucket 名称需要符合对应第三方云存储服务的命名规则。 - **End point**:指定 bucket 的访问域名 (Endpoint)。详见[阿里云官方文档](https://help.aliyun.com/zh/oss/user-guide/regions-and-endpoints?spm=a2c4g.11186623.0.0.7ac5667aLnjEtX)。 - **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` 3. **集成 SDK** 已在你的项目中集成实时互动 SDK(包含本地截图上传动态库),加入频道并发布视频流。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start#集成-sdk)。 ## 实现本地截图上传 [#实现本地截图上传-4] 调用 `enableContentInspect` 方法开启本地截图上传功能。成功开启本地截图上传功能后,SDK 会按照设定的频率进行截图,并上传截图至声网云端服务器。示例代码如下: ```cpp void CMainFrame::OnBtnEnableContentInspect() { if (CAgoraObject::GetEngine() == NULL) { return; } ContentInspectConfig config; ContentInspectModule module1; // 功能模块的类型为本地截图上传 module1.type = kContentInspectSupervise; // 本地截图上传的频率为 2 秒一次 module1.interval = 2; config.moduleCount = 1; config.modules[0] = module1; CAgoraObject::GetEngine()->enableContentInspect(true, config); } ``` ## HTTP 通知回调 [#http-通知回调-3] 截图成功并上传至声网云端服务器后,声网服务会以 HTTPS POST 请求的形式向你的应用服务器发送消息通知回调。数据格式为 JSON,字符编码为 UTF-8。 收到消息通知后,你的应用服务器需要进行响应,响应的包体格式为 JSON。在以下任意一种情况下,声网服务都会认为通知失败: - 发送消息通知后,5 秒内没有收到你的服务器的响应。 - 响应的 HTTP 状态码不是 `200`,或响应包体格式不是 JSON。 声网服务会在第一次通知失败后立即重试,再次发送消息通知,一共会尝试三次通知。 ### 请求 Header [#请求-header-4] | 字段名 | 值 | | :------------- | :------------------------------- | | `Content-Type` | `application/json;charset=utf-8` | ### 请求 Body [#请求-body-4] 请求 Body 为 JSON Object 类型,包含以下字段: | 字段 | 类型 | 描述 | | --- | --- | --- | | `requestId` | String | 回调通知 ID,标识来自声网业务服务器的一次事件通知。 | | `callbackParam` | JSON Object | 在回调中自定义传入的字段,目前仅包括 `cname` 字段,即频道名。 | | `callbackData` | String | SDK 本地截图上传模块透传的字符串数据。 | | `checksum` | String | 由 `callbackAddr`、`code`、`object` 和 `requestId` 四个参数值计算出的 MD5 值,用于校验此次回调通知是否来自于本地截图上传服务。 | | `object` | String | [content-inspect-ios-android-windows-macos-rn-electron-markdown-1-5-2 details](#table-slot-content-inspect-ios-android-windows-macos-rn-electron-markdown-1-5-2-3) | | `code` | Number | 此次截图的状态码。`200` 表示截图完成。 | | `msg` | String | 此次截图的状态。`"Supervise complete"` 表示此次截图完成。 | | `channelName` | String | 此次被截图用户所属的频道名。与 `object.cname` 一致。 | | `userId` | String | 此次被截图用户的 user ID。与 `object.uid` 一致。 | | `timestamp` | Int | 此次截图 Unix 时间戳(毫秒)。UTC 时间,与 `object.utc` 一致。 | **content-inspect-ios-android-windows-macos-rn-electron-markdown-1-5-2 details** 截图文件的名称。该文件的命名规则为:`/<年月日>/___uid_s___uid_e__utc.jpg`。文件名中各字段含义如下: - ``:截图 ID。该 ID 是一次截图的唯一标识。 - ``:被截图用户所属的频道名。 - ``:用户 ID。加入频道时设置的 user ID。 - ``: 文件类型,只支持 `video`。 - ``:此次截图的 Unix 时间戳。UTC 时间,由年、月、日、小时、分钟、秒和毫秒组成。例如,`utc` 等于 `20190611073246073`,表示该切片文件的开始时间为 UTC 2019 年 6 月 11 日 7 点 32 分 46 秒 73 毫秒。 ### 请求示例 [#请求示例-4] ```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 } ``` ## 参考信息 [#参考信息-4] ### API 参考 [#api-参考-4] [`enableContentInspect`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/snapshot#api_irtcengine_enablecontentinspect) ### 本地截图上传动态库 [#本地截图上传动态库-3] 本地截图上传动态库名称及集成后 App 增加的体积详见[减小 App 体积](/zh-CN/realtime-media/rtc/build/optimize-and-operate/reduce-app-size)。 ### HTTP 状态码 [#http-状态码-4] 应用服务器响应的 HTTP 状态码参考如下: | 状态码 | 描述 | | :----- | :----------------------------------------------------------- | | `200` | 请求成功。 | | `201` | 成功请求并创建了新的资源。 | | `206` | 整个截图过程中没有用户发流,或部分截图文件没有上传到第三方云存储。 | | `400` | 请求的语法错误(如参数错误),服务器无法理解。 | | `401` | 未经授权的(App ID/Customer Certificate 匹配错误)。 | | `404` | 服务器无法根据请求找到资源(网页)。 | | `500` | 服务器内部错误,无法完成请求。 | | `504` | 服务器内部错误。充当网关或代理的服务器未从远端服务器获取请求。 | <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="electron" /> 在实时互动场景下,声网 SDK 支持按照你设置的频率对频道内的视频流截图,并将图片上传至你指定的第三方云存储。 本文介绍如何实现本地截图上传功能。 :::info[信息] 本地截图上传为收费服务,计费方式详见[本地截图上传计费](/zh-CN/realtime-media/rtc/reference/billing-strategy#本地截图上传)。 ::: ## 技术原理 [#技术原理-5] 调用 API 开启本地截图上传功能后,SDK 会根据你设置的频率对本地用户发送的视频进行截图和上传。截图完成后,声网云端服务器会以 HTTPS 请求的形式,向你的服务器发送回调通知,并将所有截图发送至你指定的第三方云存储。 ## 前提条件 [#前提条件-5] 实现声网本地截图上传功能前,请确保已完成以下步骤: 1. **开通本地截图上传服务** 登录[声网控制台](https://console.shengwang.cn/),在左上角下拉框中选择想要开通本地截图上传服务的项目,然后在左侧菜单中选择**全部产品**-**扩展能力**-**媒体服务**-**本地截图上传**,进入**功能配置**,点击**状态**按钮,启用本地截图上传功能。 ![开启本地截图上传](https://web-cdn.agora.io/docs-portal/img/rtc/content-inspect-open-service.png) 2. **配置第三方云存储** 在**功能配置**的**本地截图上传配置**中选择你使用的第三方云存储供应商,并进行配置: :::info[信息] 目前声网本地截图上传服务仅支持使用 Amazon S3 和阿里云 OSS 作为储存截图的第三方云存储,如果你想使用其他第三方云存储供应商,请[联系技术支持](https://ticket.shengwang.cn)。 ::: Amazon S3 阿里云 OSS ![配置 AWS 存储](https://web-cdn.agora.io/docs-portal/img/rtc/content-inspect-aws.png) 你需要填写以下内容: - **截图回调地址**:截图回调地址,用于接收本地截图上传结果的服务器地址。 - **存储**:第三方云存储供应商。请选择 AWS。 - **区域**:第三方云存储数据中心区域设置,详见 [AWS 官方文档](https://docs.aws.amazon.com/general/latest/gr/s3.html)。 - **Access Key**:String 类型,第三方云存储的 access key。在一般情况下,建议提供只写权限的访问密钥。 - **Secret Key**:String 类型,第三方云存储的 secret key。 - **Bucket name**:String 类型,第三方云存储的 bucket 名称,bucket 名称需要符合对应第三方云存储服务的命名规则。 - **End point**:指定 bucket 的访问域名 (Endpoint),详见 [AWS 官方文档](https://docs.aws.amazon.com/general/latest/gr/s3.html)。 - **Filename prefix**:(选填)String 类型,截图在第三方云存储中的存储位置。举个例子,`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` ![配置阿里云存储](https://web-cdn.agora.io/docs-portal/img/rtc/content-inspect-aliyun.png) - **截图回调地址**:截图回调地址,用于接收本地截图上传结果的服务器地址。 - **存储**:第三方云存储供应商。请选择阿里云。 - **Access Key**:String 类型,第三方云存储的 access key。在一般情况下,建议提供只写权限的访问密钥。 - **Secret Key**:String 类型,第三方云存储的 secret key。 - **Bucket name**:String 类型。第三方云存储的 bucket 名称,bucket 名称需要符合对应第三方云存储服务的命名规则。 - **End point**:指定 bucket 的访问域名 (Endpoint)。详见[阿里云官方文档](https://help.aliyun.com/zh/oss/user-guide/regions-and-endpoints?spm=a2c4g.11186623.0.0.7ac5667aLnjEtX)。 - **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` 3. **集成 SDK** 已在你的项目中集成实时互动 SDK(包含本地截图上传动态库),加入频道并发布视频流。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start#集成-sdk)。 ## 实现本地截图上传 [#实现本地截图上传-5] 调用 `enableContentInspect` 方法开启本地截图上传功能。成功开启本地截图上传功能后,SDK 会按照设定的频率进行截图,并上传截图至声网云端服务器。示例代码如下: ```typescript // 定义功能模块 ContentInspectModule const modules = [{ // 使用声网自研截图上传功能 type: ContentInspectType.ContentInspectSupervision, // 本地截图上传的频率为 2 秒一次 interval: 2, }]; rtcEngine.enableContentInspect( // 开启本地截图上传功能 true, // 本地截图上传配置 { modules: modules moduleCount: modules.length, } ); ``` ## HTTP 通知回调 [#http-通知回调-4] 截图成功并上传至声网云端服务器后,声网服务会以 HTTPS POST 请求的形式向你的应用服务器发送消息通知回调。数据格式为 JSON,字符编码为 UTF-8。 收到消息通知后,你的应用服务器需要进行响应,响应的包体格式为 JSON。在以下任意一种情况下,声网服务都会认为通知失败: - 发送消息通知后,5 秒内没有收到你的服务器的响应。 - 响应的 HTTP 状态码不是 `200`,或响应包体格式不是 JSON。 声网服务会在第一次通知失败后立即重试,再次发送消息通知,一共会尝试三次通知。 ### 请求 Header [#请求-header-5] | 字段名 | 值 | | :------------- | :------------------------------- | | `Content-Type` | `application/json;charset=utf-8` | ### 请求 Body [#请求-body-5] 请求 Body 为 JSON Object 类型,包含以下字段: | 字段 | 类型 | 描述 | | --- | --- | --- | | `requestId` | String | 回调通知 ID,标识来自声网业务服务器的一次事件通知。 | | `callbackParam` | JSON Object | 在回调中自定义传入的字段,目前仅包括 `cname` 字段,即频道名。 | | `callbackData` | String | SDK 本地截图上传模块透传的字符串数据。 | | `checksum` | String | 由 `callbackAddr`、`code`、`object` 和 `requestId` 四个参数值计算出的 MD5 值,用于校验此次回调通知是否来自于本地截图上传服务。 | | `object` | String | [content-inspect-ios-android-windows-macos-rn-electron-markdown-1-5-2 details](#table-slot-content-inspect-ios-android-windows-macos-rn-electron-markdown-1-5-2-4) | | `code` | Number | 此次截图的状态码。`200` 表示截图完成。 | | `msg` | String | 此次截图的状态。`"Supervise complete"` 表示此次截图完成。 | | `channelName` | String | 此次被截图用户所属的频道名。与 `object.cname` 一致。 | | `userId` | String | 此次被截图用户的 user ID。与 `object.uid` 一致。 | | `timestamp` | Int | 此次截图 Unix 时间戳(毫秒)。UTC 时间,与 `object.utc` 一致。 | **content-inspect-ios-android-windows-macos-rn-electron-markdown-1-5-2 details** 截图文件的名称。该文件的命名规则为:`/<年月日>/___uid_s___uid_e__utc.jpg`。文件名中各字段含义如下: - ``:截图 ID。该 ID 是一次截图的唯一标识。 - ``:被截图用户所属的频道名。 - ``:用户 ID。加入频道时设置的 user ID。 - ``: 文件类型,只支持 `video`。 - ``:此次截图的 Unix 时间戳。UTC 时间,由年、月、日、小时、分钟、秒和毫秒组成。例如,`utc` 等于 `20190611073246073`,表示该切片文件的开始时间为 UTC 2019 年 6 月 11 日 7 点 32 分 46 秒 73 毫秒。 ### 请求示例 [#请求示例-5] ```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 } ``` ## 参考信息 [#参考信息-5] ### 示例项目 [#示例项目] 声网提供了开源的本地截图上传示例项目供你参考,你可以前往下载或查看其中的源代码。 ChannelMediaRelay} href="https://gitee.com/agoraio-community/Electron-SDK/blob/main/example/src/renderer/examples/advanced/ChannelMediaRelay/ChannelMediaRelay.tsx" /> ChannelMediaRelay} href="https://github.com/AgoraIO-Extensions/Electron-SDK/blob/main/example/src/renderer/examples/advanced/ChannelMediaRelay/ChannelMediaRelay.tsx" /> ### API 参考 [#api-参考-5] [`enableContentInspect`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/snapshot#api_irtcengine_enablecontentinspect) ### HTTP 状态码 [#http-状态码-5] 应用服务器响应的 HTTP 状态码参考如下: | 状态码 | 描述 | | :----- | :----------------------------------------------------------- | | `200` | 请求成功。 | | `201` | 成功请求并创建了新的资源。 | | `206` | 整个截图过程中没有用户发流,或部分截图文件没有上传到第三方云存储。 | | `400` | 请求的语法错误(如参数错误),服务器无法理解。 | | `401` | 未经授权的(App ID/Customer Certificate 匹配错误)。 | | `404` | 服务器无法根据请求找到资源(网页)。 | | `500` | 服务器内部错误,无法完成请求。 | | `504` | 服务器内部错误。充当网关或代理的服务器未从远端服务器获取请求。 | <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="unity" /> 在实时互动场景下,声网 SDK 支持按照你设置的频率对频道内的视频流截图,并将图片上传至你指定的第三方云存储。 本文介绍如何实现本地截图上传功能。 :::info[信息] 本地截图上传为收费服务,计费方式详见[本地截图上传计费](/zh-CN/realtime-media/rtc/reference/billing-strategy#本地截图上传)。 ::: ## 技术原理 [#技术原理-6] 调用 API 开启本地截图上传功能后,SDK 会根据你设置的频率对本地用户发送的视频进行截图和上传。截图完成后,声网云端服务器会以 HTTPS 请求的形式,向你的服务器发送回调通知,并将所有截图发送至你指定的第三方云存储。 ## 前提条件 [#前提条件-6] 实现声网本地截图上传功能前,请确保已完成以下步骤: 1. **开通本地截图上传服务** 登录[声网控制台](https://console.shengwang.cn/),在左上角下拉框中选择想要开通本地截图上传服务的项目,然后在左侧菜单中选择**全部产品**-**扩展能力**-**媒体服务**-**本地截图上传**,进入**功能配置**,点击**状态**按钮,启用本地截图上传功能。 ![开启本地截图上传](https://web-cdn.agora.io/docs-portal/img/rtc/content-inspect-open-service.png) 2. **配置第三方云存储** 在**功能配置**的**本地截图上传配置**中选择你使用的第三方云存储供应商,并进行配置: :::info[信息] 目前声网本地截图上传服务仅支持使用 Amazon S3 和阿里云 OSS 作为储存截图的第三方云存储,如果你想使用其他第三方云存储供应商,请[联系技术支持](https://ticket.shengwang.cn)。 ::: Amazon S3 阿里云 OSS ![配置 AWS 存储](https://web-cdn.agora.io/docs-portal/img/rtc/content-inspect-aws.png) 你需要填写以下内容: - **截图回调地址**:截图回调地址,用于接收本地截图上传结果的服务器地址。 - **存储**:第三方云存储供应商。请选择 AWS。 - **区域**:第三方云存储数据中心区域设置,详见 [AWS 官方文档](https://docs.aws.amazon.com/general/latest/gr/s3.html)。 - **Access Key**:String 类型,第三方云存储的 access key。在一般情况下,建议提供只写权限的访问密钥。 - **Secret Key**:String 类型,第三方云存储的 secret key。 - **Bucket name**:String 类型,第三方云存储的 bucket 名称,bucket 名称需要符合对应第三方云存储服务的命名规则。 - **End point**:指定 bucket 的访问域名 (Endpoint),详见 [AWS 官方文档](https://docs.aws.amazon.com/general/latest/gr/s3.html)。 - **Filename prefix**:(选填)String 类型,截图在第三方云存储中的存储位置。举个例子,`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` ![配置阿里云存储](https://web-cdn.agora.io/docs-portal/img/rtc/content-inspect-aliyun.png) - **截图回调地址**:截图回调地址,用于接收本地截图上传结果的服务器地址。 - **存储**:第三方云存储供应商。请选择阿里云。 - **Access Key**:String 类型,第三方云存储的 access key。在一般情况下,建议提供只写权限的访问密钥。 - **Secret Key**:String 类型,第三方云存储的 secret key。 - **Bucket name**:String 类型。第三方云存储的 bucket 名称,bucket 名称需要符合对应第三方云存储服务的命名规则。 - **End point**:指定 bucket 的访问域名 (Endpoint)。详见[阿里云官方文档](https://help.aliyun.com/zh/oss/user-guide/regions-and-endpoints?spm=a2c4g.11186623.0.0.7ac5667aLnjEtX)。 - **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` 3. **集成 SDK** 已在你的项目中集成实时互动 SDK(包含本地截图上传动态库),加入频道并发布视频流。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start#集成-sdk)。 ## 实现本地截图上传 [#实现本地截图上传-6] 调用 `EnableContentInspect` 方法开启本地截图上传功能。成功开启本地截图上传功能后,SDK 会按照设定的频率进行截图,并上传截图至声网云端服务器。示例代码如下: ```csharp private void OnStartButtonClick() { var config = new ContentInspectConfig(); config.modules = new ContentInspectModule[1]; // 功能模块的类型为本地截图上传 config.modules[0] = new ContentInspectModule { type = CONTENT_INSPECT_TYPE.CONTENT_INSPECT_SUPERVISION, // 本地截图上传的频率为 1 秒一次 interval = 1 }; config.moduleCount = var nRet = RtcEngine.EnableContentInspect(true, config); this.Log.UpdateLog("StartContentInspect: " + nRet); } ``` ## HTTP 通知回调 [#http-通知回调-5] 截图成功并上传至声网云端服务器后,声网服务会以 HTTPS POST 请求的形式向你的应用服务器发送消息通知回调。数据格式为 JSON,字符编码为 UTF-8。 收到消息通知后,你的应用服务器需要进行响应,响应的包体格式为 JSON。在以下任意一种情况下,声网服务都会认为通知失败: - 发送消息通知后,5 秒内没有收到你的服务器的响应。 - 响应的 HTTP 状态码不是 `200`,或响应包体格式不是 JSON。 声网服务会在第一次通知失败后立即重试,再次发送消息通知,一共会尝试三次通知。 ### 请求 Header [#请求-header-6] | 字段名 | 值 | | :------------- | :------------------------------- | | `Content-Type` | `application/json;charset=utf-8` | ### 请求 Body [#请求-body-6] 请求 Body 为 JSON Object 类型,包含以下字段: | 字段 | 类型 | 描述 | | --- | --- | --- | | `requestId` | String | 回调通知 ID,标识来自声网业务服务器的一次事件通知。 | | `callbackParam` | JSON Object | 在回调中自定义传入的字段,目前仅包括 `cname` 字段,即频道名。 | | `callbackData` | String | SDK 本地截图上传模块透传的字符串数据。 | | `checksum` | String | 由 `callbackAddr`、`code`、`object` 和 `requestId` 四个参数值计算出的 MD5 值,用于校验此次回调通知是否来自于本地截图上传服务。 | | `object` | String | [content-inspect-unity-markdown-1-5-2 details](#table-slot-content-inspect-unity-markdown-1-5-2) | | `code` | Number | 此次截图的状态码。`200` 表示截图完成。 | | `msg` | String | 此次截图的状态。`"Supervise complete"` 表示此次截图完成。 | | `channelName` | String | 此次被截图用户所属的频道名。与 `object.cname` 一致。 | | `userId` | String | 此次被截图用户的 user ID。与 `object.uid` 一致。 | | `timestamp` | Int | 此次截图 Unix 时间戳(毫秒)。UTC 时间,与 `object.utc` 一致。 | **content-inspect-unity-markdown-1-5-2 details** 截图文件的名称。该文件的命名规则为:`/<年月日>/___uid_s___uid_e__utc.jpg`。文件名中各字段含义如下: - ``:截图 ID。该 ID 是一次截图的唯一标识。 - ``:被截图用户所属的频道名。 - ``:用户 ID。加入频道时设置的 user ID。 - ``: 文件类型,只支持 `video`。 - ``:此次截图的 Unix 时间戳。UTC 时间,由年、月、日、小时、分钟、秒和毫秒组成。例如,`utc` 等于 `20190611073246073`,表示该切片文件的开始时间为 UTC 2019 年 6 月 11 日 7 点 32 分 46 秒 73 毫秒。 ### 请求示例 [#请求示例-6] ```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 } ``` ## 参考信息 [#参考信息-6] ### API 参考 [#api-参考-6] [`EnableContentInspect`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/snapshot#api_irtcengine_enablecontentinspect) ### 本地截图上传动态库 [#本地截图上传动态库-4] 本地截图上传动态库名称及集成后 App 增加的体积详见[减小 App 体积](/zh-CN/realtime-media/rtc/build/optimize-and-operate/reduce-app-size)。 ### HTTP 状态码 [#http-状态码-6] 应用服务器响应的 HTTP 状态码参考如下: | 状态码 | 描述 | | :----- | :----------------------------------------------------------- | | `200` | 请求成功。 | | `201` | 成功请求并创建了新的资源。 | | `206` | 整个截图过程中没有用户发流,或部分截图文件没有上传到第三方云存储。 | | `400` | 请求的语法错误(如参数错误),服务器无法理解。 | | `401` | 未经授权的(App ID/Customer Certificate 匹配错误)。 | | `404` | 服务器无法根据请求找到资源(网页)。 | | `500` | 服务器内部错误,无法完成请求。 | | `504` | 服务器内部错误。充当网关或代理的服务器未从远端服务器获取请求。 | <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="react-native" /> 在实时互动场景下,声网 SDK 支持按照你设置的频率对频道内的视频流截图,并将图片上传至你指定的第三方云存储。 本文介绍如何实现本地截图上传功能。 :::info[信息] 本地截图上传为收费服务,计费方式详见[本地截图上传计费](/zh-CN/realtime-media/rtc/reference/billing-strategy#本地截图上传)。 ::: ## 技术原理 [#技术原理-7] 调用 API 开启本地截图上传功能后,SDK 会根据你设置的频率对本地用户发送的视频进行截图和上传。截图完成后,声网云端服务器会以 HTTPS 请求的形式,向你的服务器发送回调通知,并将所有截图发送至你指定的第三方云存储。 ## 前提条件 [#前提条件-7] 实现声网本地截图上传功能前,请确保已完成以下步骤: 1. **开通本地截图上传服务** 登录[声网控制台](https://console.shengwang.cn/),在左上角下拉框中选择想要开通本地截图上传服务的项目,然后在左侧菜单中选择**全部产品**-**扩展能力**-**媒体服务**-**本地截图上传**,进入**功能配置**,点击**状态**按钮,启用本地截图上传功能。 ![开启本地截图上传](https://web-cdn.agora.io/docs-portal/img/rtc/content-inspect-open-service.png) 2. **配置第三方云存储** 在**功能配置**的**本地截图上传配置**中选择你使用的第三方云存储供应商,并进行配置: :::info[信息] 目前声网本地截图上传服务仅支持使用 Amazon S3 和阿里云 OSS 作为储存截图的第三方云存储,如果你想使用其他第三方云存储供应商,请[联系技术支持](https://ticket.shengwang.cn)。 ::: Amazon S3 阿里云 OSS ![配置 AWS 存储](https://web-cdn.agora.io/docs-portal/img/rtc/content-inspect-aws.png) 你需要填写以下内容: - **截图回调地址**:截图回调地址,用于接收本地截图上传结果的服务器地址。 - **存储**:第三方云存储供应商。请选择 AWS。 - **区域**:第三方云存储数据中心区域设置,详见 [AWS 官方文档](https://docs.aws.amazon.com/general/latest/gr/s3.html)。 - **Access Key**:String 类型,第三方云存储的 access key。在一般情况下,建议提供只写权限的访问密钥。 - **Secret Key**:String 类型,第三方云存储的 secret key。 - **Bucket name**:String 类型,第三方云存储的 bucket 名称,bucket 名称需要符合对应第三方云存储服务的命名规则。 - **End point**:指定 bucket 的访问域名 (Endpoint),详见 [AWS 官方文档](https://docs.aws.amazon.com/general/latest/gr/s3.html)。 - **Filename prefix**:(选填)String 类型,截图在第三方云存储中的存储位置。举个例子,`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` ![配置阿里云存储](https://web-cdn.agora.io/docs-portal/img/rtc/content-inspect-aliyun.png) - **截图回调地址**:截图回调地址,用于接收本地截图上传结果的服务器地址。 - **存储**:第三方云存储供应商。请选择阿里云。 - **Access Key**:String 类型,第三方云存储的 access key。在一般情况下,建议提供只写权限的访问密钥。 - **Secret Key**:String 类型,第三方云存储的 secret key。 - **Bucket name**:String 类型。第三方云存储的 bucket 名称,bucket 名称需要符合对应第三方云存储服务的命名规则。 - **End point**:指定 bucket 的访问域名 (Endpoint)。详见[阿里云官方文档](https://help.aliyun.com/zh/oss/user-guide/regions-and-endpoints?spm=a2c4g.11186623.0.0.7ac5667aLnjEtX)。 - **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` 3. **集成 SDK** 已在你的项目中集成实时互动 SDK(包含本地截图上传动态库),加入频道并发布视频流。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start#集成-sdk)。 ## 实现本地截图上传 [#实现本地截图上传-7] 调用 `enableContentInspect` 方法开启本地截图上传功能。成功开启本地截图上传功能后,SDK 会按照设定的频率进行截图,并上传截图至声网云端服务器。示例代码如下: ```typescript // 定义功能模块 ContentInspectModule const modules = [{ // 使用声网自研截图上传功能 type: ContentInspectType.ContentInspectSupervision, // 本地截图上传的频率为 2 秒一次 interval: 2, }]; rtcEngine.enableContentInspect( // 开启本地截图上传功能 true, // 本地截图上传配置 { modules: modules moduleCount: modules.length, } ); ``` ## HTTP 通知回调 [#http-通知回调-6] 截图成功并上传至声网云端服务器后,声网服务会以 HTTPS POST 请求的形式向你的应用服务器发送消息通知回调。数据格式为 JSON,字符编码为 UTF-8。 收到消息通知后,你的应用服务器需要进行响应,响应的包体格式为 JSON。在以下任意一种情况下,声网服务都会认为通知失败: - 发送消息通知后,5 秒内没有收到你的服务器的响应。 - 响应的 HTTP 状态码不是 `200`,或响应包体格式不是 JSON。 声网服务会在第一次通知失败后立即重试,再次发送消息通知,一共会尝试三次通知。 ### 请求 Header [#请求-header-7] | 字段名 | 值 | | :------------- | :------------------------------- | | `Content-Type` | `application/json;charset=utf-8` | ### 请求 Body [#请求-body-7] 请求 Body 为 JSON Object 类型,包含以下字段: | 字段 | 类型 | 描述 | | --- | --- | --- | | `requestId` | String | 回调通知 ID,标识来自声网业务服务器的一次事件通知。 | | `callbackParam` | JSON Object | 在回调中自定义传入的字段,目前仅包括 `cname` 字段,即频道名。 | | `callbackData` | String | SDK 本地截图上传模块透传的字符串数据。 | | `checksum` | String | 由 `callbackAddr`、`code`、`object` 和 `requestId` 四个参数值计算出的 MD5 值,用于校验此次回调通知是否来自于本地截图上传服务。 | | `object` | String | [content-inspect-ios-android-windows-macos-rn-electron-markdown-1-5-2 details](#table-slot-content-inspect-ios-android-windows-macos-rn-electron-markdown-1-5-2-5) | | `code` | Number | 此次截图的状态码。`200` 表示截图完成。 | | `msg` | String | 此次截图的状态。`"Supervise complete"` 表示此次截图完成。 | | `channelName` | String | 此次被截图用户所属的频道名。与 `object.cname` 一致。 | | `userId` | String | 此次被截图用户的 user ID。与 `object.uid` 一致。 | | `timestamp` | Int | 此次截图 Unix 时间戳(毫秒)。UTC 时间,与 `object.utc` 一致。 | **content-inspect-ios-android-windows-macos-rn-electron-markdown-1-5-2 details** 截图文件的名称。该文件的命名规则为:`/<年月日>/___uid_s___uid_e__utc.jpg`。文件名中各字段含义如下: - ``:截图 ID。该 ID 是一次截图的唯一标识。 - ``:被截图用户所属的频道名。 - ``:用户 ID。加入频道时设置的 user ID。 - ``: 文件类型,只支持 `video`。 - ``:此次截图的 Unix 时间戳。UTC 时间,由年、月、日、小时、分钟、秒和毫秒组成。例如,`utc` 等于 `20190611073246073`,表示该切片文件的开始时间为 UTC 2019 年 6 月 11 日 7 点 32 分 46 秒 73 毫秒。 ### 请求示例 [#请求示例-7] ```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 } ``` ## 参考信息 [#参考信息-7] ### 示例项目 [#示例项目-1] 声网提供了开源的本地截图上传示例项目供你参考,你可以前往下载或查看其中的源代码。 ChannelMediaRelay} href="https://gitee.com/agoraio-community/react-native-agora/tree/main/example/src/examples/advanced/ChannelMediaRelay/ChannelMediaRelay.tsx" /> ChannelMediaRelay} href="https://github.com/AgoraIO-Extensions/react-native-agora/blob/main/examples/legacy/src/examples/advanced/ChannelMediaRelay/ChannelMediaRelay.tsx" /> ### API 参考 [#api-参考-7] [`enableContentInspect`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/snapshot#api_irtcengine_enablecontentinspect) ### 本地截图上传动态库 [#本地截图上传动态库-5] 本地截图上传动态库名称及集成后 App 增加的体积详见[减小 App 体积](/zh-CN/realtime-media/rtc/build/optimize-and-operate/reduce-app-size)。 ### HTTP 状态码 [#http-状态码-7] 应用服务器响应的 HTTP 状态码参考如下: | 状态码 | 描述 | | :----- | :----------------------------------------------------------- | | `200` | 请求成功。 | | `201` | 成功请求并创建了新的资源。 | | `206` | 整个截图过程中没有用户发流,或部分截图文件没有上传到第三方云存储。 | | `400` | 请求的语法错误(如参数错误),服务器无法理解。 | | `401` | 未经授权的(App ID/Customer Certificate 匹配错误)。 | | `404` | 服务器无法根据请求找到资源(网页)。 | | `500` | 服务器内部错误,无法完成请求。 | | `504` | 服务器内部错误。充当网关或代理的服务器未从远端服务器获取请求。 | <_PlatformProcessedMarker close="true" />