Object Storage Service:Resumable upload

Background information

We recommend that you do not use resumable upload when you upload objects that are smaller than 5 GB in size from a mobile device. Resumable upload is implemented by using the multipart upload feature. Resumable upload of a single object requires multiple network requests, which is inefficient. When you upload an object that is larger than 5 GB in size by performing resumable upload, take note of the following items:

• Before resumable upload

  Before you upload an object to OSS by performing resumable upload, you can specify a directory for the checkpoint file that stores the resumable upload progress. The checkpoint file applies only to the current resumable upload task.

  • If you do not specify the directory for the checkpoint file and a part of a large object fails to be uploaded due to network issues, a long period of time is required and a large amount of traffic is consumed to re-upload the entire object.

  • If you specify the directory for the checkpoint file, a failed resumable upload task can be resumed from the position recorded in the checkpoint file.

• During resumable upload

  • Resumable upload allows you to upload only local files. Resumable upload supports the upload callback feature, which is used in the same manner as in common upload tasks. For more information, see Callback.

  • You can perform resumable upload by calling the following API operations: InitMultipartUpload, UploadPart, ListParts, CompleteMultipartUpload, and AbortMultipartUpload. If you want to perform resumable upload by using Security Token Service (STS), make sure that you are authorized to call the preceding API operations.

  • By default, the MD5 hash of each part is verified in a resumable upload task. Therefore, you do not need to specify the Content-Md5 header in the request.

  • If a resumable upload task fails and is not resumed for an extended period of time, the uploaded parts may become useless in OSS. You can configure lifecycle rules for a bucket to delete expired parts. For more information, see Configure lifecycle rules.

    Important

    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.

Usage notes

• Before you run the sample code in this topic, you must create an OSSClient instance by using methods such as using a custom domain name or Security Token Service (STS). For more information, see Initialization.

  Note

  The region of the bucket is determined by the endpoint specified for initialization.

• To upload an object, you must have the oss:PutObject permission. For more information, see Attach a custom policy to a RAM user.

Examples

• 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 on 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 until the entire object is uploaded. 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 an example on how to perform a resumable upload task:

  // Obtain an upload ID to upload the object. 
  OSSResumableUploadRequest * resumableUpload = [OSSResumableUploadRequest new];
  resumableUpload.bucketName = <bucketName>;
  // objectKey is equivalent to objectName that indicates the full path of the object you want to upload to OSS by using resumable upload. The path must include the extension of the object name. 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 deleteUploadIdOnCancelling 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 until the entire object is uploaded. 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];