# 列举变更记录 - listChanges #### 功能介绍 列举变更记录 #### 授权信息 当前API调用无需身份策略权限。 #### URI POST /koodrive/ose/v1/syncDir/listChange #### 请求参数 表1请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | Authorization | 是 | String | 该字段存储的是Access Token。调用KooDrive的API使用Token认证，拥有Token就代表拥有某种权限，在调用API的时候将Token加到请求消息头中，从而通过身份认证，获得操作API的权限。Access Token的获取请参考对应的开发手册，格式参考：Bearer+{access_token} | | X-User-Id | 是 | String | 用户id，用于app鉴权 | | X-Date | 是 | String | 日期，用于app鉴权 | | X-Traceid | 否 | String | 消息日志跟踪标识（必须58位） | 表2请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | container | 是 | String | 空间ID | | syncDirId | 是 | String | 同步盘ID | | deviceId | 是 | String | 设备ID | | cursor | 是 | String | 起始游标 | | pageSize | 是 | Integer | 每页显示数量 取值范围：\[1, 100\] 默认为10 | #### 响应参数 **状态码：200** 表3响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | fileChangeList | Array of [FileChangeInfo] objects | 文件变更记录列表 | | nextCursor | String | 分页查询的下一个cursor | | hasMore | Boolean | 是否还有更多变更信息 | 表4FileChangeInfo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | policy | String | 云空间地址：固定值 aggregate 文件变更信息生成策略，目前仅支持：full、latest、aggregate。 full：表示该文件全量变更信息，多次变更会返回多条变更信息； latest：表示文件变更后的最新状态快照，多次变更仅返回最终文件状态信息； aggregate：表示按变更类型聚合后的变更信息，多次变更时按变更类型聚合后返回每一类变更信息； | | changeType | String | 变更类型 | | fileInfo | [File] object | 云空间文件元数据 | | deviceId | String | 发起变更操作的设备ID | | extInfo | [FileChangeExtInfo] object | 扩展信息 | 表5File | 参数 | 参数类型 | 描述 | |:---|:---|:---| | category | String | 类型，drive#file | | id | String | 文件id | | fileName | String | 文件名，最长250个字符 | | fileType | String | 文件类型，外部输入 | | mimeType | String | 内容类型 | | description | String | 文件描述。字符串长度不超过512，不能包括emoji和非法字符 | | favorite | Boolean | 文件是否被收藏 | | recycled | Boolean | 文件是否被放入回收站 | | directlyRecycled | Boolean | 文件是否被直接被放入回收站（随着文件夹删除为false，直接删除为true） | | recyclingUser | [User] object | 删除用户 | | recycledTime | String | 放入回收站的时间 | | parentFolder | Array of strings | 父目录ID列表，注意：当前只取第一个父母Id | | properties | Map\ | 文件公共自定义属性。key-value个数不能超过30个；单个key-value长度不超过124字符 | | appSettings | Map\ | 应用自定义属性。key-value个数不能超过30个；单个key-value长度不超过124字符 | | containers | Array of strings | 空间标识 | | version | Integer | 版本号 | | createdTime | String | 文件创建时间 | | editedTime | String | 文件修改时间 | | editedByMeTime | String | 本人修改文件时间 | | editedByMe | Boolean | 是否是我修改文件 | | sharedWithMeTime | String | 共享给我的时间 | | sharer | [User] object | 分享者 | | owners | Array of [User] objects | 拥有者 | | lastEditor | [User] object | 最后编辑者 | | hasShared | Boolean | 是否共享 | | ownedByMe | Boolean | 是否是我上传 | | capabilities | [Capabilities] object | 能力 | | viewersHasCopyContentPermission | Boolean | 浏览者是否可以复制内容 | | writerHasCopyPermission | Boolean | 复制是否需要writer权限 | | writersHasSharePermission | Boolean | writer能否share | | originalFilename | String | 原始文件名，最长250个字符。不能包括'\<\>\|:"\*?/'和emoji，不能等于'..'、'.'、'' | | fullFileSuffix | String | 完整的文件后缀，取name第一个.后的字符串 | | fileSuffix | String | 文件后缀，fullFileExtension最后一个字符串 | | size | Integer | 文件大小 | | pictureMetadata | [PictureMetadata] object | 图片元数据 | | videoMetadata | [VideoMetadata] object | 视频元数据 | | audioMetadata | [AudioMetadata] object | 音频元数据 | | sha256 | String | 文件的sha256 | | lastHistoryVersionId | String | 最新的历史记录版本ID | | attachments | Array of [Attachment] objects | 附件（用途，附件），只有风控服务appid返回 | | iconDownloadLink | String | 图标链接 | | existThumbnail | Boolean | 是否有缩略图 | | privateKey | String | 特殊文件夹标识，使用规则如下: - 命名不得使用_default - 仅允许在空间的根目录下创建时指定 - 仅允许在创建文件夹时指定 - 同一空间下不得重复 | | signedDownloadLink | String | FileProxy签名的下载链接，在线播放使用 | | downloadLinks | Array of [DownloadLink] objects | FileProxy文件列表下载地址 | | localPath | String | 变更时的父目录顶层id路径（取前10层），变更记录和文件查询接口返回 | | sortName | String | 转换fileName后的排序名称 | | userProperties | [PrivateProperties] object | 用户属性 | 表6User | 参数 | 参数类型 | 描述 | |:---|:---|:---| | category | String | 类型，drive#user | | userId | String | 华为用户ID | | displayName | String | 用户显示名 | | me | Boolean | 是否是我 | | permissionId | String | 权限id | 表7Capabilities | 参数 | 参数类型 | 描述 | |:---|:---|:---| | addChildNodePermission | Boolean | 是否可以增加子目录/文件 | | writerHasChangeCopyPermission | Boolean | change copy是否需要write权限 | | commentPermission | Boolean | 是否可以评论 | | copyPermission | Boolean | 是否可以复制 | | deletePermission | Boolean | 是否可以删除 | | downloadPermission | Boolean | 是否可以下载内容 | | editPermission | Boolean | 是否可以编辑 | | listChildNodePermission | Boolean | 是否可以list子目录/文件 | | editContentPermission | Boolean | 是否可以修改内容 | | readHistoryVersionPermission | Boolean | 是否可以读取副本 | | removeChildNodePermission | Boolean | 是否可以移动子目录 | | renameFilePermission | Boolean | 是否可以重命名 | | shareFilePermission | Boolean | 是否可以共享 | | recyclePermission | Boolean | 是否可以移动到回收站 | | unrecyclePermission | Boolean | 是否可以撤回移动子文件到回收站 | 表8PictureMetadata | 参数 | 参数类型 | 描述 | |:---|:---|:---| | width | Integer | 照片宽度 | | height | Integer | 照片高度 | | rotation | Integer | 照片旋转角度，暂不提供 | | location | [Location] object | 定位信息 | | exifTime | String | 照片的时间，EXIF DateTime | | cameraMaker | String | 照相机制造商 | | cameraModel | String | 照相机型号 | | exposureTime | Float | 曝光长度，单位秒 | | aperture | Float | 光圈，f-number | | flashUsed | Boolean | 是否使用闪光灯 | | focalLength | Float | 焦距，毫米 | | isoSpeed | Integer | ISO速度 | | meteringMode | String | 测距模式 | | sensor | String | 感光类型 | | exposureMode | String | 曝光模式 | | colorSpace | String | 色彩空间 | | whiteBalance | String | 白平衡模式 | | exposureBias | Float | 曝光偏差，APEX值 | | maxApertureValue | Float | 最大光圈值，APEX value | | subjectDistance | Integer | 对象距离，单位米，暂不提供 | | lens | String | 镜头 | 表9Location | 参数 | 参数类型 | 描述 | |:---|:---|:---| | latitude | Double | 维度 | | longitude | Double | 经度 | | altitude | Double | 高度 | 表10VideoMetadata | 参数 | 参数类型 | 描述 | |:---|:---|:---| | width | Integer | 宽度 | | height | Integer | 高度 | | durationTime | Integer | 时长，单位毫秒 | | position | String | 经纬度信息，格式为"x":"111","y":"222","z":"2222" | | rotation | Integer | 旋转角度，取值1-8 | | format | String | 视频编码格式，例如：H264、H265、vp8/vp9、ogg、mpeg-4 avc | | dynamicRange | String | SDR，HDR | | snapshotTime | String | 拍摄时间 | 表11AudioMetadata | 参数 | 参数类型 | 描述 | |:---|:---|:---| | durationTime | Integer | 时长，单位毫秒 | | sampleRate | String | 采样率，例如：16000、48000 | | encoding | String | 音频编码格式，例如：pcm、aac、amr、amrwb | | codeRate | Number | 码率单位kb/s，例如：12.8 | | rateModel | String | 码率模式，例如：CBR | | languageCode | String | 语言国家码，例如：zh、en | 表12Attachment | 参数 | 参数类型 | 描述 | |:---|:---|:---| | usage | String | 用途默认：'content'-实体内容、'thumbnail'-缩略图，业务可以扩展该字段 | | assetId | String | Asset ID | | length | Long | 文件大小 | | versionId | String | Asset版本ID | | mimeType | String | MIME类型 | | hash | String | Asset关联的资源的hash | | sha256 | String | Asset关联的资源的sha256 | | createdTime | String | 数据创建时间 | | modifiedTime | String | 数据最后修改时间 | | attributes | Map\ | 类型属性 | | asset | [Asset] object | 资产 | 表13Asset | 参数 | 参数类型 | 描述 | |:---|:---|:---| | id | String | Asset ID | | versionId | String | Asset版本ID | | version | Long | 版本号 | | mimeType | String | MIME type | | keepPolicy | Integer | 历史版本的保存策略 - 0：自动清理，保留两个版本，第三个版本时淘汰最早的（目的是为了防止并发场景下获取失败） - 1：永久保存 | | state | Integer | 数据的状态 - 0：可用 - 1：不可用 - 2：临时 - 3：留存（不可飞速） - 4：待割接 | | createdTime | String | 数据创建时间 | | modifiedTime | String | 数据最后修改时间 | | lastModifyingUser | String | 最后一次修改的用户UPID | | resource | [Resource] object | 资源 | | cipher | [Cipher] object | 密码器 | | attributes | Map\ | 类型属性（Key部分使用字母开头的字母加数字组合，Value部分禁止使用emoji字符，不限单个属性长度，限制总大小为16K以内），存在字段如下： - pictureMetadata：图片属性数据，参见PictureMetadata定义 - videoMetadata：视频属性数据，参见VideoMetadata定义 - audioMetadata：音频属性数据，参见AudioMetadata定义 - contentDisposition：下载附件未指定response-content-disposition，自动使用该字段填充（resource.type=12生效） | | properties | Map\ | 扩展属性 | 表14Resource | 参数 | 参数类型 | 描述 | |:---|:---|:---| | id | String | 文件资源ID | | hash | String | 文件资源的hash | | length | Long | 文件资源的长度 | | sha256 | String | 文件的sha256（用于完整性校验） | | type | Integer | 资源类型 - 0：密文分片文件 - 3：明文分片文件 - 12：明文单片文件 | | state | Integer | 数据的状态 - 0：可用 - 1：不可用 - 2：临时 - 3：留存（不可飞速） - 4：待割接 | | sliceSize | Long | 分片大小 | | hfek | String | 加密文件的fek的hash，用于type={0} | | iv | String | 加密文件的IV，适用于type={0} | | createdTime | String | 数据创建时间 | | modifiedTime | String | 数据最后修改时间 | | objects | Array of [SliceObject] objects | 分片对象，适用于type={0,3} | | attributes | Map\ | 类型属性 | | properties | Map\ | 扩展属性 | 表15SliceObject | 参数 | 参数类型 | 描述 | |:---|:---|:---| | id | String | 分片ID | | number | Integer | 分片序号，从0开始计，不适用于type={12} | | start | Long | 分片的起始位置，不适用于type={12} | | sha256 | String | 分片的sha256（如果是加密，是指密文的sha256） | | length | Long | 分片的长度（如果是加密，则是密文长度） | | bucket | String | OBS桶信息 | | createdTime | String | 数据创建时间 | | modifiedTime | String | 数据最后修改时间 | | uploadUrl | [EndpointURL] object | 上传url | | downloadUrl | [EndpointURL] object | 下载url | | uploadId | String | 分段上传ID，适用于type={12}且uploadMode=multipart | | attributes | Map\ | 类型属性 | | properties | Map\ | 扩展属性 | | images | Array of [Images] objects | 缩略图 | 表16EndpointURL | 参数 | 参数类型 | 描述 | |:---|:---|:---| | url | String | URL | | method | String | http method | | headers | Map\ | http headers | | forms | Map\ | 表单参数，适用于type={12}且uploadMode=post | | partId | String | 分段参数，适用于type={12}且uploadMode=multipart | 表17Images | 参数 | 参数类型 | 描述 | |:---|:---|:---| | process | String | 文件资源名称 | | downloadUrl | [EndpointURLMetadata] object | 文件上传或下载的URL结构 | 表18EndpointURLMetadata | 参数 | 参数类型 | 描述 | |:---|:---|:---| | url | String | URL | | method | String | http method | 表19Cipher | 参数 | 参数类型 | 描述 | |:---|:---|:---| | algorithm | String | 加密算法 | | hfek | String | 加密文件的fek的hash，用于type={0,4} | | iv | String | 加密文件的IV，适用于type={0,4} | | dataType | Integer | 数据类型 - 11：同步盘 | | keychains | Array of [Keychain] objects | 钥匙串 | 表20Keychain | 参数 | 参数类型 | 描述 | |:---|:---|:---| | id | String | key的UUID | | type | Integer | 密钥类型 - 1：efek - 2：zfek - 3：sfek | | algorithm | String | 加密算法 | | ekey | String | 加密后的key | 表21DownloadLink | 参数 | 参数类型 | 描述 | |:---|:---|:---| | usage | String | 用途默认：'content'-实体内容、'thumbnail'-缩略图，业务可以扩展该字段 | | downloadLink | String | 附件下载地址 | | version | Integer | 附件版本号 | 表22PrivateProperties | 参数 | 参数类型 | 描述 | |:---|:---|:---| | attributes | Map\ | 类型属性（不限单个属性长度，限制总大小为16K以内） | | properties | Map\ | 扩展属性（不限单个属性长度，限制总大小为16K以内） | 表23FileChangeExtInfo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | moveType | Integer | 文件移动类型 1: 同步目录内移动 2: 移出同步目录 3: 移入同步目录 注 : 仅 当changeType=5 移动操作时返回 | | srcParentFileId | String | 文件变更前的父目录 ID 注: 仅当changeType=4、5、6 时，即文件彻底删除、移动、移入回收站操作时返回 | | idPath | String | 变更后的文件 ID 全路径注 : 仅 当 changeType=4、5、6 时，即文件彻底删除、移动、移入回收站操作时返回 | | localOperatedAt | Long | 文件本地操作时间，毫秒时间戳 | #### 请求示例 列举变更记录示例 ``` POST /koodrive/ose/v1/syncDir/listChange { "container" : "K*****", "syncDirId" : "K*****", "deviceId" : "K*****", "cursor" : "0", "pageSize" : "10" } ``` #### 响应示例 **状态码：200** 列举变更记录响应 ``` { "fileChangeList" : [ { "policy" : "full", "changeType" : "add", "fileInfo" : { "id" : "FmZxJyIQz5B1DtzgjM4FCuI94CpzrMZMd", "fileName" : "test.txt", "favorite" : false, "mimeType" : "text/plain", "fileSuffix" : "txt", "recycled" : false, "hidden" : false, "size" : 4, "directlyRecycled" : false, "parentFolder" : [ "FhrBCdI6kLcSzy5hGs7FPGZBUASDhplrE" ], "containers" : [ "IAAE0gxbkQ1RvAncA1649517393090925824" ], "properties" : { "localCreatedAt" : "", "localUpdatedAt" : "" }, "sha256" : "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "attachments" : [ { "assetId" : "1765316142659898496", "versionId" : "1765316142659898497", "attributes" : { "fileName" : "test.txt", "localCreatedAt" : "", "createdBy" : "c937ff95eeb44494a5a967e21d1852ae", "resource" : { "id" : "1762995278538867328", "object" : { "bucket" : "obs-koodrive-test-2", "objectId" : "2c9c760947e3454c8693a1718b5c2081086" } }, "localUpdatedAt" : "" }, "hash" : "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "length" : 4, "mimeType" : "text/plain", "usage" : "content", "sha256" : "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "createdTime" : "2025-09-01T08:08:03.357Z", "modifiedTime" : "2025-09-01T08:08:03.357Z" } ], "owners" : [ { "category" : "drive#user", "me" : true, "permissionId" : "1649517393443190528", "userId" : "YzkzN2ZmOTVlZWI0NDQ5NGE1YTk2N2UyMWQxODUyYWUtMTY0OTUxNzI5MTIwMjg5MzA1Nw" } ], "lastEditor" : { "category" : "drive#user", "me" : true, "permissionId" : "1649517393443190528", "userId" : "YzkzN2ZmOTVlZWI0NDQ5NGE1YTk2N2UyMWQxODUyYWUtMTY0OTUxNzI5MTIwMjg5MzA1Nw" }, "fileType" : "26", "createdTime" : "2025-09-01T08:08:03.092Z", "editedTime" : "2025-09-01T08:08:03.847Z", "userProperties" : { "properties" : { "hidden" : "false" } }, "creatingUser" : "YzkzN2ZmOTVlZWI0NDQ5NGE1YTk2N2UyMWQxODUyYWUtMTY0OTUxNzI5MTIwMjg5MzA1Nw" }, "extInfo" : { "idPath" : "FmZxJyIQz5B1DtzgjM4FCuI94CpzrMZMd" } } ], "hasMore" : false, "code" : 0, "msg" : "成功" } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | 列举变更记录响应 |