分段上传

初始化分段上传任务

• 功能介绍

  使用分段上传方式传输数据前，必须先创建一个初始化分段上传任务。该操作会返回一个该任务的全局唯一标识（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	分段号，取值范围为1~10000。 对于同一个分段上传任务（即uploadId相同），分段号“partNumber”不但唯一标识这一段数据，也标识了这段数据在整个对象文件内的相对位置。

• 请求参数

  请求中的body类型，按照“application/octet-stream”格式上传文件分段内容。

• 响应参数

  表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	整个分段上传任务的标识，从初始化分段上传任务的返回结果中获取该值。

• 请求参数
  数组类型，每个元素中包含如表7所示字段。

  表7 请求参数说明

  参数	是否必选	参数类型	描述
  ETag	是	String	文件分段的标识。从上传分段的返回结果中获取该值。
  partNumber	是	String	分段号。 对于同一个分段上传任务（即uploadId相同），分段号“partNumber”不但唯一标识这一段数据，也标识了这段数据在整个对象文件内的相对位置，从上传分段的返回结果中获取该值。

• 响应参数

  表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": "成功"
  }