分段上传
对于较大文件上传，可以切分成段上传。用户可以在如下的应用场景内（但不仅限于此），使用分段上传的模式：
- 上传超过100MB大小的文件。
- 网络条件较差，和OBS等存储服务端之间的连接经常断开。
- 上传前无法确定将要上传文件的大小。
分段上传分为如下3个步骤：
- 初始化分段上传任务，即创建分段上传任务。
- 上传分段。
- 完成上传合并段或终止（即取消）分段上传任务。
完成上传合并段，文件会存储到桶中。终止（即取消）分段上传任务，之前所有上传的分段内容将会被丢弃。
- URI
POST AstroZero域名/u-route/baas/sys/v1.1/connectors/{connector_type}/{connector_name}/createmultipartupload?object=X
表1 路径参数 参数
是否必选
参数类型
描述
connector_type
是
String
参数解释：
连接器的类型。
约束限制：
不涉及。
取值范围：
- obs：与OBS对接的连接器。
- minio：与MINIO对接的连接器。
- objectstorageproxy：对象存储代理类型。
默认取值：
不涉及。
connector_name
是
String
参数解释：
连接器实例的名称，即创建连接器时设置的连接器实例名。
约束限制：
不涉及。
取值范围：
不涉及。
默认取值：
不涉及。
object
是
String
参数解释：
上传文件到桶里的全路径，包含文件名、文件类型、上传到桶里的路径。不携带路径时，表示上传到桶的根目录下
示例：取值为“a/b/c/test.mp4”，表示将文件“test.mp4”上传到桶的“a/b/c”路径下。如果桶中不存在该路径，会创建该路径。
约束限制：
不涉及。
取值范围：
不涉及。
默认取值：
不涉及。
- 请求参数
表2 请求消息头参数说明 消息头名称
是否必选
参数类型
描述
Content-Type
是
String
参数解释：
上传文件的媒体类型，必须与文件名一致，例如文件名为“test.mp4”，则“Content-Type”值为“video/mp4”。
约束限制：
不涉及。
取值范围：
不涉及。
默认取值：
不涉及。
- 响应参数
表3 响应参数说明 参数
参数类型
描述
resCode
String
参数解释：
返回码。
取值范围：
如果返回“0”代表请求成功，其他错误码说明请参考错误码。
resMsg
String
参数解释：
返回消息。
取值范围：
如果成功状态，通常会返回“Success”，其他情况会返回具体的错误信息。
result
Object
参数解释：
返回创建的分段任务对象。对象中包含“uploadId”字段，表示该任务的全局唯一标识，用于标识本次分段上传任务。可以根据这个唯一标识，来发起后续相关的操作，如上传分段任务、合并段完成上传、终止（即取消）分段上传任务。
- 请求示例
已创建好OBS类型连接器，连接器实例名称为“命名空间__TestOBS”，需要向该OBS桶的“a/b/c”路径下上传大文件。调用如下请求，初始化分段上传任务。
POST https://AstroZero域名/u-route/baas/sys/v1.1/connectors/obs/命名空间__TestOBS/createmultipartupload?object=a/b/c/test.mp4
- 响应示例
{ "resCode": "0", "resMsg": "成功", "result": { "uploadId": "0000017B761F112966C45D8FF0F75F13" } }请记录“uploadId”的值，用于标识本次分段上传任务，后续相关的操作需要使用到该标识。
上传分段
- 功能介绍
初始化分段上传任务之后，可以根据指定的对象文件名和“uploadId”来分段上传数据。每一个上传的段都有一个标识它的号码，即分段号（partNumber，范围是1~10000）。对于同一个分段上传任务（即uploadId相同），分段号“partNumber”不但唯一标识这一段数据，也标识了这段数据在整个对象文件内的相对位置。如果使用同一个分段号上传了新的数据，那么存储服务端上已有的这个段号的数据将被覆盖。除了最后一个分段以外，其他分段大小必须大于5MB，最大值对于OBS、MINIO本身来说没有限制，通过AstroZero平台该接口调用时，所有分段最大值不超过100MB。每个分段不需要按顺序上传，甚至可以在不同进程、不同机器上上传，存储服务端会按照分段号排序组成最终对象。
- URI
POST AstroZero域名/u-route/baas/sys/v1.1/connectors/{connector_type}/{connector_name}/uploadpart?object=X&uploadId=Y&partNumber=Z
表4 路径参数 参数
是否必选
参数类型
描述
connector_type
是
String
参数解释：
连接器的类型。
约束限制：
不涉及。
取值范围：
- obs：与OBS对接的连接器。
- minio：与MINIO对接的连接器。
- objectstorageproxy：对象存储代理类型。
默认取值：
不涉及。
connector_name
是
String
参数解释：
连接器实例的名称，即创建连接器时命名的连接器实例名称。
约束限制：
不涉及。
取值范围：
不涉及。
默认取值：
不涉及。
object
是
String
参数解释：
上传文件到桶里的全路径，包含文件名、文件类型、上传到桶里的路径。不携带路径时，表示上传到桶的根目录下
示例：取值为“a/b/c/test.mp4”，表示将文件“test.mp4”上传到桶的“a/b/c”路径下。如果桶中不存在该路径，会创建该路径。
约束限制：
不涉及。
取值范围：
不涉及。
默认取值：
不涉及。
uploadId
是
String
参数解释：
整个分段上传任务的标识，从初始化分段上传任务的返回结果中获取该值。
约束限制：
不涉及。
取值范围：
不涉及。
默认取值：
不涉及。
partNumber
是
Number
参数解释：
分段号。
对于同一个分段上传任务（即uploadId相同），分段号“partNumber”不但唯一标识这一段数据，也标识了这段数据在整个对象文件内的相对位置。
约束限制：
不涉及。
取值范围：
1~10000。
默认取值：
不涉及。
- 请求参数
- 响应参数
表5 响应参数说明 参数
参数类型
描述
resCode
String
参数解释：
返回码。
取值范围：
如果返回“0”代表请求成功，其他错误码说明请参考错误码。
resMsg
String
参数解释：
返回消息。
取值范围：
如果成功状态，通常会返回“Success”，其他情况会返回具体的错误信息。
result
Object
参数解释：
返回分段任务对象，包含如下字段：
- ETag：文件分段的标识， 用于后续完成上传时使用。
- partNumber：分段号，用于后续完成上传时使用。
- 请求示例
已创建好OBS类型连接器，连接器实例名称为“命名空间__TestOBS”，需要向该OBS桶的“a/b/c”路径下上传大文件。已有初始化分段上传任务，标识“uploadId”为“0000017B761F112966C45D8FF0F75F13”，调用如下请求，创建分段上传任务，上传test.mp4，分段号为“1”。
POST https://AstroZero域名/u-route/baas/sys/v1.1/connectors/obs/命名空间__TestOBS/uploadpart?object=a/b/c/test.mp4&uploadId=0000017B761F112966C45D8FF0F75F13&partNumber=1
在请求Body中设置“application/octet-stream”格式的object，即要上传的文件数据。
- 响应示例
{ "resCode": "0", "resMsg": "成功", "result": { "ETag": "\"d41d8cd98f00b204e9800998ecf8427e\"", "partNumber": 1 } }请记录下“ETag”和“partNumber”的值，后续完成上传时需要使用。
完成上传合并段
- 功能介绍
所有分段上传完成后，需要调用完成上传接口，在存储服务端（如OBS）合并段生成最终对象文件。在执行完成上传操作时，需要提供所有有效的分段列表（包括分段号和分段ETag值）。AstroZero收到提交的分段列表后，会逐一验证每个段的有效性。当所有段验证通过后，将把这些分段组合成最终的对象。合并的分段任务可以是不连续的分段号。
完成上传任务后，“uploadId”就失效了，不能再用于终止（即取消）分段上传任务。
- URI
POST AstroZero域名/u-route/baas/sys/v1.1/connectors/{connector_type}/{connector_name}/completeupload?object=X&uploadId=Y
表6 路径参数 参数
是否必选
参数类型
描述
connector_type
是
String
参数解释：
连接器的类型。
约束限制：
不涉及。
取值范围：
- obs：与OBS对接的连接器。
- minio：与MINIO对接的连接器。
- objectstorageproxy：对象存储代理类型。
默认取值：
不涉及。
connector_name
是
String
参数解释：
连接器实例的名称，即创建连接器时命名的连接器实例名称。
约束限制：
不涉及。
取值范围：
不涉及。
默认取值：
不涉及。
object
是
String
参数解释：
上传文件到桶里的全路径，包含文件名、文件类型、上传到桶里的路径。不携带路径时，表示上传到桶的根目录下
示例：取值为“a/b/c/test.mp4”，表示将文件“test.mp4”上传到桶的“a/b/c”路径下。如果桶中不存在该路径，会创建该路径。
约束限制：
不涉及。
取值范围：
不涉及。
默认取值：
不涉及。
uploadId
是
String
参数解释：
整个分段上传任务的标识，从初始化分段上传任务的返回结果中获取该值。
约束限制：
不涉及。
取值范围：
不涉及。
默认取值：
不涉及。
- 请求参数
- 响应参数
表8 响应参数说明 参数
参数类型
描述
resCode
String
参数解释：
返回码。
取值范围：
如果返回“0”代表请求成功，其他错误码说明请参考错误码。
resMsg
String
参数解释：
返回消息。
取值范围：
如果成功状态，通常会返回“Success”，其他情况会返回具体的错误信息。
- 请求示例
已创建好OBS类型连接器，连接器实例名称为“命名空间__TestOBS”，需要向该OBS桶的“a/b/c”路径下上传大文件。已有初始化分段上传任务和两个分段上传任务，标识“uploadId”为“0000017B761F112966C45D8FF0F75F13”，调用如下请求，完成分段上传任务，合并所有分段生成最终对象文件。
POST https://AstroZero域名/u-route/baas/sys/v1.1/connectors/obs/命名空间__TestOBS/completeupload?object=a/b/c/test.mp4&uploadId=0000017B761F112966C45D8FF0F75F13 [{ "ETag": "\"d41d8cd98f00b204e9800998ecf8427e\"", "partNumber": 1 }, { "ETag": "\"7dcad0c8a7398333ff25418bad511581\"", "partNumber": 2 }] - 响应示例
{ "resCode": "0", "resMsg": "成功" }
终止（即取消）分段上传任务
- 功能描述
分段上传任务可以被取消，当一个分段上传任务被取消后，就不能再使用其“uploadId”做任何操作，已经上传段也会被删除。
采用分段上传方式上传文件过程中或上传文件失败后会在桶内产生段，这些段会占用存储空间，可以通过取消该分段上传任务来清理掉不需要的段，节约存储空间。
- URI
POST AstroZero域名/u-route/baas/sys/v1.1/connectors/{connector_type}/{connector_name}/abortupload?object=X&uploadId=Y
表9 路径参数 参数
是否必选
参数类型
描述
connector_type
是
String
参数解释：
连接器的类型。
约束限制：
不涉及。
取值范围：
- obs：与OBS对接的连接器。
- minio：与MINIO对接的连接器。
- objectstorageproxy：对象存储代理类型。
默认取值：
不涉及。
connector_name
是
String
参数解释：
连接器实例的名称，即创建连接器时命名的连接器实例名称。
约束限制：
不涉及。
取值范围：
不涉及。
默认取值：
不涉及。
object
是
String
参数解释：
上传文件到桶里的全路径，包含文件名、文件类型、上传到桶里的路径。不携带路径时，表示上传到桶的根目录下。
示例：取值为“a/b/c/test.mp4”，表示将文件“test.mp4”上传到桶的“a/b/c”路径下。如果桶中不存在该路径，会创建该路径。
约束限制：
不涉及。
取值范围：
不涉及。
默认取值：
不涉及。
uploadId
是
String
参数解释：
整个分段上传任务的标识，请从初始化分段上传任务的返回结果中获取该值。
约束限制：
不涉及。
取值范围：
不涉及。
默认取值：
不涉及。
- 请求参数
- 响应参数
表10 响应参数说明 参数
参数类型
描述
resCode
String
参数解释：
返回码。
取值范围：
如果返回“0”代表请求成功，其他错误码说明请参考错误码。
resMsg
String
参数解释：
返回消息。
取值范围：
如果成功状态，通常会返回“Success”，其他情况会返回具体的错误信息。
- 请求示例
已创建好OBS类型连接器，连接器实例名称为“命名空间__TestOBS”，需要向该OBS桶的“a/b/c”路径下上传大文件。已有初始化分段上传任务和分段上传任务，标识“uploadId”为“0000017B76500F0662CABA7128913936”，调用如下请求，取消该分段上传任务。
POST https://AstroZero域名/u-route/baas/sys/v1.1/connectors/obs/命名空间__TestOBS/abortupload?object=a/b/c/test3.mp4&uploadId=0000017B76500F0662CABA7128913936
- 响应示例
{ "resCode": "0", "resMsg": "成功" }
