Object Storage Service:Advanced commands

Command scope

Supported options

All advanced commands

• --encoding-type string: Encoding for input object or file names. Valid value: url.

• --request-payer string: Enables pay-by-requester mode. Set to `requester`.

Commands that support batch operations

• --start-after/--end-with (, ]: Key range filter. Exclusive start, inclusive end.

• filter options: Filter by object/file name, folder, size, time, or metadata. Filter options.

• --limited-num: Limits the number of results returned per API query.

• --recursive/-r: Recurses into all subdirectories.

• --dirs/-d: Lists only the current directory, excluding subdirectories.

  Note

  For objects, this uses the Delimiter method and scans all objects under the prefix. More objects means longer scan time.

• --force/-f: Forces the operation without a confirmation prompt.

• --list-objects: Uses the ListObjects API to list objects.

Commands that support destination filtering rules

• --update: Compares only the modification time. Synchronizes only when the source is newer than the destination.

• --size-only: Compares only the file size. Synchronizes only data with a different file size.

• --checksum: Compares file size first, then CRC-64 checksum. If the checksum is missing on either side, files are treated as inconsistent. Valid only for object-to-object copies.

• --ignore-existing: Skips existing files.

Commands that support single objects

--version-id string: The version ID of the object.

Commands that support list mode

--list-format: The format of the list file. Valid values: plain and inventory.

--list-manifest-from: Reads the description of the list file format from a file. This parameter is required when the list file format is inventory.

Local option

Option type

Description

--encoding-type

string

Encoding for input object or file names. Valid value: url.

--request-payer

string

Enables pay-by-requester mode. Valid value: requester.

--start-after

string

Returns objects alphabetically after the specified value (exclusive).

--end-with

string

Returns objects alphabetically up to the specified value (inclusive).

--page-size

int

Maximum objects per page in batch processing. Default: 1000. Range: 1 to 1000.

--include

stringArray

The inclusion rule for paths or file names.

--include-from

stringArray

Reads inclusion rules from a rule file.

--exclude

stringArray

The exclusion rule for paths or file names.

--exclude-from

stringArray

Reads exclusion rules from a rule file.

--filter

stringArray

The filter rule for paths or file names.

--files-from

stringArray

Reads a list of source file names from a file. Empty lines or comment lines are ignored. This applies only to file filtering operations.

--files-from-raw

stringArray

Reads a list of source file names from a file. This applies only to file filtering operations.

--max-age

Duration

Skips files older than this age. Default unit: seconds. Supports suffixes: ms, s, m, h, d, w, M, y. Default: off.

--min-age

Duration

Skips files newer than this age. Default unit: seconds. Supports suffixes: ms, s, m, h, d, w, M, y. Default: off.

--max-mtime

Time

Skips files newer than this UTC timestamp. Default: off.

--min-mtime

Time

Skips files older than this UTC timestamp. Default: off.

--max-size

SizeSuffix

Maximum file size to transfer. Default unit: bytes. Supports suffixes: B, K, M, G, T, P. 1 K (KiB) = 1024 B.

--min-size

SizeSuffix

Minimum file size to transfer. Default unit: bytes. Supports suffixes: B, K, M, G, T, P. 1 K (KiB) = 1024 B.

--metadata-exclude

stringArray

The exclusion rule for object metadata.

--metadata-include

stringArray

The inclusion rule for object metadata.

--metadata-filter

stringArray

The filter rule for object metadata.

--metadata-filter-from

stringArray

Reads object metadata filter rules from a rule file.

--checksum

/

Copies only source files whose size and checksum (if it exists) are inconsistent.

--size-only

/

Copies only source files with an inconsistent size.

-u, --update

/

Copies only source files that are newer than the destination files.

-r, --recursive

/

Operates on all matching objects in the bucket recursively. Without this option, operates only on the specified path.

-d, --dirs

/

Lists only files and subdirectories in the current folder, without recursion.

-f, --force

/

Forces the operation without a confirmation prompt.

--list-objects

/

Uses the ListObjects API to list objects.

--no-progress

/

Does not display the progress bar.

-j, --job

int

Concurrent tasks for multi-file operations. Default: 3.

--checkers

int

Parallel checkers. Default: 16.

--parallel

int

Concurrent tasks for single-file multipart operations.

--part-size

SizeSuffix

Part size for multipart operations. Auto-calculated by default. Range: 100 KiB to 5 GiB.

--bigfile-threshold

int

Size threshold for multipart upload, download, or copy. Default: 104857600 (100 MiB).

--version-id

string

The version ID of the object.

--storage-class

string

The storage class of the object. Valid values: Standard, IA, Archive, ColdArchive, and DeepColdArchive.

--acl

string

The access permissions of the object. Valid values: private, public-read, public-read-write, and default.

--cache-control

string

Controls browser caching behavior when the object is downloaded.

--content-disposition

string

Display format of the object.

--content-encoding

string

Content encoding of the object.

--content-type

string

The content type of the object.

--expires

string

Absolute expiration time for cached content.

--copy-props

string

Properties to copy from the source object. Valid values: none, metadata, default.

--tagging

string

Object tags in key=value format.

--tagging-directive

string

How to set destination object tags. Valid values: COPY, REPLACE.

--metadata

string

User metadata in key=value format.

--metadata-directive

string

How to set destination object metadata. Valid values: COPY, REPLACE.

--list-format

string

The format of the list file. Valid values: plain and inventory.

--list-manifest-from

string

Reads the description of the list file format from a file. This parameter is required when the list file format is inventory.

Item

Description

Filter rule syntax

• rule pattern rule option parameter: A Glob matching pattern.

• rule filename rule option parameter: The path of a file that contains Glob matching pattern rules.

• rule modifiers pattern rule option parameter: An instruction Glob matching pattern. The + instruction indicates an inclusion rule. Objects that match this rule are included in the result. The - instruction indicates an exclusion rule. Objects that match this rule are excluded from the result.

Filter rule option parameters

• --include

• --include-from

• --exclude

• --exclude-from

• --filter

• --filter-from

Option

Description

--include

--exclude

The parameter is followed by a matching pattern. Each option represents one rule. To use multiple rules, repeat these options.

For example, --include "*.txt" --include "*.js" --exclude "*.jpg" includes all .txt and .js files, but excludes all .jpg files.

The following example command recursively downloads files that match the filter rules from the oss://examplebucket/exampledir/ folder in Alibaba Cloud OSS to the localdir/ folder. The rules include all .txt and .js files, but exclude all .jpg files.

ossutil cp -r oss://examplebucket/exampledir/ localdir/ --include "*.txt" --include "*.js" --exclude "*.jpg"

--filter

The parameter is followed by an instruction matching pattern. Each option value represents one rule. To use multiple rules, repeat these options.

For example, --filter "+ *.txt" --filter "+ *.js" --filter "- *.jpg" includes all .txt and .js files, but excludes all .jpg files.

• The + symbol indicates an inclusion rule. Objects that match this rule are included in the result.

• The - symbol indicates an exclusion rule. Objects that match this rule are excluded from the result.

The following example command recursively downloads files that match the filter rules from the oss://examplebucket/exampledir/ folder in Alibaba Cloud OSS to the localdir/ folder. The rules exclude .txt and .js files, and include only .png files.

ossutil cp -r oss://examplebucket/exampledir/ localdir/ --filter "- *.txt" --filter "- *.js" --filter "+ *.png"

--include-from

--exclude-from

The parameter is followed by a rule file path. Each line in the rule file represents a Glob matching pattern. To import multiple rule files, repeat these options.

All rules imported with --include-from are inclusion rules. All rules imported with --exclude-from are exclusion rules.

For example, --include-from include-file.txt --exclude-from exclude-file.txt includes all .txt and .js files, but excludes all .jpg files.

The content of the rule file include-file.txt is as follows:

 *.txt
 *.js

The rule file include-file.txt contains the following:

 *.jpg

--filter-from

The parameter is followed by a rule file path. Each line in the rule file represents an instruction Glob matching pattern.

To import multiple rule files, repeat these options.

For example, in --filter-from filter-file.txt, the content of the rule file filter-file.txt is as follows:

 # a filter rule file
 + *.txt
 + *.js
 - **

Option

Description

--files-from

Reads a list of paths/file names from a file. You can repeat this option to use multiple list files.

When processing each line in the list file, leading or trailing spaces are removed, and comment lines starting with # or ; are ignored.

--files-from-raw

Reads a list of paths/file names from a file. You can repeat this option to use multiple list files.

When processing each line in the list file, leading or trailing spaces and comment lines starting with # or ; are not ignored.

Parameter

Description

--min-age

Duration

Processes only files modified before the specified interval. Default unit: seconds. Supports unit suffixes, e.g. 1h.

--max-age

Duration

Processes only files modified within the specified interval. Default unit: seconds. Supports unit suffixes, e.g. 1h.

--min-mtime

Time

Processes only files modified after the specified UTC time. Example: 2006-01-02T15:04:05.

--max-mtime

Time

Processes only files modified before the specified UTC time. Example: 2006-01-02T15:04:05.

Parameter

Description

--min-size

Skips files smaller than this size. Default unit: bytes. Example: 1K (KiB) = 1024 bytes.

--max-size

Skips files larger than this size. Default unit: bytes. Example: 1K (KiB) = 1024 bytes.