Object Storage Service:ossutil commands

Command structures

ossutil uses the following command structures, depending on the command type:

ossutil command [argument] [flags]  

ossutil command subcommond [argument] [flags]  

ossutil topic

• argument: arguments. Arguments are of the string type.

• flags: options. You can specify an option in the short form of -o[=value] or -o [ value], or in the full form of --options[=value] or --options[ value]. If you specify an exclusive option multiple times, only the last value takes effect.

Examples:

• High-level command: ossutil cat oss://bucket/object

• Multi-level command: ossutil api get-bucket-cors --bucket bucketexample

• Helper command: ossutil filter

Commands

ossutil provides three types of commands:

• High-level commands

  High-level commands perform common bucket and object tasks, such as creating buckets, deleting buckets, copying data, and modifying object attributes.

  Command	Description
  mb	Creates a bucket.
  rb	Deletes a bucket.
  du	Queries the storage size of the specified bucket or directory (prefix).
  stat	Displays the description of a bucket or object.
  mkdir	Creates an object whose name ends with a forward slash character (/).
  append	Appends content to an appendable object.
  cat	Sends object content to the standard output.
  ls	Lists buckets or objects.
  cp	Uploads, downloads, or copies an object.
  rm	Deletes an object.
  set-props	Sets object attributes.
  presign	Generates a signed URL for an object.
  restore	Restores a frozen object.
  revert	Reverts an object to the specified version.
  sync	Synchronizes directories or objects from the source to the destination.
  hash	Computes the hash of a file or object.

• API-level commands

  API-level commands provide direct access to Object Storage Service (OSS) API operations. You can specify parameters of an OSS API operation in the corresponding ossutil command.

• Helper commands

  Helper commands provide auxiliary support, such as managing configurations and showing help information.

Option types

Load data from files

In most cases, you specify parameter values directly in command lines. When you need to process complex values, loading values from a file provides more efficiency. When you chain commands, you must specify parameter values by using the standard input. When a parameter can take values by using different methods:

• If the value starts with file://, data is loaded from the specified file.

• If the value is -, data is loaded from the standard input.

The following sample command creates a CORS rule by loading the CORS configuration from the cors-configuration.json file:

{
  "CORSRule": {
    "AllowedOrigin": ["www.aliyun.com"],
    "AllowedMethod": ["PUT","GET"],
    "MaxAgeSeconds": 10000
  }
}

ossutil api put-bucket-cors --bucket examplebucket --cors-configuration file://cors-configuration.json

The following sample command creates a CORS rule by taking JSON configuration data in the command line:

{"CORSRule":{"AllowedOrigin":["www.aliyun.com"],"AllowedMethod":["PUT","GET"],"MaxAgeSeconds":10000}}

ossutil api put-bucket-cors --bucket examplebucket --cors-configuration  "{\"CORSRule\":{\"AllowedOrigin\":[\"www.aliyun.com\"],\"AllowedMethod\":[\"PUT\",\"GET\"],\"MaxAgeSeconds\":10000}}"

The following sample command creates a CORS rule by taking the configuration from the standard input:

cat cors-configuration.json | ossutil api put-bucket-cors --bucket examplebucket --cors-configuration -

Command output control

Output formatting

You can use the --output-format parameter in the du, stat, and ls commands and the subcommands of the api command to format the output. The following table describes the valid values of the --output-format option.

In the following example, the output of the get-bucket-cors command is in the raw format:

ossutil api get-bucket-cors --bucket bucketexample
<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration>
  <CORSRule>
    <AllowedOrigin>www.aliyun.com</AllowedOrigin>
    <AllowedMethod>PUT</AllowedMethod>
    <AllowedMethod>GET</AllowedMethod>
    <MaxAgeSeconds>10000</MaxAgeSeconds>
  </CORSRule>
  <ResponseVary>false</ResponseVary>
</CORSConfiguration>

In the following example, the output is formatted in JSON:

ossutil api get-bucket-cors --bucket bucketexample --output-format json
{
  "CORSRule": {
    "AllowedMethod": [
      "PUT",
      "GET"
    ],
    "AllowedOrigin": "www.aliyun.com",
    "MaxAgeSeconds": "10000"
  },
  "ResponseVary": "false"
}

Output query

ossutil provides a built-in JSON-based output query mechanism. You can use the --output-query value option to query output.

The output query feature is based on JMESPath. When you use the output query feature, the output is formatted in JSON, filtered based on JMESPath query expressions, and returned in the specified format. For more information about JMEPath, see JMESPath Specification.

In the following example, the get-bucket-cors command returns only the value of the AllowedMethod parameter:

ossutil api get-bucket-cors --bucket bucketexample --output-query CORSRule.AllowedMethod --output-format json
[
  "PUT",
  "GET"
]

Friendly output display

ossutil provides the --human-readable option that allows the data sizes and quantities in the output of the du and stat commands to be displayed in a more human-readable way. Specifically, data sizes are displayed in 1024-based KiB, MiB, GiB, TiB, and PiB, and quantities are displayed by using the 1000-based unit abbreviations k, m, g, t, and p.

Example of raw output display

ossutil stat oss://bucketexample
ACL                         : private
AccessMonitor               : Disabled
ArchiveObjectCount          : 2
ArchiveRealStorage          : 10
ArchiveStorage              : 131072
...
StandardObjectCount         : 119212
StandardStorage             : 66756852803
Storage                     : 66756852813
StorageClass                : Standard
TransferAcceleration        : Disabled

Example of friendly output display

ossutil stat oss://bucketexample --human-readable
ACL                         : private
AccessMonitor               : Disabled
ArchiveObjectCount          : 2
ArchiveRealStorage          : 10
ArchiveStorage              : 131.072k
...
StandardObjectCount         : 119.212k
StandardStorage             : 66.757G
Storage                     : 66.757G
StorageClass                : Standard
TransferAcceleration        : Disabled

Return codes

When a call to ossutil is made by using a process, the echo information cannot be displayed in real time. When a process run finishes, a return code is displayed based on the result. You can run the following commands to display the return code for the previously executed command and use the return code for troubleshooting.