Help Center/ Object Storage Service/ Tools Guide/ obsutil/ Object Commands/ Resuming a Failed Upload Task
Updated on 2024-12-11 GMT+08:00
View PDF
Share

Resuming a Failed Upload Task

Function

You can use this command to resume a failed upload task based on the task ID.

Command Line Structure

  • In Windows 
    obsutil cp -recover=xxx [-arcDir=xxx] [-dryRun] [-f] [-u] [-vlength] [-vmd5] [-j=1] [-p=1] [-threshold=52428800] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-include=*.xxx] [-exclude=*.xxx] [-timeRange=time1-time2] [-mf] [-o=xxx] [-cpd=xxx] [-clear] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
  • In Linux or macOS 
    ./obsutil cp -recover=xxx [-arcDir=xxx] [-dryRun] [-f] [-u] [-vlength] [-vmd5] [-j=1] [-p=1] [-threshold=52428800] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-include=*.xxx] [-exclude=*.xxx] [-timeRange=time1-time2] [-mf] [-o=xxx] [-cpd=xxx] [-clear] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

Examples

  • Take the Windows OS as an example. Run the obsutil cp -recover 104786c8-27c2-48fc-bc6a-5886596fb0ed -f command to resume the failed upload task. 
    obsutil cp -recover 104786c8-27c2-48fc-bc6a-5886596fb0ed -f
Start at 2024-10-08 01:10:07.3809685 +0000 UTC

Parallel:      5                   Jobs:          5
Threshold:     50.00MB             PartSize:      auto
VerifyLength:  false               VerifyMd5:     false
CheckpointDir: xxxx

Task id: a628d6da-c562-4a1f-b687-4fa125de0dc3
OutputDir: xxxx
TempFileDir: xxxx

[========================================================] 100.00% tps:35.71 2.02 KB/s 7.20MB/7.20MB 0s
Succeed count:      1         Failed count:       0
Succeed bytes:      xxx
Metrics [max cost:90 ms, min cost:45 ms, average cost:63.80 ms, average tps:35.71, transfered size:70B]

Task id: a628d6da-c562-4a1f-b687-4fa125de0dc3

Parameter Description

Parameter

Optional or Mandatory

Description

recover

Mandatory (additional parameter)

ID of the upload task to be resumed

NOTE:
  • You can obtain the task ID after an upload task is complete, or query it based on the name of the result list. A task ID is the 36 characters, excluding the suffix .txt.
  • You can locate the upload task to be resumed in the directory where the result lists reside. For details about the directory of the result lists, see additional parameter o.

arcDir

Optional (additional parameter)

Path to which the uploaded files are archived

dryRun

Optional (additional parameter)

Conducts a dry run.

u

Optional (additional parameter)

Indicates incremental upload. If this parameter is set, each file can be uploaded only when it does not exist in the bucket, its size is different from the namesake one in the bucket, or it has the latest modification time.

CAUTION:

When you compare each local file with data in the bucket, a billable HEAD request is generated. For details, see Requests.

vlength

Optional (additional parameter)

After the upload completes, check whether the sizes of the objects in the bucket are the same as those of the local files.

vmd5

Optional (additional parameter)

After the upload completes, check whether the MD5 values of the objects in the bucket are the same as those of the local files.

NOTE:
  • If the size of the file or folder to be uploaded is too large, using this parameter will degrade the overall performance due to MD5 calculation.
  • After the MD5 verification is successful, this parameter value is used for metadata x-obs-meta-md5chksum, for later MD5 verification during download or copy.
CAUTION:

If your object needs encryption, do not use this parameter.

p

Optional (additional parameter)

Indicates the maximum number of concurrent multipart upload tasks when uploading a file. The default value is the value of defaultParallels in the configuration file.

threshold

Optional (additional parameter)

Indicates the threshold for enabling multipart upload, in bytes. The default value is the value of defaultBigfileThreshold in the configuration file.

NOTE:
  • If the size of the file or folder to be uploaded is smaller than the threshold, upload it directly. Otherwise, a multipart upload is required.
  • If you upload a file or folder directly, no part record is generated, and resumable transmission is not supported.
  • This parameter value can contain a unit, for example, 1MB (indicating 1048576 bytes).

acl

Optional (additional parameter)

Access control policies that can be specified when uploading files. Possible values are:

  • private
  • public-read
  • public-read-write
NOTE:

The preceding three values indicate private read and write, public read, and public read and write.

sc

Optional (additional parameter)

Indicates the storage classes of objects that can be specified when uploading files. Possible values are:

  • standard: Standard storage class. It features low access latency and high throughput, and is applicable to storing frequently accessed data (multiple accesses per month) or data that is smaller than 1 MB.
  • warm: Infrequent Access storage class. It is ideal for storing infrequently accessed (less than 12 times a year) data, but when needed, the access has to be fast.
  • cold: Archive storage class. It provides secure, durable, and inexpensive storage for rarely-accessed (once a year) data.

meta

Optional (additional parameter)

Indicates the customized metadata that can be specified when uploading files. The format is key1:value1#key2:value2#key3:value3.

NOTE:

The preceding value indicates that the object in the bucket contains three groups of customized metadata after the file is uploaded: key1:value1, key2:value2, and key3:value3.

ps

Optional (additional parameter)

Indicates the size of each part in a multipart upload task, in bytes. The value ranges from 100KB to 5GB. The default value is the value of defaultPartSize in the configuration file.

NOTE:
  • This parameter value can contain a unit, for example, 1MB (indicating 1048576 bytes).
  • The parameter can be set to auto. In this case, obsutil automatically sets the part size for each multipart task based on the source file size.

cpd

Optional (additional parameter)

Indicates the folder where the part records reside. The default value is .obsutil_checkpoint, the subfolder in the home directory of the user who executes obsutil commands.

NOTE:

A part record is generated during a multipart upload and saved to the upload subfolder. After the upload succeeds, its part record is deleted automatically. If the upload fails or is suspended, the system attempts to resume the task according to its part record when you perform the upload the next time.

f

Optional (additional parameter)

Runs in force mode.

j

Optional (additional parameter)

Maximum number of concurrent tasks for uploading a folder. The default value is the value of defaultJobs in the configuration file.

NOTE:

The value is ensured to be greater than or equal to 1.

exclude

Optional (additional parameter)

Indicates the file matching patterns that are excluded, for example: *.txt.

NOTE:
  • The asterisk (*) represents any group of characters, and the question mark (?) represents any single character. For instance, abc*.txt indicates any file whose name starts with abc and ends with .txt.
  • You can use \* to represent * and \? to represent ?.
  • If the name of the file to be uploaded matches the value of this parameter, the file is skipped.
NOTICE:
  • You are advised to use quotation marks for the matching pattern to prevent special characters from being escaped by the OS and leading to unexpected results. Use single quotation marks for Linux or macOS and quotation marks for Windows.
  • The matching pattern applies to the absolute file path (including the file name and file directory).
  • The matching pattern applies only to files in a folder.
  • Multiple exclude parameters can be specified, for example, -exclude=*.xxx -exclude=*.xxx.

include

Optional (additional parameter)

Indicates the file matching patterns that are included, for example: *.jpg.

NOTE:
  • The asterisk (*) represents any group of characters, and the question mark (?) represents any single character.
  • You can use ** to represent * and \? to represent ?.
  • Only after identifying that the name of the file to be uploaded does not match the value of exclude, the system checks whether the file name matches the value of this parameter. If yes, the file is uploaded. If not, the file is skipped.
NOTICE:
  • You are advised to use quotation marks for the matching pattern to prevent special characters from being escaped by the OS and leading to unexpected results. Use single quotation marks for Linux or macOS and quotation marks for Windows.
  • The matching pattern applies to the absolute file path (including the file name and file directory).
  • The matching pattern applies only to files in a folder.
  • Multiple include parameters can be specified, for example, -include=*.xxx -include=*.xxx.

at

Optional (additional parameter)

Indicates that when resuming a failed upload task, only the files whose latest access time is within the value of timeRange are uploaded.

NOTE:
  • This parameter must be used together with timeRange.

timeRange

Optional (additional parameter)

Indicates the time range matching pattern when uploading files. Only files whose latest modification time is within the configured time range are uploaded.

This pattern has a lower priority than the file matching patterns (exclude/include). That is, the time range matching pattern is executed after the configured file matching patterns.

NOTE:
  • The matching time range is represented in time1-time2, where time1 must be earlier than or the same as time2. The time format is yyyyMMddHHmmss.
  • Automatic formatting is supported. For example, yyyyMMdd is equivalent to yyyyMMdd000000, and yyyyMM is equivalent to yyyyMM01000000.
  • If this parameter is set to *-time2, all files whose latest modification time is earlier than time2 are matched. If it is set to time1-*, all files whose latest modification time is later than time1 are matched.
NOTICE:

Time in the matching pattern is the UTC time.

mf

Optional (additional parameter)

Indicates that the name matching pattern (include or exclude) and the time matching pattern (timeRange) also take effect on objects whose names end with a slash (/).

o

Optional (additional parameter)

Indicates the folder where operation result lists reside. After the command is executed, result lists (possibly including success, failure, and warning files) are generated in the folder. The default value is .obsutil_output, the subfolder in the home directory of the user who executes obsutil commands.

NOTE:
  • The naming rule for result lists is as follows: cp_{succeed | failed | warning}_report_time_TaskId.txt.

    By default, the maximum size of a single result list is 30 MB and the maximum number of result lists that can be retained is 1024. You can set the maximum size and number by configuring recordMaxLogSize and recordBackups in the configuration file.

  • If there are multiple folders and files and you need to confirm the detailed error information about a failed task, refer to the failure list cp_failed_report_time_TaskId.txt in the result list folder and the log files in the log path.

clear

Optional (additional parameter)

Deletes the failure result files after the upload task is resumed.

config

Optional (additional parameter)

User-defined configuration file for executing the current command. To learn the parameters that can be configured in this file, see Configuration Parameters.

e

Optional (additional parameter)

Specifies the endpoint.

i

Optional (additional parameter)

Specifies the user's AK.

k

Optional (additional parameter)

Specifies the user's SK.

t

Optional (additional parameter)

Specifies the user's security token.

Response

Refer to Response for uploading an object.

Parent topic: Object Commands