This topic describes how to use resumable upload.

Background information

  • During resumable upload
    • When a resumable upload task fails, the uploaded parts become useless in OSS. You can configure lifecycle rules for a bucket to delete expired parts. For more information, see Manage lifecycle rules.
      Notice By default, if the current upload task is canceled, the parts uploaded to the server are deleted synchronously. If you want to retain resumable upload records, you must specify a folder to store the checkpoint file that contains the resumable upload records and modify the setting of the deleteUploadIdOnCancelling parameter. If resumable upload records are retained on the mobile device for an extended period of time but the parts uploaded to the server have been deleted by the configured lifecycle rules of the bucket, the resumable upload records on the server may be different from those on the mobile device.

Sample code

  • The following code provides an example on how to call the resumableUpload method to perform a resumable upload task when the checkpoint file is permanently stored in the local device:
    OSSResumableUploadRequest * resumableUpload = [OSSResumableUploadRequest new];
    resumableUpload.bucketName = OSS_BUCKET_PRIVATE;
    //...
    NSString *cachesDir = [NSSearchPathForDirectoriesInDomains(NSCachesDirectory, NSUserDomainMask, YES) firstObject];
    resumableUpload.recordDirectoryPath = cachesDir;
    					
    Note When a resumable upload task fails, a checkpoint file is generated to record the resumable upload progress. The next upload starts from the position recorded in the checkpoint file to upload the entire object. After the object is uploaded, the checkpoint file is automatically deleted. By default, the checkpoint file is not retained permanently on the local device.
  • The following code provides a complete example on how to perform a resumable upload task:
    // Obtain an upload ID to upload an object.
    OSSResumableUploadRequest * resumableUpload = [OSSResumableUploadRequest new];
    resumableUpload.bucketName = <bucketName>;
    // objectKey is equivalent to objectName that indicates the complete path of the object you want to upload to OSS by using resumable upload. The path must include the extension of the object. For example, you can set objectKey to abc/efg/123.jpg.
    resumableUpload.objectKey = <objectKey>;
    resumableUpload.partSize = 1024 * 1024;
    resumableUpload.uploadProgress = ^(int64_t bytesSent, int64_t totalByteSent, int64_t totalBytesExpectedToSend) {
        NSLog(@"%lld, %lld, %lld", bytesSent, totalByteSent, totalBytesExpectedToSend);
    };
    NSString *cachesDir = [NSSearchPathForDirectoriesInDomains(NSCachesDirectory, NSUserDomainMask, YES) firstObject];
    // Specify the path to store the checkpoint file.
    resumableUpload.recordDirectoryPath = cachesDir;
    // Set the deleteUploadOnCancelling parameter to NO. NO indicates that the checkpoint file is not deleted when the upload task fails. The next upload starts from the position recorded in the checkpoint file to upload the entire object. If you do not specify this parameter, default value YES is used. YES indicates that the checkpoint file is deleted when the upload task fails. The entire object is uploaded again during the next upload.
    resumableUpload.deleteUploadIdOnCancelling = NO;
    
    resumableUpload.uploadingFileURL = [NSURL fileURLWithPath:<your file path>];
    OSSTask * resumeTask = [client resumableUpload:resumableUpload];
    [resumeTask continueWithBlock:^id(OSSTask *task) {
        if (task.error) {
            NSLog(@"error: %@", task.error);
            if ([task.error.domain isEqualToString:OSSClientErrorDomain] && task.error.code == OSSClientErrorCodeCannotResumeUpload) {
                // The task cannot be resumed. You must obtain a new upload ID to upload the object.
            }
        } else {
            NSLog(@"Upload file success");
        }
        return nil;
    }];
    
    // [resumeTask waitUntilFinished];
    
    // [resumableUpload cancel];