tcjlj/MeBox
1
0
Fork 0
mirror of https://github.com/truewhile/MeBox.git synced 2026-10-14 09:06:37 +08:00
Code Issues Packages Projects Releases Wiki Activity

优化，添加115接口文档

Browse Source
This commit is contained in:
truewhile
2026-09-05 14:32:58 +08:00
parent d00b14df55
commit 0e9fb2c937
57 changed files with 5682 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files
115doc/115开放平台/API列表/文件管理/文件上传/上传流程.md
+41
View File
@@ -0,0 +1,41 @@
# 上传流程
### 基本信息
| 属性 | 内容 |
|:---------|:------------------------------|
| 文档名称 | 上传流程 |
| 文档版本 | v1.0 |
| 适用场景 | 115开放平台文件上传 |
### 文档说明
本文档说明 115 开放平台的文件秒传、普通上传和断点续传流程。
## 流程概览
1. 请求「文件上传」接口初始化上传。
2. 若响应中 `status=2`，表示秒传成功，上传流程结束。
3. 若响应提示需要二次认证，按 `sign_check` 指定的字节范围计算大写 SHA1，然后携带 `sign_key` 和 `sign_val` 重新请求「文件上传」接口。
4. 若 `status=1`，携带初始化响应中的 `bucket`、`object`、`callback` 及「获取上传凭证」接口返回的凭证，向对象存储上传文件。
5. 需要续传时，携带初始化响应中的 `pick_code` 及待上传文件信息请求「断点续传」接口，获取新的对象存储上传参数。
6. 对象存储返回上传成功后，普通上传或断点续传完成。
## 相关接口
- [文件上传](文件上传.md)
- [获取上传凭证](获取上传凭证.md)
- [断点续传](断点续传.md)
- [阿里云 OSS 上传文件说明](https://help.aliyun.com/zh/oss/user-guide/upload-objects-to-oss/)
## 注意事项
- 对象存储上传不请求 `proapi.115.com`，应使用「获取上传凭证」和上传调度接口返回的域名、对象标识、临时凭证与回调参数发起请求。
- `sign_check` 的起止字节均在 SHA1 计算范围内。例如 `0-99` 表示计算共 100 字节的内容。
- 调用开放平台接口时必须携带 `Authorization: Bearer access_token`，并妥善保管临时上传凭证。
### 修改历史
| 修改时间 | 修改说明 |
|:-----------------------------|:-----|
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
115doc/115开放平台/API列表/文件管理/文件上传/文件上传.md
+141
View File
@@ -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 | 创建文档 |
115doc/115开放平台/API列表/文件管理/文件上传/断点续传.md
+110
View File
@@ -0,0 +1,110 @@
## 断点续传
### 基本信息
| 属性 | 内容 |
|:---------|:------------------------------|
| 接口名称 | 断点续传 |
| 接口版本 | v1.0 |
| 接口路径 | /upload/resume |
| 请求方法 | POST |
| 接口状态 | 生产环境 |
### 接口说明
根据已有上传任务和待上传文件信息，获取断点续传所需的对象存储上传参数。
### 接口地址
```
https://proapi.115.com/open/upload/resume
```
### 请求方式
```
POST
Content-Type: multipart/form-data
```
### 认证方式
```
Authorization: Bearer access_token
```
### 请求参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 约束/示例 |
|:----------|:-----|:---|:----|:------------------|:--------------------|
| file_size | int | 是 | - | 文件大小，单位为字节 | 5335 |
| target | string | 是 | - | 文件上传目标 | `U_1_0`，格式为 `U_1_<文件夹ID>` |
| fileid | string | 是 | - | 文件 SHA1 值 | `<FILE_SHA1>` |
| pick_code | string | 是 | - | 上传任务唯一标识 | `<PICK_CODE>` |
### 请求示例
```shell
curl 'https://proapi.115.com/open/upload/resume' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-F 'file_size=5335' \
-F 'target=U_1_0' \
-F 'fileid=<FILE_SHA1>' \
-F 'pick_code=<PICK_CODE>'
```
### 响应字段说明
| 字段 | 类型 | 描述 |
|:--------------------------|:------|:----------------------|
| state | boolean | 状态码，是表示成功，否表示异常 |
| message | string | 异常信息 |
| code | int | 异常码 |
| data | object | 续传调度数据 |
| data.version | string | 上传接口版本 |
| data.target | string | 文件上传目标 |
| data.pick_code | string | 上传任务唯一标识 |
| data.bucket | string | 对象存储 bucket |
| data.object | string | OSS 对象标识 |
| data.callback | object | 上传完成回调数据 |
| data.callback.callback | string | 上传完成回调信息 |
| data.callback.callback_var | string | 上传完成回调参数 |
### 响应示例
```json
{
"state": true,
"message": "",
"code": 0,
"data": {
"version": "",
"target": "U_1_0",
"pick_code": "",
"bucket": "",
"object": "",
"callback": {
"callback": "",
"callback_var": ""
}
}
}
```
### 业务规则
- `target` 必须匹配 `U_1_<数字文件夹ID>`；`U_1_0` 表示网盘根目录。
- 非 VIP 用户单文件大小不得超过 5 GiB；尝鲜VIP、体验VIP用户单文件大小不得超过 15 GiB。
- 续传前会检查用户剩余空间和盗播上传封禁状态。
- 上游调度结果的 `status` 只有为 1 或 2 时才按成功响应返回续传参数。
### 注意事项
- `pick_code` 必须来自原上传初始化调度响应，并与当前文件信息匹配。
- 请妥善保管 `access_token`、上传凭证与回调数据，不要在日志或客户端可见信息中输出。
### 修改历史
| 修改时间 | 修改说明 |
|:-----------------------------|:-----|
| 2025年04月01日(周二) 00:00:00 | 创建文档 |
115doc/115开放平台/API列表/文件管理/文件上传/获取上传凭证.md
+87
View File
@@ -0,0 +1,87 @@
## 获取上传凭证
### 基本信息
| 属性 | 内容 |
|:---------|:------------------------------|
| 接口名称 | 获取上传凭证 |
| 接口版本 | v1.0 |
| 接口路径 | /upload/get_token |
| 请求方法 | GET |
| 接口状态 | 生产环境 |
### 接口说明
获取对象存储上传域名和临时上传凭证。
### 接口地址
```
https://proapi.115.com/open/upload/get_token
```
### 请求方式
```
GET
```
### 认证方式
```
Authorization: Bearer access_token
```
### 请求参数
无
### 请求示例
```shell
curl 'https://proapi.115.com/open/upload/get_token' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'
```
### 响应字段说明
| 字段 | 类型 | 描述 |
|:-------------------|:------|:---------------|
| state | boolean | 状态码，是表示成功，否表示异常 |
| message | string | 异常信息 |
| code | int | 异常码 |
| data | object | 上传凭证数据 |
| data.endpoint | string | 上传域名 |
| data.AccessKeySecret | string | 临时上传凭证密钥 |
| data.SecurityToken | string | 临时安全令牌 |
| data.Expiration | string | 上传凭证过期时间 |
| data.AccessKeyId | string | 临时上传凭证 ID |
### 响应示例
```json
{
"state": true,
"message": "",
"code": 0,
"data": {
"endpoint": "",
"AccessKeySecret": "",
"SecurityToken": "",
"Expiration": "",
"AccessKeyId": ""
}
}
```
### 注意事项
- 网页版文档中的密钥字段名存在拼写误差，服务端实际返回字段为 `AccessKeySecret`。
- 上传凭证为敏感信息，仅用于当前上传流程；不要写入日志、持久化存储或对外暴露。
- 服务端通过当前 `access_token` 识别用户，不接收用户账号请求参数。
### 修改历史
| 修改时间 | 修改说明 |
|:-----------------------------|:-----|
| 2025年04月01日(周二) 00:00:00 | 创建文档 |