Object Storage Service:cp (Download objects)

API Action

Description

oss:GetObject

Required to download an object.

oss:GetObjectVersion

Optional. Required to download a specific version of a source object using the --version-id option.

kms:GenerateDataKey

Optional. Required if the downloaded object is encrypted on the server side using KMS.

kms:Decrypt

oss:ListObjects

Optional. Required for batch downloads (recursive operations).

Parameter

Description

cloud_url

The source path of the OSS object. The format is oss://bucket[/prefix]. For example, oss://examplebucket/examplefile.txt.

file_url

The destination path for the local file. If the destination is a directory, the path must end with a separator (/ or \). For example, a Linux path is /localfolder/examplefile.txt and a Windows path is D:\localfolder\examplefile.txt.

-r, --recursive

Recursively applies the operation to all matching objects under the specified prefix. Otherwise, the operation applies only to the single specified object.

-f --force

Forces the operation without prompting for confirmation.

-u，--update

Performs the download only if the destination file does not exist or if the source object's last modified time is later than the destination file's.

--maxdownspeed

The maximum download speed in KB/s. The default value is 0, which means no speed limit.

--disable-ignore-error

Disables ignoring errors during batch operations.

--only-current-dir

Downloads only the objects in the current directory and ignores subdirectories and the objects within them.

--bigfile-threshold

The size threshold in bytes for a resumable download.

Default: 100 MB

Value range: 0 to 9223372036854775807

--part-size

The part size in bytes. By default, ossutil automatically calculates an appropriate part size based on the object size.

Value range: 1 to 9223372036854775807

--checkpoint-dir

The directory where ossutil stores checkpoint information for a resumable download. If a resumable download fails, ossutil creates a .ossutil_checkpoint directory to record checkpoint information. ossutil deletes this directory after the download succeeds. Ensure that the specified directory can be deleted.

--range

Downloads a specified byte range of the object and saves it as a new file. Byte numbering is zero-based.

• Specify a range

  For example, 3-9 downloads bytes from the 3rd to the 9th byte, inclusive.

• Specify a start position

  For example, 3- downloads from the 3rd byte to the end of the object, inclusive.

• Specify an end position

  For example, -9 downloads from the 0th byte to the 9th byte, inclusive.

--encoding-type

The encoding type of the object name. Set this option to url. If this option is not specified, the object name is not encoded.

--include

Includes all objects that match the specified pattern.

For more information, see include and exclude options.

--exclude

Excludes all objects that match the specified pattern.

For more information, see include and exclude options.

--meta

Sets the metadata for the object. The format is header:value#header:value. Example: Cache-Control:no-cache#Content-Encoding:gzip. For more information about metadata, see set-meta (Manage object metadata).

--acl

The access control list (ACL) of the object. Valid values:

• default (default): The object inherits the ACL of the bucket.

• private: Only the bucket owner has read and write permissions. Other users cannot access the objects in the bucket.

• public-read: Only the bucket owner has write permissions. All other users, including anonymous users, have read-only permissions on the objects in the bucket. This can lead to data leaks and increased fees. Use this ACL with caution.

• public-read-write: Anyone, including anonymous users, can read and write objects in the bucket. This can lead to data leaks, increased fees, and potential legal liabilities if malicious content is uploaded. Except for specific use cases, do not configure public read-write permissions.

--snapshot-path

The directory where snapshot information is saved during the download. For the next download, ossutil reads the snapshot information from this directory to perform an incremental download.

--disable-crc64

Disables the 64-bit cyclic redundancy check (CRC-64). By default, ossutil enables CRC-64 for all data transfers.

--payer

The payment method for the request. To have the requester pay for traffic and requests generated from accessing the specified path, set this option to requester.

--partition-download

Specifies a partition of the object to download. The value is in the format Partition number:Total partitions. For example, 1:5 indicates that this ossutil command downloads partition 1 out of 5 total partitions. Partition numbers are 1-based. The tool's internal algorithm determines how ossutil partitions the object. This option lets you split an object into multiple partitions and download them in parallel using multiple ossutil commands. Each command downloads its assigned partition.

-j，--job

The number of concurrent tasks for multi-object operations. Default: 3. Value range: 1 to 10,000.

--parallel

The number of concurrent tasks for single-object operations. Value range: 1 to 10,000. If this option is not set, ossutil determines the value based on the operation type and object size.

--version-id

Downloads a specific version of an object. Use the --version-id option only with a versioning-enabled bucket. To enable versioning for a bucket, see bucket-versioning (Versioning).

--start-time

A UNIX timestamp. If you specify this option, objects with a last modified time earlier than this timestamp are ignored.

--end-time

A UNIX timestamp. If you specify this option, objects with a last modified time later than this timestamp are ignored.