Synchronously Uploading Incremental Objects
Function
This function synchronizes all content in the local source path to the specified target bucket on OBS, ensuring that the content is consistent between the local path and the target bucket. Incremental synchronization has the following meanings: (1) Increment: Compare the source file with the target object and upload only the source file that has changes. (2) Synchronization: After the command is executed, ensure that the local source path is a subset of the target bucket specified by OBS. That is, any file in the local source path has its corresponding object in the target bucket on OBS.
- Do not change the local file or folder during synchronization. Otherwise, the synchronization may fail or data may be inconsistent.
- Each file can be synchronously 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.
When you compare each local file with data in the bucket, a billable HEAD request is generated. For details, see Requests.
Command Line Structure
- In Windows
- Uploading a file synchronously
obsutil sync file_url obs://bucket[/key] [-arcDir=xxx] [-dryRun] [-link] [-vlength] [-vmd5] [-p=1] [-threshold=5248800] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-o=xxx] [-cpd=xxx] [-fr] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
- Uploading a folder synchronously
obsutil sync folder_url obs://bucket[/key] [-arcDir=xxx] [-dryRun] [-link] [-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] [-at] [-mf] [-o=xxx] [-cpd=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
- Uploading a file synchronously
- In Linux or macOS
- Uploading a file synchronously
./obsutil sync file_url obs://bucket[/key] [-arcDir=xxx] [-dryRun] [-link] [-vlength] [-vmd5] [-p=1] [-threshold=5248800] [-acl=xxx] [-sc=xxx] [-meta=aaa:bbb#ccc:ddd] [-ps=auto] [-o=xxx] [-cpd=xxx] [-fr] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
- Uploading a folder synchronously
./obsutil sync folder_url obs://bucket[/key] [-arcDir=xxx] [-dryRun] [-link] [-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] [-at] [-mf] [-o=xxx] [-cpd=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]
- Uploading a file synchronously
Examples
- Take the Windows OS as an example. Run the obsutil sync d:\temp\test.txt obs://bucket-test/key command to synchronously upload a file.
obsutil sync d:\temp\test.txt obs://bucket-test/key Parallel: 3 Jobs: 3 Threshold: 524288000 PartSize: 5242880 Exclude: Include: VerifyLength: false VerifyMd5: false CheckpointDir: xxxx [====================================================] 100.00% 1.68 MB/s 8.46MB/8.46MB 5s Upload successfully, 8.46MB, d:\temp\test.txt --> obs://bucket-test/key
- Take the Windows OS as an example. Run the obsutil sync d:\temp obs://bucket-test/temp command to synchronously upload a folder.
obsutil sync d:\temp obs://bucket-test/temp Parallel: 3 Jobs: 3 Threshold: 524288000 PartSize: 5242880 Exclude: Include: VerifyLength: false VerifyMd5: false CheckpointDir: xxxx Task id: 104786c8-27c2-48fc-bc6a-5886596fb0ed OutputDir: xxxx [========================================================] 100.00% tps:35.71 2.02 KB/s 7.20MB/7.20MB 0s Succeed count is: 5 Failed count is: 0 Metrics [max cost:90 ms, min cost:45 ms, average cost:63.80 ms, average tps:35.71] Task id: 104786c8-27c2-48fc-bc6a-5886596fb0ed
- For more examples, see Synchronous Upload.
Parameter Description
Parameter |
Optional or Mandatory |
Description |
---|---|---|
file_url |
Mandatory for uploading a file synchronously |
Local file path |
folder_url |
Mandatory for uploading a folder synchronously |
Local folder path |
bucket |
Mandatory |
Bucket name |
key |
Optional |
Indicates the object name or object name prefix specified when uploading a file synchronously, or the object name prefix specified when uploading a folder synchronously. The rules are as follows:
NOTE:
|
fr |
Optional for synchronously uploading a file (additional parameter) |
Generates an operation result list when synchronously uploading a file. |
arcDir |
Optional (additional parameter) |
Path to which the synchronously uploaded files are archived |
dryRun |
Optional (additional parameter) |
Conducts a dry run. |
link |
Optional (additional parameter) |
Uploads the actual path of the symbolic-link file/folder
NOTICE:
|
vlength |
Optional (additional parameter) |
After the synchronous upload is complete, 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 synchronous upload is complete, check whether the MD5 values of the objects in the bucket are the same as those of the local files.
NOTE:
|
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:
|
acl |
Optional (additional parameter) |
Access control policies that can be specified when synchronously uploading files. Possible values are:
NOTE:
The preceding four values indicate private read and write, public read, public read and write, and bucket owner full control. |
sc |
Optional (additional parameter) |
Indicates the storage classes of objects that can be specified when synchronously uploading files. Possible values are:
|
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:
|
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. |
j |
Optional for synchronously uploading a folder (additional parameter) |
Indicates the maximum number of concurrent tasks for uploading a folder synchronously. 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 for synchronously uploading a folder (additional parameter) |
Indicates the file matching patterns that are excluded, for example: *.txt.
NOTE:
NOTICE:
|
include |
Optional for synchronously uploading a folder (additional parameter) |
Indicates the file matching patterns that are included, for example: *.jpg.
NOTE:
NOTICE:
|
at |
Optional for synchronously uploading a folder (additional parameter) |
Indicates that when synchronously uploading a folder, only the files whose latest access time is within the value of timeRange are uploaded.
NOTE:
|
disableDirObject |
Optional for synchronously uploading folders (additional parameter) |
Indicates the folders themselves are not uploaded as an object. Configuring this parameter can avoid uploading empty folders to a bucket. If a folder contains files, the files will be uploaded and the original path format is retained. |
timeRange |
Optional for synchronously uploading a folder (additional parameter) |
Indicates the time range matching pattern when synchronously 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:
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 folders. |
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:
|
config |
Optional (additional parameter) |
User-defined configuration file for executing a command. For details about parameters that can be configured, see Parameter Description. |
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.
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.