名词解释

客户端

客户端是用户或业务应用使用的一端，用来查询、回放、截图或导出目标设备的云录像。

基于 Flutter、React Native、Android、iOS 或 HarmonyOS SDK 开发的应用都属于客户端。客户端从业务服务端取得绑定目标设备的 app_access_token，再访问这台设备的录像。

设备端

设备端是运行在 IoT 音视频设备上的一端，用来把设备采集和编码后的音视频帧上传到云端。

设备端集成 C SDK，并配置自己的 device_id 和 device_secret_key。取得业务服务端签发的 device_access_token 后，即可上传录像。

业务服务端

业务服务端是由你部署和维护的可信服务。它保管 AppId、AccessKeyId 和 AccessKeySecret，完成用户与设备的业务授权判断，并调用 HTTP API。

业务服务端为设备签发 device_access_token，为客户端签发 app_access_token，也可以查询录像文件索引和删除录像。

AppId

AppId 是 Ti 云存应用的唯一标识。

同一个业务应用可以包含设备端、多个客户端技术栈和业务服务端。它们使用同一个 AppId 访问对应的 Ti 云存应用。AppId 不表示某个用户、某台设备或某段录像。

AccessKeyId

AccessKeyId 是应用级凭证标识。

业务服务端调用 HTTP API 时，用它标识签名使用的是哪组应用级凭证。AccessKeyId 本身不是密钥，必须和 AccessKeySecret 配套使用。

AccessKeySecret

AccessKeySecret 是应用级密钥，用于业务服务端生成 TGV1 请求签名。

只保存在可信业务服务端。不要下发到客户端或设备端，也不要写进源码、日志、截图或工单。

device_id

device_id 是设备在 Ti 云存服务中的稳定标识。它是平台生成的随机加密、可自校验字符串，自校验由平台完成，应用层代码不需要解析或重新实现。

平台当前生成的 device_id 格式如下：

• 长度为 12 到 32 个字符。
• 由数字 0-9 和大写字母 A-Z 组成。

如果应用层代码需要校验 device_id，建议使用较宽松的规则：

• 字节长度为 12 到 32，包含上下限。
• 每个字节都是 0x21 到 0x7E 范围内的可见 ASCII 字符，不包含空格或控制字符。
• 不按当前字符集写死校验规则，以便兼容后续格式扩展。

把平台下发的 device_id 当成不透明字符串，原样保存和传递；不要自行生成、解析、删除首尾字符或转换大小写。

设备端上传录像、业务服务端签发 Token、客户端访问录像，以及查询或删除录像时，都用同一个 device_id 表示这台设备。测试设备的取值在开通时随凭证下发，正式设备由项目的设备管理流程分配，见申请开通。

device_secret_key

device_secret_key 是与 device_id 成对使用的设备级密钥。

设备端使用它证明自己持有对应 device_id 的密钥，Ti 云存据此校验设备身份。

平台当前生成的 device_secret_key 格式如下：

• 长度为 32 到 64 个字符。
• 由数字、大小写字母和 + - / _ = 组成。

如果应用层代码需要校验 device_secret_key，建议使用较宽松的规则：

• 字节长度为 32 到 64，包含上下限。
• 每个字节都是 0x21 到 0x7E 范围内的可见 ASCII 字符，不包含空格或控制字符。
• 不按当前字符集写死校验规则。

保存和使用 device_secret_key 时：

• 设备端应将它保存在设备平台提供的安全存储中，例如安全芯片（SE）、TEE 安全存储、加密的 KV 存储或访问受限的 Flash 分区。
• 设备应用只在启动 SDK 等需要鉴权的场景读取它，并原样传给设备端 C SDK；不要自行生成、解析、删除首尾字符或转换大小写。

device_secret_key 不等同于应用级 AccessKeySecret。不要把它写进源码、公共固件包或未加密的配置文件；不要打印到日志；不要通过聊天、邮件、截图或工单发送。

device_access_token

device_access_token 是设备端上传录像使用的短期凭证。

业务服务端通过 HTTP API 为指定设备签发。设备端把它作为不透明字符串传给 C SDK，用于上传。

app_access_token

app_access_token 是客户端访问指定设备录像使用的短期凭证。

业务服务端确认当前用户有权访问目标设备后，为该设备签发。客户端把它作为不透明字符串传给 SDK。

媒体通道（Channel）

媒体通道用于标识设备产生的每一路音视频数据。设备向 Ti 云存写入音视频帧时，需要通过 channel_id 标明数据来自哪一路；Ti 云存会保留该编号，客户端播放、录制或导出云录像时，再通过它选择需要的视频和音频。

channel_id 由开发者自行分配。对于只有一个摄像头和一个麦克风的设备，SDK 建议将视频和音频的 channel_id 都设置为 0，但这只是推荐用法，并非固定值。如果设备提供多个摄像头或多路码流，则需要为不同来源分配不同且稳定的编号。例如，可以将主摄像头的视频和音频设置为 0，将辅助摄像头的视频设置为 1。

一段云录像可以同时包含多个媒体通道。每个通道最多包含一路视频和一路音频，channel_id 的取值范围为 0–255。通道编号所代表的摄像头、码流或麦克风由开发者定义，设备端与客户端必须使用一致的对应关系。否则，设备端虽然能够成功上传录像，客户端却可能选不到对应的音视频数据，导致录像无法正常播放。

channel_id 不等于 TiRTC 实时音视频中的 stream_id。Channel ID 用于云录像，范围是 0..255，音频和视频可以共用编号；Stream ID 用于实时连接，范围是 0..15，同一连接中的音频和视频不能共用编号。两套编号分别配置，不要求数值一致。

上传任务

上传任务是 C SDK 为一段媒体时间范围创建的异步处理过程。

创建请求成功只表示 SDK 接受了任务。设备持续写入音视频帧，任务根据开始和结束边界选择数据、上传并重试，最终结果以该请求的 on_result 回调为准。

录像时间段

录像时间段是一段可以查询和回放的云录像范围。

开始和结束时间都使用 UTC Unix 毫秒，范围采用左闭右开语义，即 [start_time_ms, end_time_ms)。结束时间点本身不属于当前时间段。

录像日期

录像日期是按指定 IANA 时区划分的自然日，使用 YYYY-MM-DD 格式表示。

日期查询会返回指定范围内的每一天。某一天至少存在一个当前可见的录像时点时，hasRecording 为 true。采用夏令时的地区可能存在 23 小时或 25 小时的自然日，因此不能把录像日期固定换算为 24 小时。

录像文件索引

录像文件索引是 HTTP API 返回的录像对象信息。业务服务端可以分页查询这些索引，并按设备和时间范围删除云端录像。

它和客户端 SDK 返回的录像时间段职责不同：前者面向服务端管理，后者面向客户端回放。

request_id

request_id 是服务端响应中的请求标识。

排查 HTTP API 问题时，记录本次请求的接口、发生时间、状态码、业务错误码和 request_id。不要同时记录 Token、Authorization 或签名原文。