命令简介

命令结构

ossutil常用的命令格式如下：

ossutil command [argument] [flags]  

ossutil command subcommond [argument] [flags]  

ossutil topic

• argument：参数，为字符串。

• flags：选项，支持短名字风格-o[=value]/ -o [ value]和长名字风格--options[=value]/--options[ value]。如果多次指定某个排它参数，则仅最后一个值生效。

命令示例如下：

• 命令：ossutil cat oss://bucket/object

• 多级命令：ossutil api get-bucket-cors --bucket bucketexample

• 帮助主题：ossutil filter

命令列表

ossutil 提供了三类命令：

• 高级命令

  用于常用的对对象或者存储空间的操作场景，例如存储空间创建、删除、数据拷贝、对象属性修改等。

  命令名	含义
  mb	创建存储空间
  rb	删除存储空间
  du	获取存储或者指定前缀所占的存储空间大小
  stat	显示存储空间或者对象的描述信息
  mkdir	创建一个名字有后缀字符/的对象
  append	将内容上传到追加类型的对象末尾
  cat	将对象内容连接到标准输出
  ls	列举存储空间或者对象
  cp	上传、下载或拷贝对象
  rm	删除存储空间里的对象
  set-props	设置对象的属性
  presign	生成对象的预签名URL
  restore	恢复冷冻状态的对象为可读状态
  revert	将对象恢复成指定的版本
  sync	将本地文件目录或者对象从源端同步到目的端
  hash	计算文件/对象的哈希值

• API级命令，提供了API操作的直接访问，支持该接口的配置参数。

  说明

  仅列举部分命令，您可以通过ossutil api -h查看所有命令。

  命令名	含义
  put-bucket-acl	设置、修改Bucket的访问权限
  get-bucket-acl	获取访问权限
  ....
  put-bucket-cors	设置跨域资源共享规则
  get-bucket-cors	获取跨域资源共享规则
  delete-bucket-cors	删除跨域资源共享规则

• 辅助命令，例如配置文件的配置、额外的帮助主题等。

  命令名	含义
  help	获取帮助信息
  config	创建配置文件用以存储配置项和访问凭证
  update	版本更新
  version	显示版本信息
  probe	探测命令

命令选项类型

从非命令行中加载数据

一般情况下，参数的值都放在命令行里，当参数值比较复杂时，需要从文件加载参数值；当需要串联多个命令操作时，需要标准输中加载参数值。所以，对需要支持多种加载参数值的参数，做了如下约定：

• 以file://开始的，表示从文件路径中加载。

• 当参数值为-时，表示从标准输入中加载。

例如， 设置存储空间的跨域设置，以JSON参数格式为例，通过文件方式加载跨域参数。cors-configuration.json文件如下：

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

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

通过选项参数值加载跨域参数，cors-configuration.json的紧凑形式如下：

{"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}}"

从标准输入加载参数的示例如下：

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

控制命令输出

输出格式

对ossutil api下的子命令，以及du、stat、ls命令，支持通过--output-format参数调整其输出格式，当前支持的格式如下：

例如：以get-bucket-cors为例，原始内容如下：

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>

转成JSON如下：

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

筛选输出

ossutil提供了基于JSON的内置客户端筛选功能，通过--output-query value选项使用。

该功能基于JMESPath语法，当使用该功能时，会把返回的内容转成JSON，然后再使用JMESPath进行筛查，最后按照指定的输出格式输出。有关JMESPath 语法的说明，请参见JMESPath Specification。

例如：以get-bucket-cors为例，只输出AllowedMethod内容，示例如下：

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

友好显示

对于高级命令（du、stat），提供了--human-reaable选项，对字节、数量数据，提供了以人类可读方式输出信息。即字节数据转成Ki|Mi|Gi|Ti|Pi后缀格式（1024 base），数量数据转成k|m|g|t|p后缀格式(1000 base)。

例如：原始模式

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

友好模式

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

命令返回码

通过进程等方式调用ossutil时，无法实时查看回显信息。ossutil支持在进程运行结束后，根据不同的运行结果生成不同的返回码，具体的返回码及其含如下。您可以通过以下方式获取最近一次运行结果的返回码，然后根据返回码分析并处理问题。