命令結構

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-readable選項，對字節、數量數據，提供了以人類可讀方式輸出信息。即字節數據轉成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支持在進程運行結束后，根據不同的運行結果生成不同的返回碼，具體的返回碼及其含如下。您可以通過以下方式獲取最近一次運行結果的返回碼，然后根據返回碼分析并處理問題。