# 异步断点续传上传 #### 功能介绍 异步断点续传上传是异步执行的断点续传上传，并且支持暂停、取消、继续等功能。其原理是创建一个子线程，在子线程中进行断点续传上传，上传失败产生异常时可以通过回调获取异常，上传成功时可以从task中获取Optional封装的结果。 ![](https://support.huaweicloud.com/sdk-android-devg-obs/public_sys-resources/notice_3.0-zh-cn.png) 开发过程中，您有任何问题可以在github上[提交issue](https://github.com/huaweicloud/huaweicloud-sdk-java-obs/issues)，或者在[华为云对象存储服务论坛](https://bbs.huaweicloud.com/forum/forum-620-1.html)中发帖求助。[接口参考文档](https://obssdk.obs.cn-north-1.myhuaweicloud.com/apidoc/cn/android/index.html)详细介绍了每个接口的参数和使用方法。 #### 接口约束 - 您必须是桶拥有者或拥有上传对象的权限，才能上传对象。建议使用IAM或桶策略进行授权，如果使用IAM则需授予obs:object:PutObject权限，如果使用桶策略则需授予PutObject权限。相关授权方式介绍可参见[OBS权限控制概述](https://support.huaweicloud.com/perms-cfg-obs/obs_40_0001.html)，配置方式详见[使用IAM自定义策略](https://support.huaweicloud.com/usermanual-obs/obs_03_0121.html)、[配置对象策略](https://support.huaweicloud.com/usermanual-obs/obs_03_0075.html)。 - OBS支持的region以及region与endPoint的对应关系，详细信息请参见[地区与终端节点](https://developer.huaweicloud.com/endpoint?OBS)。 - 断点续传上传接口传入的文件大小至少要100K以上。 - 使用SDK的断点续传接口时，必须开启断点续传选项后才能在进程再次进入时读取上一次上传的进度。 #### 方法定义 obsClientAsync.uploadFileAsync([UploadFileRequest] [request], TaskCallback\<[CompleteMultipartUploadResult], [UploadFileRequest]\> completeCallback) #### 请求参数说明 表1uploadFile请求参数 | **参数** | **类型** | **是否必选** | **描述** | |:---|:---|:---|:---| | request | [UploadFileRequest] | 是 | **参数解释** **：** 上传对象请求参数，详见[UploadFileRequest]。 | | completeCallback | [TaskCallback] \<[CompleteMultipartUploadResult], [UploadFileRequest]\> | 是 | **参数解释** **：** 异步上传时，用于获取上传结果和异常的回调。 | 表2UploadFileRequest | **参数** | **类型** | **是否必选** | **描述** | |:---|:---|:---|:---| | bucketName | String | 必选 | **参数解释** **：** 桶名。 **约束限制：** - 桶的名字需全局唯一，不能与已有的任何桶名称重复，包括其他用户创建的桶。 - 桶命名规则如下： - 3～63个字符，数字或字母开头，支持小写字母、数字、"-"、"."。 - 禁止使用IP地址。 - 禁止以"-"或"."开头及结尾。 - 禁止两个"."相邻（如："my..bucket"）。 - 禁止"."和"-"相邻（如："my-.bucket"和"my.-bucket"）。 - 同一用户在同一个区域多次创建同名桶不会报错，创建的桶属性以第一次请求为准。 **默认取值：** 无 | | objectKey | String | 必选 | **参数解释：** 对象名。对象名是对象在存储桶中的唯一标识。对象名是对象在桶中的完整路径，路径中不包含桶名。 例如，您对象的访问地址为examplebucket.obs.cn-north-4.myhuaweicloud.com/folder/test.txt，对象名为folder/test.txt。 **取值范围：** 长度大于0且不超过1024的字符串。 **默认取值：** 无 | | objectMetadata | ObjectMetadata | 可选 | **参数解释：** 对象元数据，详见[ObjectMetadata](https://support.huaweicloud.com/sdk-java-devg-obs/obs_21_0611.html#obs_21_0611__table137372322512)。 **默认取值：** 无 | | acl | AccessControlList | 可选 | **参数解释** **：** 创桶时可指定桶的ACL，您可以使用预定义的ACL，也可以自定义ACL，有关访问控制列表（Access Control List，ACL）功能的详细信息可参见[ACL功能介绍](https://support.huaweicloud.com/perms-cfg-obs/obs_40_0005.html)。 **取值范围：** - 如果使用预定义ACL，则可选配置项参见[ACL预定义访问策略](https://support.huaweicloud.com/sdk-java-devg-obs/obs_21_0611.html#obs_21_0611__table1248494120558)。 - 如果选择自定义ACL，则可以根据[AccessControlList](https://support.huaweicloud.com/sdk-java-devg-obs/obs_21_0611.html#obs_21_0611__table3131153615508)参数描述，自行给参数赋值。 **默认取值：** AccessControlList.REST_CANNED_PRIVATE | | sseKmsHeader | SseKmsHeader | 可选 | **参数解释：** 服务端加密头信息。详见[SseKmsHeader](https://support.huaweicloud.com/sdk-java-devg-obs/obs_21_0611.html#obs_21_0611__table4723393474)。 **默认取值：** 无 | | sseCHeader | SseCHeader | 可选 | **参数解释：** 服务端加密头信息。详见[SseCHeader](https://support.huaweicloud.com/sdk-java-devg-obs/obs_21_0611.html#obs_21_0611__table1386064771811)。 **默认取值：** 无 | | enableCheckpoint | boolean | 可选 | **参数解释：** 是否开启断点续传模式。 **取值范围：** true：开启断点续传模式。 false：关闭断点续传模式。 **默认取值：** false | | checkpointFile | String | 可选 | **参数解释：** 断点续传过程中，会生成一个进度记录文件，文件中会记录段的上传进度和段的相关信息。checkpointFile参数为该记录文件的文件路径。 **约束限制：** 仅在断点续传模式下有效。 **默认取值：** 当该值为空时，默认为待上传的本地文件的同级目录。 | | uploadFile | String | 必选 | **参数解释：** 待上传文件或文件夹的完整路径，如aa/bb.txt，或aa/。 **默认取值：** 无 | | extensionPermissionMap | Map\\> | 可选 | **参数解释：** 桶ACL的授权Map，您可以为一个或多个账号授予桶权限。Map的[ExtensionObjectPermissionEnum](https://support.huaweicloud.com/sdk-java-devg-obs/obs_21_0611.html#obs_21_0611__table1180612441263)用于指定权限，Map的Set\用于说明该权限授予的账号ID列表，即domain_id列表。 **取值范围：** - 授予权限的范围详见[ExtensionObjectPermissionEnum](https://support.huaweicloud.com/sdk-java-devg-obs/obs_21_0611.html#obs_21_0611__table1180612441263)。 - 如何获取账号ID请参见[如何获取账号ID和用户ID?](https://support.huaweicloud.com/sdk-java-devg-obs/obs_23_1712.html) **默认取值：** 无 | | progressListener | ProgressListener | 可选 | **参数解释：** 设置数据传输监听器，用于获取上传进度。详见[ProgressListener](https://support.huaweicloud.com/sdk-java-devg-obs/obs_21_0611.html#obs_21_0611__table134092034114420)。 | | partSize | long | 可选 | **参数解释：** 分段大小。 **取值范围：** 100KB\~5GB，单位：字节。 **默认取值：** 9MB | | taskNum | int | 可选 | **参数解释：** 分段上传时的最大并发数。 **取值范围：** 1\~10000，单位：个。 **默认取值：** 1，即不设置则默认单任务上传。 | | encodeHeaders | boolean | 可选 | **参数解释：** 是否开启OBS对请求头域的自动编码。 由于HTTP编码规范限制，无法发送非ASCII码字符，SDK会在发送请求时对您头域中的**中文汉字**进行url编码，发送编码后数据。如您设置的值content-disposition为attachment; filename="中文.txt"，则对象元数据中存储的信息为attachment; filename="%E4%B8%AD%E6%96%87.txt"。使用浏览器访问时浏览器将会自动解码。 **取值范围：** true：启用SDK编码。 false：不启用SDK编码。 **默认取值：** true | | needCalculateCRC64 | boolean | 可选 | **参数解释：** 是否自动计算待上传数据的crc64值并提交服务端校验。 **约束限制：** 不支持POSIX、SFS对象。 **取值范围：** true：表示由SDK计算crc64并提交服务端校验。 false：不检验crc64。 **默认取值：** false | 表3TaskCallback\泛型接口 | **方法名称** | **返回值** | **参数类型** | **描述** | |:---|:---|:---|:---| | onSuccess | void | result（泛型） | 成功时执行的回调，参数是请求成功的结果。 | | onException | void | [ObsException](https://support.huaweicloud.com/sdk-java-devg-obs/obs_21_2005.html), request（泛型） | 异常时执行的回调，参数是捕获的异常和出现异常的请求。 | #### 返回结果说明 表4UploadFileTask | **方法名称** | **返回值** | **参数类型** | **描述** | |:---|:---|:---|:---| | isTaskFinished | boolean | 无 | 判断任务是否执行完毕 | | waitUntilFinished | void | 无 | 阻塞当前线程，等待异步上传任务结束 | | cancel | boolean | 无 | 取消异步上传任务，返回true时执行取消成功，false说明执行失败 | | getResult | java.util.Optional \<[CompleteMultipartUploadResult]\> | 无 | 阻塞当前线程，等待异步上传任务结束，然后返回任务执行结果, 上传失败时Optional.isPresent()为false | 表5CompleteMultipartUploadResult | **参数名称** | **参数类型** | **描述** | |:---|:---|:---| | statusCode | int | **参数解释：** HTTP状态码。 **取值范围：** 状态码是一组从2xx（成功）到4xx或5xx（错误）的数字代码，状态码表示了请求响应的状态。 完整的状态码列表请参见[状态码](https://support.huaweicloud.com/api-obs/obs_04_0114.html)。 **默认取值：** 无 | | responseHeaders | Map\ | **参数解释：** 响应消息头列表，由多个元组构成。元组中String代表响应消息头的名称，Object代表响应消息头的值。 **默认取值：** 无 | | bucketName | String | **参数解释** **：** 桶名。 **约束限制：** - 桶的名字需全局唯一，不能与已有的任何桶名称重复，包括其他用户创建的桶。 - 桶命名规则如下： - 3～63个字符，数字或字母开头，支持小写字母、数字、"-"、"."。 - 禁止使用IP地址。 - 禁止以"-"或"."开头及结尾。 - 禁止两个"."相邻（如："my..bucket"）。 - 禁止"."和"-"相邻（如："my-.bucket"和"my.-bucket"）。 - 同一用户在同一个区域多次创建同名桶不会报错，创建的桶属性以第一次请求为准。 **默认取值：** 无 | | objectKey | String | **参数解释：** 对象名。对象名是对象在存储桶中的唯一标识。对象名是对象在桶中的完整路径，路径中不包含桶名。 例如，您对象的访问地址为examplebucket.obs.cn-north-4.myhuaweicloud.com/folder/test.txt，对象名为folder/test.txt。 **取值范围：** 长度大于0且不超过1024的字符串。 **默认取值：** 无 | | etag | String | **参数解释：** 对象的etag值，即Base64编码的128位MD5摘要。etag是对象内容的唯一标识，可以通过该值识别对象内容是否有变化。比如上传对象时etag为A，下载对象时etag为B，则说明对象内容发生了变化。etag只反映变化的内容，而不是其元数据。上传的对象或拷贝操作创建的对象，都有唯一的etag。 **约束限制：** 当对象是服务端加密的对象时，etag值不是对象的MD5值。 **取值范围：** 长度为32的字符串。 **默认取值：** 无 | | versionId | String | **参数解释：** 对象的版本号。如果桶的多版本状态为开启，则会返回对象的版本号。 **取值范围：** 长度为32的字符串。 **默认取值：** 无 | #### 代码示例 ![](https://support.huaweicloud.com/sdk-android-devg-obs/public_sys-resources/note_3.0-zh-cn.png) - 断点续传上传接口是利用[分段上传](https://support.huaweicloud.com/sdk-android-devg-obs/obs_26_0407.html)特性实现的，是对分段上传的封装和加强。 - 断点续传上传接口不仅能在失败重传时节省资源提高效率，还因其对分段进行并发上传的机制能加快上传速度，帮助用户快速完成上传业务；且其对用户透明，用户不用关心checkpoint文件的创建和删除、分段任务的切分、并发上传的实现等内部细节。 - **enableCheckpoint** **参数**默认是false，代表不启用断点续传模式，此时断点续传上传接口退化成对分段上传的简单封装，不会产生checkpoint文件。 - **checkpointFile** **参数** 和**enableCheckSum参数** 仅在**enableCheckpoint参数**为true时有效。 - 由于 HTTP 编码规范限制，无法发送非 ASCII 码字符，SDK 会在发送请求时对您头域中的**中文汉字**进行 url 编码，发送编码后数据。如您设置的值 content-disposition 为 "attachment; filename="中文.txt""，则对象元数据中存储的信息为"attachment; filename="%E4%B8%AD%E6%96%87.txt""。使用浏览器访问时浏览器将会自动解码。 - 如果不需要 SDK 帮您编码，可以调用 UploadFileRequest.setIsEncodeHeaders(false) 关闭自动编码。 - 断点续传上传功能暂不支持暂停或取消操作。