千问办公企业旗舰版开发者文档:读取文件与下载地址。
认证方式见APP开发者文档 → 认证接入。
按当前用户的个人文件路径或 file_id 查询。向对象存储地址请求时仅使用返回的 URL 和 headers,不附带业务认证凭据。
接口面向当前认证用户的文件,文件归属由 Barn 校验。不接受管理 API Key、Agent Token 或其他用途 OAuth 凭据替代。调用方不得自行设置 X-Gw 身份头。
按 ID 定位后,文件或父目录重命名不改变该 ID。删除后同路径重建会得到新 ID。
200 返回文件信息;presigned_url 可能省略。
使用 file_id 时返回下载地址,不应用 mode/size 预览选项;预览与编辑继续按 path 调用。
示例使用认证接入定义的 appRequest。
401 表示认证失败;403 表示文件权限或审核策略拒绝;404 表示当前用户下找不到文件,不能通过更换用户 ID 绕过归属校验。400/422 时检查 path、file_id 及读取参数;500 为服务端故障,503 为服务暂不可用,504 为请求超时。读取失败不能据此认定文件已经删除。
业务错误通常返回
- 模块:文件服务
- 接口:GET
/api/openapi/app/v1/drive/files - operationId:
appGetDriveFile
接口说明
按当前用户的个人文件路径或 file_id 查询。向对象存储地址请求时仅使用返回的 URL 和 headers,不附带业务认证凭据。
接口面向当前认证用户的文件,文件归属由 Barn 校验。不接受管理 API Key、Agent Token 或其他用途 OAuth 凭据替代。调用方不得自行设置 X-Gw 身份头。
按 ID 定位后,文件或父目录重命名不改变该 ID。删除后同路径重建会得到新 ID。
请求参数
| 参数/字段 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| path | query | string | 二选一 | 当前用户绝对逻辑路径,使用 query 编码 |
| file_id | query | string (uuid) | 二选一 | 单个非零 UUID,与 path 不能同时传;其他用户 ID 返回 404 |
| mode | query | string | 否 | preview、download、edit;默认 download |
| size | query | string | 否 | sm 缩略图 |
响应
200 返回文件信息;presigned_url 可能省略。
| 字段 | 类型 | 必返 | 说明 |
|---|---|---|---|
| file_id | string (uuid) | 是 | 稳定文件 ID,仅在当前用户网盘内有效 |
| path | string | 是 | 当前用户的文件路径,用于后续读取和附件引用 |
| size | integer | 是 | 文件字节数 |
| is_directory | boolean | 是 | 是否为目录 |
| mime_type | string | 是 | MIME 类型 |
| source | string | 是 | 服务端记录的文件来源 |
| metadata | object | 是 | 字符串键值元数据,无内容时为 {} |
| created_at | string | 是 | RFC3339 创建时间 |
| modified_at | string | 是 | RFC3339 修改时间 |
| storage_path | string | 否 | 逻辑存储路径,不是 OSS 对象 key |
| moderation_state | string | 否 | 文件审核状态,按实际结果返回 |
| display_name | string | 否 | 展示名称,按实际结果返回 |
| presigned_url | string | 否 | 临时访问地址,未生成时省略 |
调用示例
示例使用认证接入定义的 appRequest。
错误处理
401 表示认证失败;403 表示文件权限或审核策略拒绝;404 表示当前用户下找不到文件,不能通过更换用户 ID 绕过归属校验。400/422 时检查 path、file_id 及读取参数;500 为服务端故障,503 为服务暂不可用,504 为请求超时。读取失败不能据此认定文件已经删除。
业务错误通常返回 code、message;鉴权失败可能为空正文,参数解析错误可能为纯文本。先检查 HTTP 状态和 Content-Type,再解析正文。