mirror of
https://github.com/truewhile/MeBox.git
synced 2026-09-28 03:06:38 +08:00
truewhile
142 lines
6.1 KiB
Markdown
142 lines
6.1 KiB
Markdown
## 文件上传
|
||
|
||
### 基本信息
|
||
|
||
| 属性 | 内容 |
|
||
|:---------|:------------------------------|
|
||
| 接口名称 | 文件上传 |
|
||
| 接口版本 | v1.0 |
|
||
| 接口路径 | /upload/init |
|
||
| 请求方法 | POST |
|
||
| 接口状态 | 生产环境 |
|
||
|
||
### 接口说明
|
||
|
||
初始化断点续传调度，完成秒传判定、二次认证调度或返回对象存储上传参数。
|
||
|
||
### 接口地址
|
||
|
||
```
|
||
https://proapi.115.com/open/upload/init
|
||
```
|
||
|
||
### 请求方式
|
||
|
||
```
|
||
POST
|
||
Content-Type: multipart/form-data
|
||
```
|
||
|
||
### 认证方式
|
||
|
||
```
|
||
Authorization: Bearer access_token
|
||
```
|
||
|
||
### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|
||
|:----------|:-----|:---|:----|:---------------------------|:--------------------|
|
||
| file_name | string | 是 | - | 文件名 | 图片.jpg |
|
||
| file_size | int | 是 | - | 文件大小，单位为字节 | 5335 |
|
||
| target | string | 是 | - | 文件上传目标 | `U_1_0`，格式为 `U_1_<文件夹ID>` |
|
||
| fileid | string | 是 | - | 文件 SHA1 值 | `<FILE_SHA1>` |
|
||
| preid | string | 否 | "" | 文件前 128 KiB 内容的 SHA1 值 | `<PREID_SHA1>` |
|
||
| path | string | 否 | "" | 上传路径 | "" |
|
||
| pick_code | string | 否 | "" | 上传任务唯一标识，用于续传 | `<PICK_CODE>` |
|
||
| topupload | int | 否 | "" | 上传调度文件类型标记，见下方枚举表格 | 0 |
|
||
| sign_key | string | 否 | "" | 二次认证标识 | `<SIGN_KEY>` |
|
||
| sign_val | string | 否 | "" | 根据 `sign_check` 计算的大写 SHA1 值 | `<SIGN_VAL>` |
|
||
|
||
#### 请求参数中的 topupload 字段枚举
|
||
|
||
| 值 | 说明 | 备注 |
|
||
|:---|:---------------------------|:---|
|
||
| -1 | 没有上传调度文件类型标记 | - |
|
||
| 0 | 单文件上传任务，记录一条独立上传记录 | - |
|
||
| 1 | 文件夹任务的第一个子文件，记录一次文件夹上传 | - |
|
||
| 2 | 文件夹任务的其他子文件，不单独记录上传记录 | - |
|
||
|
||
### 请求示例
|
||
|
||
```shell
|
||
curl 'https://proapi.115.com/open/upload/init' \
|
||
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
|
||
-F 'file_name=图片.jpg' \
|
||
-F 'file_size=5335' \
|
||
-F 'target=U_1_0' \
|
||
-F 'fileid=<FILE_SHA1>' \
|
||
-F 'topupload=0'
|
||
```
|
||
|
||
### 响应字段说明
|
||
|
||
| 字段 | 类型 | 描述 |
|
||
|:--------------------------|:------|:----------------------------------------|
|
||
| state | boolean | 状态码，是表示成功，否表示异常 |
|
||
| message | string | 异常信息 |
|
||
| code | int | 异常码 |
|
||
| data | object | 上传调度数据 |
|
||
| data.status | int | 上传状态：1-非秒传 2-秒传 |
|
||
| data.code | int | 上传调度状态码 |
|
||
| data.pick_code | string | 上传任务唯一标识，用于续传 |
|
||
| data.target | string | 文件上传目标 |
|
||
| data.bucket | string | 对象存储 bucket |
|
||
| data.object | string | OSS 对象标识 |
|
||
| data.callback | object | 上传完成回调数据 |
|
||
| data.callback.callback | string | 上传完成回调信息 |
|
||
| data.callback.callback_var | string | 上传完成回调参数 |
|
||
| data.sign_key | string | 本次二次认证的 SHA1 标识 |
|
||
| data.sign_check | string | 二次认证所需本地文件 SHA1 计算的字节范围 |
|
||
| data.file_id | string | 秒传成功时新增文件 ID |
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"state": true,
|
||
"message": "",
|
||
"code": 0,
|
||
"data": {
|
||
"status": 1,
|
||
"code": 0,
|
||
"pick_code": "",
|
||
"target": "U_1_0",
|
||
"bucket": "",
|
||
"object": "",
|
||
"callback": {
|
||
"callback": "",
|
||
"callback_var": ""
|
||
},
|
||
"sign_key": "",
|
||
"sign_check": "",
|
||
"file_id": ""
|
||
}
|
||
}
|
||
```
|
||
|
||
### 业务规则
|
||
|
||
- `target` 必须匹配 `U_1_<数字文件夹ID>`；`U_1_0` 表示网盘根目录。
|
||
- 非 VIP 用户单文件大小不得超过 5 GiB；尝鲜VIP、体验VIP用户单文件大小不得超过 15 GiB。
|
||
- 上传前会检查用户剩余空间和盗播上传封禁状态。
|
||
- 二次认证调度结果见下表。
|
||
|
||
| code | status | 说明 | 后续处理 |
|
||
|:-----|:-------|:---------|:------|
|
||
| 700 | 6 | 签名认证后失败 | 按 `sign_check` 截取包含起止字节的文件内容计算大写 SHA1，再传入 `sign_key` 和 `sign_val` |
|
||
| 701 | 7 | 需要认证签名 | 按 `sign_check` 截取包含起止字节的文件内容计算大写 SHA1，再传入 `sign_key` 和 `sign_val` |
|
||
| 702 | 8 | 签名认证失败 | 按 `sign_check` 截取包含起止字节的文件内容计算大写 SHA1，再传入 `sign_key` 和 `sign_val` |
|
||
|
||
### 注意事项
|
||
|
||
- `sign_check` 格式为 `起始字节-结束字节`，起止字节均包含在 SHA1 计算范围内；例如 `2392148-2392298` 需计算该范围内文件内容的 SHA1。
|
||
- 省略 `topupload` 时，服务端会将其归一化为空字符串；显式传入枚举值时会归一化为整数。
|
||
- 请妥善保管 `access_token`、上传凭证与回调数据，不要在日志或客户端可见信息中输出。
|
||
|
||
### 修改历史
|
||
|
||
| 修改时间 | 修改说明 |
|
||
|:-----------------------------|:-----|
|
||
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
|