查询目录内容

Drive 目前为 Beta 功能，接口定义、响应结构和行为可能发生变化。请关注文档更新，并在生产环境使用前完成兼容性验证。

GET /api/v1/forward/drives/entries

请求头

Header	是否必填	说明
Authorization	是	`Bearer <PAT 或 SAT>`

查询参数

参数	类型	是否必填	说明
identity_id	string	是	当前认证范围内的 Identity ID，只能出现一次；Identity 级 SAT 只能选择其绑定的 Identity。
path	string	否	相对目录路径；默认空字符串，表示根目录。
limit	integer	否	默认 20，范围 1～100；只能出现一次。
page_token	string	否	上一次响应的 `next_page_token`，首次查询省略。必须用于相同凭证资源范围、Identity 和目录；最多 8192 字节，不得修改。

路径规则

省略 path 或传空字符串表示根目录。非空路径遵循以下规则：

使用有效 UTF-8 相对路径，如 projects/reports，不接受绝对路径，如 /projects/reports 或 C:/projects/reports。
使用 / 分隔目录，不允许开头或结尾的 /、连续 /、反斜杠，以及 .、.. 路径段。
不允许首尾空白、控制字符或 %（包括 projects%2Freports 这样的转义文本）。

以上规则针对解码后的路径。Query 编码：

保留路径分隔符 /，如 path=projects/reports，不要编码为 %2F。
中文和保留字符使用标准表单 URL 编码，空格使用 +。

示例请求

curl --silent --show-error --fail-with-body -X GET \
  "https://api.qoder.com/api/v1/forward/drives/entries?identity_id=idn_xxx&path=projects&limit=20" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

示例响应

HTTP 200 OK

{
  "entries": [
    {
      "path": "projects/demo",
      "name": "demo",
      "type": "directory"
    },
    {
      "path": "projects/readme.md",
      "name": "readme.md",
      "type": "file",
      "size": 2048,
      "etag": "example-etag",
      "last_modified": "2026-09-07T02:00:00Z"
    }
  ]
}

响应字段

字段	类型	说明
entries	array	当前目录的直接子项，按路径字典序返回；目录不存在或为空时为 `[]`。
entries[].path	string	Drive 内相对路径，目录不带末尾 `/`。
entries[].name	string	当前层级的文件名或目录名。
entries[].type	string	`file` 或 `directory`。
entries[].size	integer	文件大小，单位字节，零字节文件为 0；目录省略。
entries[].etag	string	文件 ETag，非空时返回；目录省略。
entries[].last_modified	string	文件最近修改时间，RFC 3339；无时间值时省略，目录省略。
next_page_token	string	还有下一页时返回；最后一页省略。原样传入下一次请求的 `page_token`。

错误

HTTP	Code	触发条件
400	`invalid_drive_path`	路径或 Query 中的路径编码不合法，或 Identity 标识格式不合法。
400	`invalid_limit`	分页大小不是 1～100 的整数，或重复传入。
400	`invalid_page_token`	分页令牌无效、被修改，或用于其他资源范围、Identity、目录。
400	`invalid_identity_id`	`identity_id` 缺失、为空或重复传入。
401	—	凭证缺失或无效；Service Account Key 需先换取 SAT。
403	`identity_mismatch`	Identity 级 SAT 选择了其他 Identity。
404	`identity_not_found`	当前认证范围内未找到 Identity。
500	—	服务内部错误。
503	`drive_unavailable`	Drive 存储、签名或依赖能力暂不可用。

HTTP 错误响应

{
  "type": "error",
  "request_id": "req_xxx",
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_drive_path",
    "message": "Invalid Drive path."
  }
}

响应字段

字段	类型	说明
type	string	固定为 `error`。
request_id	string	请求追踪 ID，可用时返回。
error.type	string	错误大类，如 `invalid_request_error`、`authentication_error`、`permission_error`、`not_found_error`、`conflict_error`、`api_error`。
error.code	string	业务错误码，部分公共错误不返回此字段。
error.message	string	错误描述。

入口鉴权错误可能使用不同的响应结构。

查询目录内容

请求头

查询参数

路径规则

示例请求

示例响应

响应字段

错误

HTTP 错误响应

响应字段

相关

申请上传 URL

申请下载 URL

​请求头

​查询参数

​路径规则

​示例请求

​示例响应

​响应字段

​错误

​HTTP 错误响应

​响应字段

​相关

申请上传 URL

申请下载 URL

请求头

查询参数

路径规则

示例请求

示例响应

响应字段

错误

HTTP 错误响应

响应字段

相关