Skip to main content

读取文件与下载地址

千问办公企业旗舰版开发者文档:读取文件与下载地址。

认证方式见APP开发者文档 → 认证接入。
  • 模块:文件服务
  • 接口:GET/api/openapi/app/v1/drive/files
  • operationId:appGetDriveFile

接口说明

按当前用户的个人文件路径或 file_id 查询。向对象存储地址请求时仅使用返回的 URL 和 headers,不附带业务认证凭据。 接口面向当前认证用户的文件,文件归属由 Barn 校验。不接受管理 API Key、Agent Token 或其他用途 OAuth 凭据替代。调用方不得自行设置 X-Gw 身份头。 按 ID 定位后,文件或父目录重命名不改变该 ID。删除后同路径重建会得到新 ID。

请求参数

参数/字段位置类型必填说明
pathquerystring二选一当前用户绝对逻辑路径,使用 query 编码
file_idquerystring (uuid)二选一单个非零 UUID,与 path 不能同时传;其他用户 ID 返回 404
modequerystring否preview、download、edit;默认 download
sizequerystring否sm 缩略图

响应

200 返回文件信息;presigned_url 可能省略。
字段类型必返说明
file_idstring (uuid)是稳定文件 ID,仅在当前用户网盘内有效
pathstring是当前用户的文件路径,用于后续读取和附件引用
sizeinteger是文件字节数
is_directoryboolean是是否为目录
mime_typestring是MIME 类型
sourcestring是服务端记录的文件来源
metadataobject是字符串键值元数据,无内容时为 {}
created_atstring是RFC3339 创建时间
modified_atstring是RFC3339 修改时间
storage_pathstring否逻辑存储路径,不是 OSS 对象 key
moderation_statestring否文件审核状态,按实际结果返回
display_namestring否展示名称,按实际结果返回
presigned_urlstring否临时访问地址,未生成时省略
使用 file_id 时返回下载地址,不应用 mode/size 预览选项;预览与编辑继续按 path 调用。

调用示例

示例使用认证接入定义的 appRequest。
const query = new URLSearchParams({ path: '/Uploads/input.txt', mode: 'download' });
const response = await appRequest(`/api/openapi/app/v1/drive/files?${query}`, {

});
if (!response.ok) throw new Error(`读取失败:${response.status}`);
const file = await response.json();
// file.presigned_url 可能省略;有值时原样使用,不附带登录凭据。

错误处理

401 表示认证失败;403 表示文件权限或审核策略拒绝;404 表示当前用户下找不到文件,不能通过更换用户 ID 绕过归属校验。400/422 时检查 path、file_id 及读取参数;500 为服务端故障,503 为服务暂不可用,504 为请求超时。读取失败不能据此认定文件已经删除。 业务错误通常返回 code、message;鉴权失败可能为空正文,参数解析错误可能为纯文本。先检查 HTTP 状态和 Content-Type,再解析正文。