## 上传流程

#### 1.创建文件

1. 调用创建文件接口，接口返回的`reuse`为true时，表示秒传成功，上传结束。
2. 非秒传情况将会返回预上传ID`preuploadID`与分片大小`sliceSize`，请将文件根据分片大小切分。
3. 非秒传情况下返回`servers`为后续上传文件的对应域名（重要），多个任选其一。

#### 2.上传分片

1. 该步骤准备工作，按照`sliceSize`将文件切分，并计算每个分片的MD5。
2. 调用上传分片接口，传入对应参数，注意此步骤 `Content-Type: multipart/form-data`**。**

#### 3. 上传完毕 

1. 调用上传完毕接口，若接口返回的`completed`为 ture 且`fileID`不为0时，上传完成。
2. 若接口返回的`completed`为 false 时，则需间隔1秒继续轮询此接口，获取上传最终结果。



## 创建文件

API： POST   域名 + /upload/v2/file/create

说明：

文件名要小于256个字符且不能包含以下任何字符："\/:*?|><

文件名不能全部是空格

开发者上传单文件大小限制10GB

#### Header 参数

| 名称          | 类型   | 是否必填 | 说明                 |
| ------------- | ------ | -------- | -------------------- |
| Authorization | string | 必填     | 鉴权access_token     |
| Platform      | string | 必填     | 固定为:open_platform |

#### Body 参数

| 名称         | 类型   | 是否必填 | 说明                                                         |
| ------------ | ------ | -------- | ------------------------------------------------------------ |
| parentFileID | number | 必填     | 父目录id，上传到根目录时填写 0                               |
| filename     | string | 必填     | 文件名要小于255个字符且不能包含以下任何字符："\/:*?\|><。（注：不能重名）containDir 为 true 时，传入路径+文件名，例如：/你好/123/测试文件.mp4 |
| etag         | string | 必填     | 文件md5                                                      |
| size         | number | 必填     | 文件大小，单位为 byte 字节                                   |
| duplicate    | number | 非必填   | 当有相同文件名时，文件处理策略（1保留两者，新文件名将自动添加后缀，2覆盖原文件） |
| containDir   | bool   | 非必填   | 上传文件是否包含路径，默认false                              |

#### 返回数据 

| 名称        | 类型    | 是否必填 | 说明                                                         |
| ----------- | ------- | -------- | ------------------------------------------------------------ |
| fileID      | number  | 非必填   | 文件ID。当123云盘已有该文件,则会发生秒传。此时会将文件ID字段返回。唯一 |
| preuploadID | string  | 必填     | 预上传ID(如果 reuse 为 true 时,该字段不存在)                 |
| reuse       | boolean | 必填     | 是否秒传，返回true时表示文件已上传成功                       |
| sliceSize   | number  | 必填     | 分片大小，必须按此大小生成文件分片再上传                     |
| servers     | array   | 必填     | 上传地址                                                     |



#### 响应示例

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "fileID": 0,
    "reuse": false,
    "preuploadID": "WvjyUgonimrlBq2PVJ3bSyjPVJYP4IGeSxGdSly...(过长省略)",
    "sliceSize": 16777216,
    "servers": [
      "http://openapi-upload.123242.com"
    ]
  },
  "x-traceID": "2f41bbb4-93ab-459b-8dab-2204d3b3ff66_kong-db-5898fdd8c6-wnv6h"
}
```





## 上传分片

API： POST   上传域名 + /upload/v2/file/slice

说明：

上传域名是创建文件接口响应中的servers

Content-Type: multipart/form-data

#### Header 参数

| 名称          | 类型   | 是否必填 | 说明                 |
| ------------- | ------ | -------- | -------------------- |
| Authorization | string | 必填     | 鉴权access_token     |
| Platform      | string | 必填     | 固定为:open_platform |

#### Body 参数

| 名称        | 类型   | 是否必填 | 说明                  |
| ----------- | ------ | -------- | --------------------- |
| preuploadID | string | 必填     | 预上传ID              |
| sliceNo     | number | 必填     | 分片序号，从1开始自增 |
| sliceMD5    | string | 必填     | 当前分片md5           |
| slice       | file   | 必填     | 分片二进制流          |

#### 返回数据 

无



#### 响应示例

```json
{
	"code": 0,
	"message": "ok",
	"data": null,
	"x-traceID": ""
}
```



## 上传完毕

API： POST   域名 + /upload/v2/file/upload_complete

说明：分片上传完成后请求

#### Header 参数

| 名称          | 类型   | 是否必填 | 说明                 |
| ------------- | ------ | -------- | -------------------- |
| Authorization | string | 必填     | 鉴权access_token     |
| Platform      | string | 必填     | 固定为:open_platform |

#### Body 参数

| 名称        | 类型   | 是否必填 | 说明     |
| ----------- | ------ | -------- | -------- |
| preuploadID | string | 必填     | 预上传ID |

#### 返回数据

| 名称      | 类型   | 是否必填 | 说明           |
| --------- | ------ | -------- | -------------- |
| completed | bool   | 必填     | 上传是否完成   |
| fileID    | number | 必填     | 上传完成文件id |

#### 响应示例

```json
{
	"code": 0,
	"message": "ok",
	"data": {
		"completed": true,
		"fileID": 11522654
	},
	"x-traceID": "65562117-5c67-4d69-98cb-0f65201f83d3_test-kong-7787db5b5-wggzb"
}
```

## 获取上传域名

API： GET 域名 + /upload/v2/file/domain

#### Header 参数

| 名称          | 类型   | 是否必填 | 说明                 |
| ------------- | ------ | -------- | -------------------- |
| Authorization | string | 必填     | 鉴权access_token     |
| Platform      | string | 必填     | 固定为:open_platform |

####  Body 参数

无

#### 返回数据 

| 名称 | 类型  | 是否必填 | 说明                           |
| ---- | ----- | -------- | ------------------------------ |
| data | array | 必填     | 上传域名，存在多个可以任选其一 |

 

#### 响应示例

```json
{
	"code": 0,
	"message": "ok",
	"data": [
		"https://openapi-upload.123pan.com"
	],
	"x-traceID": ""
}
```





## 单步上传

API： POST   上传域名 + /upload/v2/file/single/create

说明：

文件名要小于256个字符且不能包含以下任何字符："\/:*?|><

文件名不能全部是空格

此接口限制开发者上传单文件大小为1GB

上传域名是获取上传域名接口响应中的域名

此接口用于实现小文件单步上传一次HTTP请求交互即可完成上传

#### Header 参数

| 名称          | 类型   | 是否必填 | 说明                 |
| ------------- | ------ | -------- | -------------------- |
| Authorization | string | 必填     | 鉴权access_token     |
| Platform      | string | 必填     | 固定为:open_platform |

#### Body 参数

| 名称         | 类型   | 是否必填 | 说明                                                         |
| ------------ | ------ | -------- | ------------------------------------------------------------ |
| parentFileID | number | 必填     | 父目录id，上传到根目录时填写 0                               |
| filename     | string | 必填     | 文件名要小于255个字符且不能包含以下任何字符："\/:*?\|><。（注：不能重名）containDir 为 true 时，传入路径+文件名，例如：/你好/123/测试文件.mp4 |
| etag         | string | 必填     | 文件md5                                                      |
| size         | number | 必填     | 文件大小，单位为 byte 字节                                   |
| file         | file   | 必填     | 文件二进制流                                                 |
| duplicate    | number | 非必填   | 当有相同文件名时，文件处理策略（1保留两者，新文件名将自动添加后缀，2覆盖原文件） |
| containDir   | bool   | 非必填   | 上传文件是否包含路径，默认false                              |

#### 返回数据 

| 名称      | 类型   | 是否必填 | 说明                                                         |
| --------- | ------ | -------- | ------------------------------------------------------------ |
| fileID    | number | 必填     | 文件ID。当123云盘已有该文件,则会发生秒传。此时会将文件ID字段返回。唯一 |
| completed | bool   | 必填     | 是否上传完成（如果 completed 为 true 时，则说明上传完成）    |

####  响应示例

```json
{
	"code": 0,
	"message": "ok",
	"data": {
		"fileID": 11522653,
		"completed": true
	},
	"x-traceID": ""
}
```

