help(获取帮助信息)

本文为您介绍如何获取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一款用于管理对象存储OSS数据的命令行工具。

用法: 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