如何擷取協助資訊 - Object Storage Service

本文為您介紹如何擷取ossutil命令的協助資訊。

內建的協助命令

在使用ossutil時，您可以在命令名稱末尾輸入-h或者--help，以擷取任何命令的協助資訊。您可以使用ossutil [topic]擷取特定主題的協助資訊。命令樣本如下：

命令說明	命令
顯示ossutil可用的頂層命令的協助	`ossutil -h`
顯示cp命令的協助資訊	`ossutil cp -h`
顯示API命名下的所有子命令	`ossutil api -h`
顯示API命名下的put-bucket-cors子命令的幫忙資訊	`ossutil api put-bucket-cors -h`
顯示filter類選項的協助說明	`ossutil filter`

命令的協助格式

命令分為父命令和子命令，即父命令包含有子命令，子命令下不包含其它命令。

父命令的協助格式

命令的協助分為5部分：描述資訊、用法、子命令列表、額外的說明主題和其它資訊。

ossutil一款用於管理Object Storage Service資料的命令列工具。

用法: ossutil [command]

命令列表:
  api         API 級命令
  append      將檔案內容上傳到追加類型的對象末尾
  cat         將對象內容串連到標準輸出
  config      建立設定檔用以儲存配置項和訪問憑證
  cp          上傳，下載或拷貝對象
  du          擷取儲存或者指定首碼所佔的儲存空間大小
  hash        計算檔案的雜湊值
  help        Help about any command
  ls          列舉儲存空間或者對象
  mb          建立儲存空間
  mkdir       建立一個名字有尾碼字元'/'的對象
  presign     產生對象的預簽名URL
  probe       探測命令
  rb          刪除儲存空間
  restore     恢複冷凍狀態的對象為可讀狀態
  revert      將對象從刪除狀態恢複成最近的多版本狀態
  rm          刪除儲存空間裡的對象
  set-props   設定對象的屬性
  stat        顯示bucket或者object的描述資訊
  sync        將本地檔案目錄或者對象從源端同步到目的端
  update      更新ossutil
  version     顯示版本資訊

其他說明主題:
  filter      過濾參數的詳細說明，如何在支援這些參數的命令中使用

Use "ossutil [command] --help" for more information about a command.
Use "ossutil [topic]" for more information about a topic.

子命令協助格式

命令的協助分為六部分：詳細描述、用法、別名（可選）、樣本、局部選項和全域選項。

樣本一：cat命令

ossutil cat -h --language zh
將對象內容輸出到標準輸出。
要運行該命令，您必須具有oss:GetObject許可權。

用法: ossutil cat oss://bucket/object [flags]

樣本:

1）將儲存空間examplebucket內名為example.txt的檔案內容輸出到螢幕
  ossutil cat oss://examplebucket/example.txt

2）將儲存空間examplebucket內名為example.txt，版本號碼為CAEQARiBgID8rumR2h***的檔案內容輸出到螢幕
  ossutil cat oss://examplebucket/example.txt --version-id CAEQARiBgID8rumR2h***

3) 指定範圍，將儲存空間examplebucket內名為example.txt的檔案內容輸出到螢幕
  顯示開始的 10個字元
  ossutil cat oss://examplebucket/example.txt --head 10

  顯示最後的 10個字元
  ossutil cat oss://examplebucket/example.txt --tail 10

  從位置10到檔案尾
  ossutil cat oss://examplebucket/example.txt --offset 10

  從位置10開始的20個字元
  ossutil cat oss://examplebucket/example.txt --offset 10 --count 20

選項:
      --count int              僅列印 N 個字元 (預設值 -1)
      --encoding-type string   輸入的對象名或檔案名稱的編碼方式, 取值: "url"
      --head int               僅列印前 N 個字元
      --offset int             從位置 N 開始列印
      --request-payer string   請求的支付方式，如果為要求者付費模式，請設定該值, 取值: "requester"
      --tail int               僅列印最後 N 個字元
      --version-id string      對象的版本標識

全域選項:
  -i, --access-key-id string        訪問oss使用的AccessKeyID
  -k, --access-key-secret string    訪問oss使用的AccessKeySecret
      --addressing-style string     請求地址的格式 (預設值 "virtual"), 取值: "virtual","path","cname"
  -c, --config-file string          設定檔的路徑 (預設值 "~\\.ossutilconfig")
      --connect-timeout int         用戶端連線逾時的時間，單位為秒 (預設值 10)
  -n, --dry-run                     在不進行任何更改的情況下執行試運行
  -e, --endpoint string             對外服務的訪問網域名稱
  -h, --help                        help for the command
      --language string             顯示的語言
      --loglevel string             記錄層級 (預設值 "off"), 取值: "off","info","debug"
      --mode string                 表示鑒權模式, 取值: "AK","StsToken","EcsRamRole","Anonymous"
      --output-format string        輸出格式 (預設值 "raw")
      --output-properties strings   輸出參數屬性
      --output-query string         JMESPath 查詢條件
      --profile string              指定設定檔裡的profile
      --read-timeout int            用戶端讀寫請求逾時時間, 單位為秒 (預設值 20)
      --region string               資料中心所在的地區
      --retry-times int             當錯誤發生時的重試次數 (預設值 10)
      --sign-version string         請求使用的簽名演算法版本 (預設值 "v4"), 取值: "v1","v4"
      --skip-verify-cert            表示不校正服務端的數位憑證
  -t, --sts-token string            訪問oss使用的STSToken

樣本二：put-bucket-cosr命令

ossutil api put-bucket-cors -h --language zh

設定指定儲存空間（Bucket）的跨域資源共用CORS（Cross-Origin Resource Sharing）規則。
- 調用該介面時需要擁有oss:PutBucketCors許可權。
- 預設不開啟CORS
Bucket預設不開啟CORS功能，所有跨域請求的Origin都不被允許。

- 覆蓋語義
 PutBucketCors為覆蓋語義，即新配置的CORS規則將覆蓋已有的CORS規則。

- 應用程式中使用CORS
在應用程式中使用CORS功能時，需通過PutBucketCors介面手動上傳CORS規則來開啟CORS功能。
例如從example.com通過瀏覽器的XMLHttpRequest功能來訪問OSS，需要通過本介面手動上傳CORS規則，且CORS規則需由XML文檔進行描述。

- CORS規則匹配
當OSS收到一個跨域請求或OPTIONS請求，會先讀取Bucket對應的CORS規則，然後進行相應的許可權檢查。OSS會依次檢查每一條規則，使用第一條匹配的規則來允許請求並返回對應的Header。如果所有規則都匹配失敗，則不附加任何CORS相關的Header。
CORS規則匹配成功必須滿足以下三個條件：
    - 請求的Origin必須匹配一個AllowedOrigin項。

    - 請求的方法（例如GET、PUT等）或者OPTIONS請求的Access-Control-Request-Method頭對應的方法必須匹配一個AllowedMethod項。

    - OPTIONS請求的Access-Control-Request-Headers頭包含的每個header都必須匹配一個AllowedHeader項。

關於介面的更多描述，詳見： https://www.alibabacloud.com/help/zh/oss/developer-reference/putbucketcors

用法: ossutil api put-bucket-cors --bucket value --cors-configuration value [flags]

樣本:

--cors-configuration 配置選項 既支援XML文法也支援JSON文法，當選項值包含file://首碼時，表示從檔案中讀取配置。

XML 文法：
<CORSConfiguration>
  <CORSRule>
    <AllowedOrigin>string</AllowedOrigin>
    ...
    <AllowedMethod>string</AllowedMethod>
    ...
    <AllowedHeader>string</AllowedHeader>
    <ExposeHeader>string</ExposeHeader>
    ...
    <MaxAgeSeconds>integer</MaxAgeSeconds>
  </CORSRule>
  ...
  <ResponseVary>boolean</ResponseVary>
</CORSConfiguration>

JSON 文法：
{
  "CORSRule": [
    {
      "AllowedOrigin": ["string", ...],
      "AllowedMethod": ["string", ...],
      "AllowedHeader": "string",
      "ExposeHeader": ["string", ...],
      "MaxAgeSeconds": integer
    },
    ...
  ],
  "ResponseVary": boolean
}

1）指定允許的跨域請求來源為www.aliyun.com、允許的跨域要求方法為 PUT 和 GET，請求返回結果的緩衝時間為10000秒。

使用 xml 設定檔，cors-configuration.xml 內容如下：
<CORSConfiguration>
  <CORSRule>
    <AllowedOrigin>www.aliyun.com</AllowedOrigin>
    <AllowedMethod>PUT</AllowedMethod>
    <AllowedMethod>GET</AllowedMethod>
    <MaxAgeSeconds>10000</MaxAgeSeconds>
  </CORSRule>
</CORSConfiguration>

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

使用 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

使用 json 配置參數：
ossutil api put-bucket-cors --bucket examplebucket --cors-configuration  "{\"CORSRule\":{\"AllowedOrigin\":[\"www.aliyun.com\"],\"AllowedMethod\":[\"PUT\",\"GET\"],\"MaxAgeSeconds\":10000}}"


選項:
      --bucket string               Bucket名稱
      --cors-configuration string   Bucket的CORS規則容器

全域選項:
  -i, --access-key-id string        訪問oss使用的AccessKeyID
  -k, --access-key-secret string    訪問oss使用的AccessKeySecret
      --addressing-style string     請求地址的格式 (預設值 "virtual"), 取值: "virtual","path","cname"
  -c, --config-file string          設定檔的路徑 (預設值 "~\\.ossutilconfig")
      --connect-timeout int         用戶端連線逾時的時間，單位為秒 (預設值 10)
  -n, --dry-run                     在不進行任何更改的情況下執行試運行
  -e, --endpoint string             對外服務的訪問網域名稱
  -h, --help                        help for the command
      --language string             顯示的語言
      --loglevel string             記錄層級 (預設值 "off"), 取值: "off","info","debug"
      --mode string                 表示鑒權模式, 取值: "AK","StsToken","EcsRamRole","Anonymous"
      --output-format string        輸出格式 (預設值 "raw")
      --output-properties strings   輸出參數屬性
      --output-query string         JMESPath 查詢條件
      --profile string              指定設定檔裡的profile
      --read-timeout int            用戶端讀寫請求逾時時間, 單位為秒 (預設值 20)
      --region string               資料中心所在的地區
      --retry-times int             當錯誤發生時的重試次數 (預設值 10)
      --sign-version string         請求使用的簽名演算法版本 (預設值 "v4"), 取值: "v1","v4"
      --skip-verify-cert            表示不校正服務端的數位憑證
  -t, --sts-token string            訪問oss使用的STSToken

每個子命令的協助均包括一個選項類型、選項名稱和描述。

選項類型	選項名稱	說明
字串	--option string	字串參數可以包含ASCII字元集中的字母數字字元、符號和空格。如果包含空格時，需要用引號引起來。例如--acl private。
布爾值	--option	開啟或關閉某一選項。例如：--dry-run。
整數	--option Int	不帶正負號的整數。例如：--read-timeout 10。
時間戳記	--option Time	ISO 8601格式，即DateTime或Date。例如：--max-mtime 2006-01-02T15:04:05。
位元組單位尾碼	--option SizeSuffix	預設單位是位元組（B），也可以使用單位尾碼形式，支援的單位尾碼為：K(KiB)=1024位元組、M(MiB)、G(GiB)、G(GiB)、T(TiB)、P(PiB)、E(EiB)。例如：最小size為1024位元組。 --min-size 1024 --min-size 1K
時間單位尾碼	--option Duration	時間單位，預設單位是秒，支援的單位尾碼為： ms 毫秒，s 秒，m 分鐘，h 小時，d 天，w 星期，M 月，y 年。也支援小數。例如：1.5天 --min-age 1.5d
字串列表	--option strings	支援單個或者多個同名選項，支援以逗號（,）分隔的多個值，支援多選項輸入的單值。例如：--metadata user=jack, --metadata address=china
字串數組	--option stringArray	支援單個或者多個同名選項，只支援多選項輸入的單值。例如：--include .jpg --include .txt