Object Storage Service:Synchronize OSS objects to your local computer

Usage notes

• To synchronize objects from OSS to your computer, you must have the oss:GetObject and oss:ListObjects permissions. For more information, see Attach a custom policy to a RAM user.

• Binary name

  For ossutil 1.6.16 and later, you can directly use ossutil as the binary name in the command line. You do not need to update the binary name based on the operating system. For ossutil earlier than 1.6.16, you need to update the binary name based on the operating system. For more information, see ossutil command reference.

• Number of local files to synchronize

  When you run the sync command without including the --delete option, no limit is imposed on the number of local files that you can synchronize at a time. If you include the --delete option when you run the sync command, you can synchronize up to 1 million local files at a time. If the number of local files that you want to synchronize exceeds 1 million, the over max sync numbers 1000000. error message is returned.

• Differences between the sync and cp commands

  • The sync command recursively synchronizes all objects and subdirectories in a specific directory. The cp command recursively synchronizes objects only if the -r option is specified.

  • The sync command supports the --backup-dir option. When you run the sync command to synchronize data to OSS, you can specify this option in the command to specify a directory in OSS to store objects that exist in the destination but do not exist in the source. The cp command does not support the --backup-dir option.

  • The sync command does not support the --version-id option. Therefore, the sync command cannot be used to synchronize previous versions of objects in versioned buckets. The cp command supports the --version-id option.

  Except for the preceding differences, you can use the sync and cp commands in a similar manner. For more information about how to run the cp command, see Download objects.

Command syntax

ossutil sync cloud_url  file_url
[-f --force]
[-u --update]
[--maxdownspeed <value>]
[--delete]
[--backup-dir <value>]
[--enable-symlink-dir]
[--disable-all-symlink]
[--disable-ignore-error]
[--only-current-dir]
[--output-dir <value>]
[--bigfile-threshold <value>]
[--part-size <value>]
[--checkpoint-dir <value>]
[--range <value>]
[--encoding-type <value>]
[--snapshot-path <value>]
[--include <value>]
[--exclude <value>]
[--disable-crc64]
[--payer <value>]
[-j, --job <value>]
[--parallel <value>]
[--retry-times <value>]

The following table describes the parameters and options in the command syntax.

Examples

The localdir directory of a bucket named examplebucket contains objects a.txt and b.txt and a subdirectory named C. A local file named d.txt is stored in the destdir directory of the local root directory. The following structure shows the files and directories in your computer and OSS before synchronization:

examplebucket           Local root directory
└── localdir/             └── destdir/
       ├── a.txt                └── d.txt
       ├── b.txt
       └── C/

• Synchronize the localdir directory from examplebucket to your computer.

  ossutil sync  oss://examplebucket/localdir/  destdir/ 

  After you run the preceding command, the a.txt and b.txt objects and the C directory are added to the destfolder directory of your computer. The following structure shows the files and directories in your computer and OSS after synchronization:

  examplebucket           Local root directory
  └── localdir/             └── destdir/
         ├── a.txt                ├── a.txt 
         ├── b.txt                ├── b.txt
         └── C/                   ├── d.txt
                                     └── C/

• Synchronize the localdir directory of the examplebucket bucket to a local directory named destdir. The --backup-dir option is set to a directory named backup in the command to store objects that exist in the destdir directory but do not exist in the localdir directory. These objects are deleted from the destdir directory.

  ossutil sync oss://examplebucket/localdir/  destdir/  --delete  --backup-dir backup/

  After you run the command, the localdir directory of the examplebucket bucket is synchronized to the destdir directory in your computer. Objects that exist in the destdir directory and do not exist in the localdir directory are moved to the backup directory. Only the synchronized objects named a.txt and b.txt and the subdirectory named C are stored in the destdir directory after synchronization. The d.txt object that exists in the destdir directory before synchronization is moved to the backup directory. The following structure shows the files and directories in your computer and OSS after synchronization by specifying the backup directory:

  examplebucket              Local root directory
  └── localdir/               ├── destdir/
         ├── a.txt            │     ├── a.txt 
         ├── b.txt            │     ├── b.txt
         └── C/               │     └── C/                             
                                 └── backup/
                                        └──d.txt

• If the preceding commands are run successfully, output similar to the following content is returned to indicate the number of synchronized objects, the sizes of synchronized objects, and the time consumed by the synchronization:

  Succeed: Total num: 2, size: 750,081. OK num: 2(upload 2 files).
  
  average speed 1641000(byte/s)

Common options

If you use ossutil to switch to a bucket that is located in another region, add the -e option to specify the endpoint of the region in which the bucket is located. If you use ossutil to switch to a bucket that belongs to another Alibaba Cloud account, add the -i option to specify the AccessKey ID of the specified account, and add the -k option to specify the AccessKey secret of the specified account.

ossutil sync oss://examplebucket/srcfolder/  examplefolder/ -e oss-cn-shanghai.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA****  -k 67DLVBkH7EamOjy2W5RVAHUY9H****

For more information about common options, see Common options.