Drive 目前为 Beta 功能，接口定义、响应结构和行为可能发生变化。请关注文档更新，并在生产环境使用前完成兼容性验证。
POST /api/v1/forward/drives/download-url
请求头
| Header | 是否必填 | 说明 |
|---|
| Authorization | 是 | Bearer <PAT 或 SAT> |
| Content-Type | 是 | application/json |
| Idempotency-Key | 否 | 同一次请求重试复用原值，见幂等重试。 |
查询参数
| 参数 | 类型 | 是否必填 | 说明 |
|---|
| identity_id | string | 是 | 当前认证范围内的 Identity ID，只能出现一次；Identity 级 SAT 只能选择其绑定的 Identity。 |
请求体参数
| 参数 | 类型 | 是否必填 | 说明 |
|---|
| path | string | 是 | 待下载文件的相对路径，不能为根目录或目录。 |
路径规则
- 使用有效 UTF-8 相对路径，如
projects/reports，不接受绝对路径，如 /projects/reports 或 C:/projects/reports。
- 使用
/ 分隔目录，不允许开头或结尾的 /、连续 /、反斜杠，以及 .、.. 路径段。
- 不允许首尾空白、控制字符或
%（包括 projects%2Freports 这样的转义文本）。
示例请求
curl --silent --show-error --fail-with-body -X POST \
"https://api.qoder.com/api/v1/forward/drives/download-url?identity_id=idn_xxx" \
-H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"path": "projects/readme.md"
}'
示例响应
HTTP 200 OK
{
"url": "https://storage.example.com/signed-download-url",
"method": "GET",
"headers": {},
"expires_at": "2026-09-07T02:15:00Z",
"size": 2048,
"etag": "example-etag",
"content_type": "text/markdown"
}
响应字段
| 字段 | 类型 | 说明 |
|---|
| url | string | 签名 URL。 |
| method | string | 固定为 GET。 |
| headers | object | 使用签名 URL 时必须携带的 Header；无要求时为 {}。 |
| expires_at | string | 到期时间，RFC 3339；签发后 15 分钟有效。 |
| size | integer | 文件大小，单位字节；值为 0 时省略。 |
| etag | string | 文件 ETag；非空时返回。 |
| content_type | string | 文件 MIME 类型；非空时返回。 |
幂等重试
本接口可选传 Idempotency-Key。同一请求重试保持认证范围、Identity、key 和请求体原始内容一致；重放响应包含 Idempotency-Replayed: true。刷新签名 URL 时省略该 Header 或使用新值，重放不会延长有效期。
| HTTP | Code | 触发条件 |
|---|
| 400 | invalid_drive_path | 文件路径不合法，或 Identity 标识格式不合法。 |
| 400 | — | 请求体不是合法 JSON、字段类型错误或包含未知字段。 |
| 400 | invalid_identity_id | identity_id 缺失、为空或重复传入。 |
| 401 | — | 凭证缺失或无效；Service Account Key 需先换取 SAT。 |
| 403 | identity_mismatch | Identity 级 SAT 选择了其他 Identity。 |
| 404 | drive_entry_not_found | 对应文件不存在。 |
| 404 | identity_not_found | 当前认证范围内未找到 Identity。 |
| 409 | idempotency_key_reused | 同一 key 对应不同请求体。 |
| 409 | idempotency_key_in_progress | 相同 key 的请求仍在处理，重试间隔见 Retry-After。 |
| 413 | — | 请求体超过服务限制。 |
| 500 | — | 服务内部错误。 |
| 503 | drive_unavailable | Drive 存储、签名或依赖能力暂不可用。 |
| 503 | idempotency_unavailable | 幂等存储暂不可用。 |
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 | 错误描述。 |
error 对象，请求追踪 ID 位于 error.request_id。签名 URL 的存储服务错误使用独立响应格式。
入口鉴权错误可能使用不同的响应结构。
