使用 mkdir 命令可在存储空间内创建文件目录。使用 mkdir 命令前，建议先使用 ossutil help mkdir 命令查看帮助信息。

• 创建一个目录

  ./ossutil mkdir oss://bucket/dir/

  说明

  • dir 需以正斜线（/）结尾，若未添加正斜线（/），ossutil 会自动添加。
  • 若目录已存在，会出现报错。
• 创建一个多级目录

  ./ossutil mkdir oss://bucket/dir1/dir2/

  创建多级目录时，只会创建最后一级目录。例如此命令中，若将 dir2/ 删除，且 dir1/ 中无文件，则 dir1/ 会消失。

使用 cp 命令，可对文件进行上传/下载/拷贝文件操作。在使用 cp 命令前，建议先使用 ossutil help cp 命令查看帮助信息。

• cp 命令简介
  使用 cp 命令进行上传/下载/拷贝文件时：

  • 使用 -r 选项来拷贝文件夹，对大文件默认使用分片上传并可进行断点续传（开启分片上传的大文件阈值可用 --bigfile-threshold 选项来设置）。
  • 使用 -f 选项表示强制上传。当目标端存在同名文件时，不询问，直接覆盖。
  • 使用 --retry-times=${times} 选项来指定当错误发生时 ossutil 重试次数。该值默认为 10，取值范围为：1-500。
  • 使用 --encoding-type url 选项表示输入的 Object 名和文件名都是经过 url 编码。目前，ossutil 只支持 url encode，且 Bucket 名不支持 url encode。
  当批量上传/下载/拷贝文件时，如果某个文件出错，ossutil 默认会将错误信息记录在 report 文件，并跳过该文件，继续其他文件的操作。更多信息请参见 ossutil help cp。

  说明

  • 默认情况下，ossutil 进行数据传输时都会打开 crc64 校验，您可以在上传/下载/拷贝 --disable-crc64 选项关闭 crc64 校验。
  • 当出现存储空间（Bucket）不存在、AccessKeyId/AccessKeySecret 错误造成的权限验证非法等错误时，不再继续拷贝其他文件。
• 上传文件
  • 将当前目录下 a.txt 文件上传到 oss://bucket/path

    $./ossutil cp a.txt oss://bucket/path

  • 上传单个文件并指定 --meta 选项

    上传文件的同时可以使用 --meta 选项设置Object 的 meta 信息，其内容格式为 header:value#header:value...，如下将当前目录下文件 a.txt 上传并设置其 meta 信息：

    $./ossutil cp a.txt oss://bucket/path --meta=Cache-Control:no-cache#Content-Encoding:gzip

    说明 当前可选的 Header 列表如下：

    Headers:
          Expires(time.RFC3339:2006-01-02T15:04:05Z07:00)
          X-Oss-Object-Acl
          Origin
          X-Oss-Storage-Class
          Content-Encoding
          Cache-Control
          Content-Disposition
          Accept-Encoding
          X-Oss-Server-Side-Encryption
          Content-Type
          以及以X-Oss-Meta-开头的header

    Header 不区分大小写，但 Value 区分大小写。设置后将用指定的 meta 代替原来的 meta。没有指定的 HTTP HEADER 将保留，没有指定的 user meta 将会被删除。

  • 上传文件夹：
    上传文件时，搭配 -r 选项可以将目标文件夹上传到 OSS。命令如下:

    $./ossutil cp -r dir oss://bucket/path

    说明 若上传目标对象为符号链接（软链接），且指向本地文件夹，则使用 cp 命令上传时，应当给软链接加上正斜线（/）。

    ./ossutil cp -r symbolic_link/ oss://bucket/path

  • 上传文件/文件夹并设置限速
    上传文件/文件夹时，指定 --maxupspeed 选项，可设置上传时的最高速度，单位为 KB/s，缺省为 0（不限速）。

    • 上传文件并设置限速为 1MByte/s

      $./ossutil cp a.jpg oss://bucket/path --maxupspeed 1024

    • 上传文件夹并设置限速为 1MByte/s

      $./ossutil cp -r dir oss://bucket/path --maxupspeed 1024

  • 上传文件夹并指定 --update 选项

    批量上传时，若指定 --update 选项，只有当目标文件不存在，或源文件新于目标文件时，ossutil 才会执行上传操作。命令如下：

    $./ossutil cp -r dir oss://bucket/path --update

    该选项可用于当批量上传失败重传时，跳过已经成功的文件，实现增量上传。

  • 上传文件夹并指定 --snapshot-path 选项

    批量上传时，若指定 --snapshot-path 选项，ossutil 在指定的目录下生成文件上传的快照信息，在下一次指定该选项上传时，ossutil 会读取指定路径下的快照信息进行增量上传。命令如下：

    $./ossutil cp -r dir oss://bucket/path --snapshot-path=path

    注意

    • --snapshot-path 选项用于在某些场景下加速增量上传或增量下载批量文件(拷贝不支持该选项)。例如，文件数较多且两次上传期间没有其他用户更改 OSS 上对应的 Object。
    • --snapshot-path 命令通过在本地记录成功上传的文件的本地 lastModifiedTime，从而在下次上传时通过比较 lastModifiedTime 来决定是否跳过相同文件的上传，所以在使用该选项时，请确保两次上传期间没有其他用户更改了 OSS 上的对应 Object。当不满足该场景时，如果想要增量上传批量文件，请使用 --update 选项。
    • ossutil 不会主动删除 snapshot-path 下的快照信息，为了避免快照信息过多，当用户确定快照信息无用时，请用户自行清理 snapshot-path。
    • 由于读写 snapshot 信息需要额外开销，当要批量上传的文件数比较少或网络状况比较好或有其他用户操作相同 Object 时，并不建议使用该选项。可以使用 --update 选项来增量上传。
    • --update 选项和 --snapshot-path 选项可以同时使用，ossutil 会优先根据 snapshot-path 信息判断是否跳过上传，如果不满足跳过条件，再根据 --update 判断是否跳过上传。
• 下载文件
  • 下载单个文件：

    $./ossutil cp oss://my-bucket/path/test1.txt /dir

    下载文件时，可以通过 --range 选项进行指定范围下载。

    示例：将 test1.txt 的第 10 到第 20 个字符作为一个文件载到本地。

    $./ossutil cp oss://my-bucket/path/test1.txt /dir  --range=10-20
    Succeed: Total num: 1, size: 11. OK num: 1(download 1 objects).
    0.290769(s) elapsed

  • 下载文件夹：

    $./ossutil  cp -r oss://my-bucket/path  /dir

  • 下载文件夹并指定 --update 选项

    批量下载时，若指定 --update 选项，只有当目标文件不存在，或源文件新于目标文件时，ossutil 才会执行下载操作。命令如下：

    $./ossutil cp -r oss://bucket/path  /dir  --update

    该选项可用于当批量下载失败重传时，跳过已经下载成功的文件。实现增量下载。

• 拷贝文件

  目前只支持拷贝 Object，不支持拷贝未完成的 Multipart，不支持跨 region 拷贝 Object。

  • 拷贝单个文件

    ./ossutil cp oss://bucket/path1/a oss://bucket/path2/

  • 拷贝单个文件并重命名

    ./ossutil cp oss://bucket/path1/a oss://bucket/path2/b

  • 拷贝单个文件并指定 --meta 选项
    拷贝文件的同时可以使用 --meta 选项设置 Object 的 meta 信息，其内容格式为 header:value#header:value...。

    ./ossutil cp oss://bucket/path1/a oss://bucket/path2/ --meta=Cache-Control:no-cache

    说明 当前可选的 Header 列表如下：

    Headers:
          Expires(time.RFC3339:2006-01-02T15:04:05Z07:00)
          X-Oss-Object-Acl
          Origin
          X-Oss-Storage-Class
          Content-Encoding
          Cache-Control
          Content-Disposition
          Accept-Encoding
          X-Oss-Server-Side-Encryption
          Content-Type
          以及以X-Oss-Meta-开头的header

    Header 不区分大小写，但 Value 区分大小写。设置后将用指定的 meta 代替原来的 meta。没有指定的 HTTP HEADER 将保留，没有指定的 user meta 将会被删除。

  • 同 region 不同 Bucket 之间的文件拷贝
    拷贝文件时，搭配 -r 选项可以实现批量文件拷贝功能。

    $./ossutil cp oss://your_src_bucket/path1/ oss://your_dest_bucket/path2/ -r

  • 同 region 不同 Bucket 之间的增量文件拷贝
    批量拷贝时，若指定 --update 选项，只有当目标文件不存在，或源文件新于目标文件时，ossutil 才会执行拷贝操作。命令如下：

    $./ossutil cp oss://your_src_bucket/path1/ oss://your_dest_bucket/path2/ -r --update

    该选项可用于当批量拷贝失败重传时，跳过已经拷贝成功的文件，实现增量拷贝。
• 上传/下载/拷贝文件的性能调优
  在 cp 命令中，通过 --jobs 项和 --parallel 项控制并发数。当 ossutil 自行设置的默认并发达不到用户的性能需求时，您可以自行调整该两个选项来升降性能。

  • 使用--jobs 项来控制多个文件上传/下载/拷贝时，文件间启动的并发数。
  • 使用--parallel 项来控制分片上传/下载/拷贝一个大文件时，每一个大文件启动的并发数。

  默认情况下，ossutil 会根据文件大小来计算 parallel 个数（该选项对于小文件不起作用，进行分片上传/下载/拷贝的大文件文件阈值可由 --bigfile-threshold 选项来控制）。当进行批量大文件的上传/下载/拷贝时，实际的并发数为 jobs 个数乘以 parallel 个数。

  警告

  • 通常情况下，当 ECS 虚拟机或者服务器在网络、内存、CPU 等资源不是特别大的情况下，建议将并发数调整到 100 以下。如果网络、内存、CPU 等资源没有占满，可以适当增加并发数。
  • 如果并发数调得太大，由于线程间资源切换及抢夺等，ossutil 上传/下载/拷贝性能可能会下降。并发数过大可能会产生 EOF 错误。所以请根据实际的机器情况调整 --jobs 和 --parallel 选项的数值。如果要进行压测，可在一开始时调低这两项数值，然后逐渐调大直至找到最优值。

追加上传命令如下：

./ossutil appendfromfile a.txt oss://bucket/object [--meta=meta-value]

如果 object 不存在，可通过 --meta 设置 object 的 meta 信息，例如 --meta "X-Oss-Meta-Author:test"。如果 object 已经存在，不可以输入 --meta 信息，OSS 不支持在已经存在的 appendable object 上设置 meta 信息。

使用 sign 命令可以生成经过签名的文件 URL 供第三方用户临时访问 Object。使用 sign 命令前，建议先使用 ossutil help sign 命令查看帮助信息。

• 生成默认超时时间的文件 URL，默认超时时间为 60 秒

  $./ossutil sign oss://bucket/path/object

• 生成指定超时时间的文件 URL
  使用 --timeout 选项，可以设置文件 URL 的超时时间，单位为秒，默认值为 60，取值范围为 0-9223372036854775807。

  $./ossutil sign oss://bucket/path/object --timeout=${time}

• 删除单个文件

  $./ossutil rm oss://bucket/path/object

• 删除指定前缀的所有文件
  配合 -r 选项，可以递归执行删除操作，删除指定前缀的所有文件。

  $./ossutil rm oss://bucket/path/ -r

  说明 更多帮助信息请参考 ossutil help rm。

• include/exclude 参数使用示例
  • 上传/下载/拷贝时过滤文件
    • 上传所有文件格式为 txt 的文件：

      $./ossutil cp dir/ oss://my-bucket/path --include "*.txt" -r

    • 下载所有文件格式不为 jpg 的文件：

      $./ossutil cp oss://my-bucket/path dir/ --exclude "*.jpg" -r

    • 拷贝所有文件名包含 abc 且不是 jpg 和 txt 格式的文件：

      $./ossutil cp oss://my-bucket1/path oss://my-bucket2/path --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -r

  • set-meta 时过滤文件
    • 将所有文件格式为 jpg 的文件设置为低频存储：

      $./ossutil64 set-meta oss://my-bucket/path X-Oss-Storage-Class:IA --include "*.jpg" -u -r

    • 将所有文件名包含 abc 且文件格式不为 jpg 和 txt 的文件设置为标准存储：

      $./ossutil set-meta oss://my-bucket/path X-Oss-Storage-Class:Standard --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -u -r

  • set-acl 时过滤文件
    • 将所有文件类型为 .jpg 的文件读写权限设置为私有：

      $./ossutil64 set-acl oss://my-bucket/path private  --include "*.jpg"  -r

  • 综合示例：上传指定条件（所有文件名不包含 2 且文件格式为 jpg 和 txt）的文件并设定文件存储类型及读写权限：

    $./ossutil cp dir/ oss://my-bucket/path -rf --include "*.txt"  --include "*.jpg" --exclude "*2*" --meta  X-Oss-Storage-Class:Standard --acl public-read

使用 cat 命令可以将文件内容输出到 ossutil。

./ossutil cat oss://bucket/object