doc-exports/docs/obs/tool-obsutil/obs_11_0043.html

Synchronously Downloading Incremental Objects

Function

You can use this command to synchronize all objects in a specified path of the source OBS bucket to a target local path to ensure data consistency. Incremental synchronization has the following meanings:

• "Incremental" means that the source objects are compared with their counterparts in the target local path and only the source objects with content changes are downloaded.
• "Synchronous" means that after the command is executed, all objects in the specified path of the source OBS bucket have their counterparts in the target local path.

• Do not change the source objects in the OBS bucket when synchronously downloading objects. Otherwise, the synchronization may fail or data may be inconsistent.
• Each object can be synchronously downloaded only when it does not exist in the local path, its size is different from the namesake one in the local path, or it has the latest modification time.
• A single file cannot be downloaded synchronously. Only folders can be downloaded synchronously.

Command Line Structure

• Windows

  obsutil sync obs://bucket[/key] folder_url [-tempFileDir=xxx] [-dryRun] [-vlength] [-vmd5] [-j=1] [-p=1] [-threshold=52428800] [-ps=auto] [-include=*.xxx] [-exclude=*.xxx] [-timeRange=time1-time2] [-mf] [-o=xxx] [-cpd=xxx] [-config=xxx] 

• macOS or Linux

  ./obsutil sync obs://bucket[/key] folder_url [-tempFileDir=xxx] [-dryRun] [-vlength] [-vmd5] [-j=1] [-p=1] [-threshold=52428800] [-ps=auto] [-include=*.xxx] [-exclude=*.xxx] [-timeRange=time1-time2] [-mf] [-o=xxx] [-cpd=xxx] [-config=xxx] 

Examples

• In Windows, run obsutil sync obs://bucket-test/temp d:\temp to download objects synchronously.

  obsutil sync obs://bucket-test/temp d:\temp
  Start at 2024-09-30 08:53:22.327072 +0000 UTC
  
  Parallel:      5                   Jobs:          5
  Threshold:     50.00MB             PartSize:      auto
  VerifyLength:  false               VerifyMd5:     false
  CheckpointDir: xxxx
  
  Task id: 3066a4b0-4d21-4929-bb84-4829c32cbd0f
  OutputDir: xxxx
  TempFileDir: xxxx
  
  [======================================================] 100.00% tps:17.86 155.59 KB/s 7.20MB/7.20MB 0s
  Succeed count:   6         Failed count:    0
  Succeed bytes:    xxxx
  Metrics [max cost:153 ms, min cost:129 ms, average cost:92.00 ms, average tps:17.86, transferred size: 7.20MB]
  
  Task id: 3066a4b0-4d21-4929-bb84-4829c32cbd0f

• For more examples, see Common Examples.

Parameter Description

Parameter	Optional or Mandatory	Description
folder_url	Mandatory	The local folder path
bucket	Mandatory	The bucket name
key	Optional	The name prefix of objects to be synchronously downloaded The rules are as follows: If this parameter is left blank, all files in the folder specified by folder_url are the same as all objects in the bucket. If this parameter is configured, all files in the folder specified by folder_url are the same as the objects whose name prefix is the configured value in the bucket. NOTE: If the value of this parameter does not end with a slash (/), the obsutil tool automatically adds a slash (/) at the end of the configured value as the object name prefix. For details about how to use this parameter, see Synchronous Download.
tempFileDir	Optional (additional parameter)	The directory for storing temporary files during synchronous download. The default value is the value of defaultTempFileDir in the configuration file. NOTE: Temporary files generated during multipart download are stored in this directory. Therefore, ensure that the user who executes obsutil has the write permission on the path. The available space of the partition where the path is located must be greater than the size of the objects to be downloaded.
dryRun	Optional (additional parameter)	Conducts a dry run.
vlength	Optional (additional parameter)	Checks whether the sizes of the local files are the same as those of the objects in the bucket after the download is complete.
vmd5	Optional (additional parameter)	Checks whether MD5 values of the local files are the same as those of the objects in the bucket after the download is complete. NOTE: Objects in the bucket must contain metadata x-obs-meta-md5chksum, or MD5 verification will be skipped. CAUTION: If your object needs encryption, do not use this parameter.
p	Optional (additional parameter)	The maximum number of concurrent multipart download tasks when downloading an object. The default value is the value of defaultParallels in the configuration file.
threshold	Optional (additional parameter)	The threshold for enabling multipart download, in bytes. The default value is the value of defaultBigfileThreshold in the configuration file. NOTE: If the size of the object to be downloaded is smaller than the threshold, download the object directly. If not, a multipart download is required. If you download an object directly, no part record is generated, and resumable transmission is not supported. This parameter value can contain a unit, for example, 1MB (indicating 1,048,576 bytes).
ps	Optional (additional parameter)	The size of each part in a multipart download task, in bytes. The default value is the value of defaultPartSize in the configuration file. NOTE: This parameter value can contain a unit, for example, 1MB (indicating 1,048,576 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 object size.
cpd	Optional (additional parameter)	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 download and saved to the down subfolder. After the download succeeds, its part record is deleted automatically. If the download fails or is suspended, the system attempts to resume the task according to its part record when you perform the download the next time.
j	Optional for downloading objects in batches (additional parameter)	The maximum number of concurrent tasks for downloading objects synchronously. The default value is the value of defaultJobs in the configuration file. NOTE: The tool ensures that this value is at least 1.
exclude	Optional for downloading objects in batches (additional parameter)	The matching patterns of source objects 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 object to be downloaded matches the value of this parameter, the object 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 double quotation marks for Windows. The matching pattern applies to the object's absolute path, which includes the object name prefix and the object name starting from the root directory. For example, if an object's path in the bucket is obs://bucket/src1/src2/test.txt, its absolute path is src1/src2/test.txt. This matching pattern applies only to objects whose names do not end with a slash (/). Multiple exclude parameters can be specified, for example, -exclude=*.xxx -exclude=*.xxx.
include	Optional for downloading objects in batches (additional parameter)	The matching patterns of source objects 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 ?. The exclude rule is applied first. If the name of the object to be downloaded does not match the exclude rule, the system then checks whether the object name matches this parameter. If it does, the object is downloaded; if it does not, the object 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 double quotation marks for Windows. The matching pattern applies to the object's absolute path, which includes the object name prefix and the object name starting from the root directory. For example, if an object's path in the bucket is obs://bucket/src1/src2/test.txt, its absolute path is src1/src2/test.txt. This matching pattern applies only to objects whose names do not end with a slash (/). Multiple include parameters can be specified, for example, -include=*.xxx -include=*.xxx.
timeRange	Optional (additional parameter)	The time range matching pattern when synchronously downloading objects. Only objects whose latest modification time is within the configured time range are downloaded. This pattern has a lower priority than the object matching patterns (exclude/include). That is, the time range matching pattern is executed after the configured object 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 last modification time is earlier than time2 are matched. If it is set to time1-*, all files whose last modification time is later than time1 are matched. NOTICE: Time in the matching pattern is the UTC time. This matching pattern applies only to objects whose names do not end with a slash (/).
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)	The folder that stores the result files. After the command is executed, result files (possibly success, failure, and warning files) will be created in the specified folder. The default value is .obsutil_output, a subfolder in the user's home directory where obsutil commands are executed. NOTE: A result file should be named as follows: sync_{succeed | failed | warning}_report_time_TaskId.txt. By default, the maximum size of a single result file is 30 MB and the maximum number of result files that can be retained is 1,024. 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 details of a failed task, refer to the failure result file cp_failed_report_time_TaskId.txt in the result folder and the log files in the log path.
config	Optional (additional parameter)	The user-defined configuration file for executing the current command. For details about parameters that can be configured, see Configuration Parameters.

Response

Refer to Response for uploading an object.

Parent topic: Object Commands