优化，添加115接口文档

2026-10-14 00:56:37 +08:00 · 2026-09-05 14:32:58 +08:00
parent d00b14df55
commit 0e9fb2c937
57 changed files with 5682 additions and 76 deletions
@@ -0,0 +1,141 @@
+## 文件上传
+
+### 基本信息
+
+| 属性       | 内容                            |
+|:---------|:------------------------------|
+| 接口名称     | 文件上传                         |
+| 接口版本     | 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 | 创建文档 |