BOS CMD

概述

百度智能云已经提供了基于BCE Python SDK的命令行工具 BCE CLI(Command Line Interface),但是Python 版BCE CLI 依赖用户的操作环境,而且需要用户安装Python 2.7,所以百度智能云现在向用户提供一种安装更方便,执行效率更高,而且使用方法与 BCE CLI 相同的命令行工具 —— BCE CMD。

BCE CMD当前只包含了BOS的功能,所以下文都用BOS CMD代指BCE CMD。BOS CMD提供了丰富的功能,您不仅可以通过BOS CMD完成Bucket的创建和删除,Object的上传、下载、删除和拷贝等, 当您从BOS下载文件或者上传文件到BOS遇到问题时,还可以使用BCE CMD的子命令bosprobe进行错误检查。

安装BOS CMD

bcecmd下载

文件名及下载地址 操作系统 架构 大小 MD5
windows-bcecmd-0.2.5.zip Windows x86-64 3.3MB 1d6f4924163f189f8cad1b140a7178e8
linux-bcecmd-0.2.5.zip Linux x86-64 3.4MB 3d231a42789892f22a7e36988b37c65b
mac-bcecmd-0.2.5.zip Mac 64 5.9MB 448ad23962502a0c68f1774888b11ec9

安装

请根据自己的操作系统类型,下载对应版本的bcecmd,下载完成后只需解压zip包到您需要执行程序的目录,无需安装,您可以直接在终端中使用。

说明:

  • Linux 用户解压命令为 $ unzip linux-bcecmd-0.2.5.zip
  • Mac 用户解压命令为 $ unzip mac-bcecmd-0.2.5.zip
  • 建议您将 bcecmd 所在目录加入操作系统的环境变量中,这样您在任何目录下都能够运行 bcecmd;
  • windows用户请在windows cmd中运行程序, linux和mac用户请在终端中运行程序。

配置BOS CMD

通用配置

配置支持中文显示

如需要配置支持中文显示的CMD环境,请执行如下命令配置:

$ export LANG=en_US.UTF-8

说明:可先执行locale命令查看当前环境的语言支持情况,若不是LANG=en_US.UTF-8,可执行上述命令进行修改。

配置AK/SK、Region、Host信息

使用BOS CMD工具之前,推荐先设置Access Key、Secure Key、Region和Host。可以通过-c/--configure来设置AK、SK、Region和Host信息。

$ bcecmd -c  [<conf-path>]

$ Your Access Key ID [None]: Enter Your AK

$ Your Secret Access Key ID [None]: Enter Your SK

$ Default Region Name [bj]: Enter Your region

$ Default Domain [bj.bcebos.com]: Enter Your host

说明:

  • <conf-path>为本地文件目录,当用户有多个百度智能云账户时,通过指定<conf-path>将不同账号的配置文件写到不同目录下,执行命令时可以指定目录选择对应账户的配置。
  • 不指定<conf-path>时,CMD在配置完成后将配置文件自动写到当前用户主目录~/.go-bcecli;指定<conf-path>时,将配置文件自动写到指定目录。
  • 即使不设置AK/SK,您也可以通过BOS CMD访问public权限的bucket。
  • 指定Region之后您可以不指定Host,BOS CMD可自动拼接Host为Region.bcebos.com。
  • 如果您指定了Host,那么BOS CMD不再自动拼接Host,而是访问您指定的Host。
  • 可以填写None将AK/SK/Region以及Domain设置为空。当Region设置为空时默认值为bj。当Domain设置为空时默认使用Region拼接,当两个同时为空时默认访问bj.bcebos.com

BOS CMD相关配置

bcecmd -c命令除了可以进行通用设置,还支持设置自动切换域名,另还支持设置BOS上传的相关属性,如是否使用HTTPS协议及分块上传的并发数等。

设置自动切换域名

BOS拥有多个Region,如果您需要在不同Region下面进行操作,BOS CMD的“自动切换域名”功能可以根据您当前操作的Bucket所在Region,来自动切换域名。为了方便您的使用,CMD会默认开启此功能。

如果您想让您所以的操作请求都发送到您指定的域名或者Host(通过bcecmd -c配置的domain),你可以通过bcecmd -c命令关闭“自动切换域名”功能, 设置为no表示关闭此功能。

$ bcecmd -c [<conf-path>]

$ Default use auto switch domain [yes]:

说明:取值可以是yes和no,yes代表开启根据Bucket所在Region自动切换域名,no表示关闭。缺省情况下为开启。

设置HTTPS协议上传

为了保证用户数据的安全性,建议用户使用HTTPS协议上传。是否使用HTTPS可以通过bcecmd -c命令进行设置,设置为no代表使用HTTP协议上传。

$ bcecmd -c [<conf-path>]

$ Default use https protocol [no]:

说明:取值可以是yes和no,缺省情况下使用HTTP协议上传。

设置大文件分块上传的并发数

使用BOS CMD上传大于32MB的文件时,BOS CMD会自动进行分块上传,您可以通过bcecmd -c命令设置单个文件分块上传的并发数。

$ bcecmd -c [<conf-path>]

$ Default multi upload thread num [10]:

说明:分块上传的并发数应设置为大于等于1的整数,缺省为10。

设置BOS CMD sync命令并发上传下载的文件数

BOS CMD 通过sync命令执行上传或下载时,会并发操作多文件。您可以通过bcecmd -c命令设置 sync 命令并发数。

$ bcecmd -c [<conf-path>]

$ Default sync processing num [10]:

说明:并发数应设置为大于等于1的整数,缺省为10。

注意:使用sync命令时,sync会并发地处理多个文件,如果有文件大小超过分块上传的阈值时,这个文件也会被分块后并发上传, 所以最坏的情况下将有 “sync并发数 x 单文件分块上传并发数” 个协程同时运行, 但是并不是并发数越高上传效率越高,所以您需要根据自己电脑配置来配置合适的sync并发数和分块上传并发数。

设置分块上传的单个分块大小

BCE CMD默认的单个分块大小为10Mb,如果您网络环境良好(使用默认分块大小上传文件未出现超时),建议您就使用默认的分块大小。
当上传出现超时时(当BOS返回的错误码为RequestTimeout),建议你调低单个分块的大小来避免上传超时。您可以通过如下的命令配置分块大小:

$ bcecmd -c [<conf-path>]

$ Default multi upload part size [10] MB (Must be positive integer and equal or greater than 1) :

说明:

通过CMD使用BOS服务

用户可以通过bos命令来访问BOS服务,管理、操作Bucket和Object。如果BOS服务余额不足时进行操作会提示Access Denied。

CMD使用多层命令结构,所有的命令以bcecmd开头,[options]表示BCE CMD支持的选项,<service>表示CMD所支持的服务,如BOS等,每个服务拥有多个特定的子命令。

$ bcecmd [options] [<service> <command> [parameters [options]]]

参数解释

参数项 取值 说明
options BCE通用的Option,取值为-c-v-h-d--conf-path -
service 取值为bosbosprobe bosprobe的使用方法请查看bosprobe
command 取值为:mbrblscprm 各命令的作用请参见命令功能描述。
parameters 取值为<local-path><bos-path> <bos-path>包含以下几种形式:
- BOS根目录:bos:/
- BOS Bucket根目录:bos:/<bucket-name>
- BOS Bucket下文件夹:bos:/<bucket-name>/<folder-name>/
- BOS Bucket下的Object:bos:/<bucket-name>/<folder-name>/<object-key> 注: 在<bos-path>中Bucket后面如果出现连续多个"/"会处理成一个"/"。
参数的值可以是简单的字符串或数字,如$ bcecmd bos cp localfile.txt bos:/mybucket/remotefile.txt。如果字符串中包含空格及特殊字符,在Linux中需要使用单引号,在Windows中需要使用双引号包围。如$ bcecmd bos cp 'my object 1' 'bos:/mybucket/my object 1'
+options BOS命令的Option,取值为-r-a-s等。 BOS各命令可配置的option不一样,详细的使用方法请参见各命令行解释。

CMD通用Option

  • 查看帮助:可以在任意命令后面添加-h--help来查看该命令的帮助信息。

    $ bcecmd -h
    $ bcecmd bos -h
    $ bcecmd bos ls --help
    
  • 查看、设置AK、SK等配置信息:-c/--configure

    $ bcecmd -c [<conf-path>]
    
  • 查看版本信息:-v/--version

    $ bcecmd -v
    
  • 查看debug信息:-d/--debug

    $ bcecmd -d bos ls bos:/bce-test/pre/
    

    注意: -d/--debug命令不能单独使用,必须与bos命令结合使用。

  • 使用指定配置文件:--conf-path

    $ bcecmd --conf-path ./conf-sample/ bos ls bos:/bce-test/pre/
    

    注意: 不使用--conf-path命令时,默认使用用户主目录~/.go-bcecli下的配置。

Bucket管理

创建Bucket

描述: 创建一个空的Bucket。

命令格式: $ bcecmd bos mb bos:/<bucket-name> [--region REGION]

说明:

  • 仅在“自动切换域名”功能开启后,您才能为Bucket指定所属地域。
  • 如果您没有指定Bucket所属地域,我们将使用您在CMD中配置的默认地域(即使用bcecmd -c配置的默认地域,如果您没有配置默认地域,CMD的默认地域将为bj)。

示例:

  • 不指定创建Bucket所属地域

    操作示例:

    $ bcecmd bos mb bos:/mybucket

    返回示例:

    Make bucket: mybucket in region **

  • 指定创建Bucket所属地域

    操作示例:

    $ bcecmd bos mb bos:/mybucket -r bj

    返回示例:

    Make bucket: mybucket in region bj

Bucket删除

描述: 删除一个Bucket,要求Bucket内无Object和未完成的三步上传Part。

命令格式: $ bcecmd bos rb bos:/<bucket-name> [-y, --yes] [-f, --force]

说明:

  • -y, --yes:使用该选项时,默认跳过确认步骤。
  • -f, --force:如果需要删除非空Bucket,可以使用-f/--force选项进行强制删除。使用该选项时,Bucket不为空也可以将该Bucket及其内所有Objects一起删除。

操作示例: $ bcecmd bos rb bos:/mybucket --force

返回示例:

Do you really want to REMOVE bucket bos:/bce-test and all objects in it? (Y/N) **Y**
Delete object: bos:/mybucket/test1.txt
Delete object: bos:/mybucket/test2.txt
Remove bucket: mybucket

罗列Bucket

描述: 罗列Bucket列表。

命令格式: $ bcecmd bos ls [bos:/]

操作示例: $ bcecmd bos ls

返回示例:

2015-08-12 10:20:58       bj  bce-doc
2015-08-12 10:21:09       bj  bce-sdk
2016-07-19 11:11:41       bj  bce-temp
2016-07-19 10:53:37       bj  bce-test

说明:示例输出第一列代表bucket的创建日期,第二列代表创建时间,第三列代表bucket所在区域,第四列表示Bucket的名称。

管理Object

Object上传

描述: BOS CMD支持同步上传、单文件上传、批量上传三种方式,上传过程中可以指定Object的存储类型是标准存储、低频存储、还是冷存储。此外BOS CMD还支持:

  • 对于大于32M的文件自动分块并发上传,并设置上传的并发连接数等。

当您需要在本地和BOS之间进行数据上传,同步上传(sync)是最方便的上传命令。同步上传默认支持批量操作,可以将本地目录同步到BOS。如果BOS端已经有名称相同且修改时间比本地文件新,同步上传会忽略此文件,只同步新文件或有改动的文件。
sync命令会同时列举本地和BOS侧文件, 对于不同情况分别执行以下动作:

  • 对于新增的文件(本地的某个文件BOS侧没有):上传
  • 对于已上传但是有改动的文件(本地文件的更新时间晚于BOS侧文件的创建时间, 或者本地文件的大小跟BOS侧不一致):覆盖上传
  • 对于已上传且没改动的文件:跳过不处理
  • 对于已上传但是在本地没有的文件:根据--delete参数来做不同的处理。

命令格式:

  • 同步上传:$ bcecmd bos sync <local_dir> bos:/<bucket_name>/[prefix] [--exclude EXCLUDE] [--include INCLUDE] [--delete] [--exclude-delete EXCLUDE-DELETE] [--dryrun] [--yes] [--quiet] [--storage-class STORAGE-CLASS] [--sync-type SYNC-TYPE] [--concurrency CONCURRENCY] [--restart]

    参数说明:

    • local_dir必须为本地目录,不能为单个文件。也不支持通配符匹配的语法,如<local_dir>/* 以及<local_dir>/prefix*等。
    • 在windows和linux系统下, 硬链接文件和普通文件的处理方式一样,软链接文件夹和普通文件夹的处理方式一样,但软链接文件(指向文件的软链接)和普通文件的处理方式不一样,sync会操作软链接文件指向的文件而不是软链接文件本身,但是软链接本身被删除, 也会触发sync。
    • --exclude:执行本地到bos的sync的时候, 需要跳过的文件, 支持通配符*和多项配置,
      如要跳过tmp文件和当前目录所有子目录下的svn目录:--exclude ./*.tmp --exclude */.svn
    • --include:执行本地到bos的sync的时候, 只同步指定文件, 支持通配符*和多项配置,
      如只同步当前目录所有子目录下的log文件和html文件:--include ./*.log --include ./*.html
    • --delete:删除BOS有而本地没有的文件,使BOS和本地的数据完全一致。执行后默认会提示用户是否要执行删除。
    • --exclude-delete:此选项需要同 --delete 一起使用, 用于在删除本地文件时排除特定文件或目录, 具体用法请参考 --exclude的使用规则。
    • --dryrun:列出会执行的操作但不实际执行。
    • --yes:执行删除动作时不需要确认直接删除。
    • --quiet:同步上传但不输出任何中间过程。
    • --storage-class [STORAGE_CLASS]:通过storage-class参数指定同步上传的Object
      的存储类型。指定storage-class为STANDARD_IA或者COLD时表示存储为低频存
      储或者冷存储类型,指定的storage-class为STANDARD或者不指定storage-class时
      为标准存储。
    • --sync-type: 同步类型可以为 time-sizetime-size-crc32only-crc32, 默认为 time-size。 bcecmd 执行 sync 时首先会判断要同步的文件在目的端是否存在,如果不存在就会上传或者下载文件, 当源端和目的端都存在时, 就会根据同步类型来决定是否需要同步文件。
      time-size: 比较源端和目的端文件的修改日期和大小来判断是否同步,当源端文件的修改日期早于目的端文件时,不会同步文件;当源端文件的修改日期等于目的端文件的修改日期,且它们的大小相同时不同步文件, 否则同步;
      time-size-crc32: bcecmd 先使用 time-size 模式判断是否需要同步文件, 当time-size 输出结果为需要同步文件时, bcecmd 将比较源端和目的端文件的 crc32, 当crc32的值不同时才会同步文件;
      only-crc32: bcecmd 只会比较源端和目的端文件的crc32, 如果不同就会同步文件。
    • --concurrency: 用于设置 sync 命令并发上传下载的文件数。
    • --restart: 忽略断点续传,重头开始上传文件。

    注意

    • 当--delete 与过滤(include 或exclude)同时使用时,如果一个文件被过滤,尽管它同时存在于源端和目的端,
      它也会被删除。因为bcecmd只会比较未被过滤的文件。
    • 需要注意 BOS 在2018年1月之后才全面支持CRC32, 所以当 bcecmd sync-type 选择为time-size-crc32only-crc32时,如果bcecmd 未能从BOS获取到 object 的 CRC32信息时, bcecmd 将总是会同步这些文件。
  • 单文件上传:$ bcecmd bos cp <local-path> <bos-path> [--storage-class [STORAGE_CLASS]] [--restart] [--quiet] [--yes] [--disable-bar]

  • 批量上传:$ bcecmd bos cp <local-path> <bos-path> --recursive [--storage-class [STORAGE_CLASS]] [--restart] [--quiet] [--yes] [--disable-bar]

    说明:

    • 执行bcecmd bos cp /tmp/file1 bos:/bucket/file2命令时,file2可以与file1相同,如果file2在bucket中已存在则会被覆盖。
    • 执行bcecmd bos cp /tmp/file bos:/bucket/命令时,自动使用本地文件名作为bos端文件名,如果已存在重名文件会被覆盖。
    • 执行bcecmd bos cp /tmp/file bos:/bucket/prefix[/] -r命令时,本地为文件时会退化为单文件上传,bos路径结尾为”/”时prefix会当做目录,新文件保存在prefix下一级;结尾不为"/"时会当做object名直接上传。
    • 执行bcecmd bos cp /tmp/dir/ bos:/bucket/prefix[/] -r命令时,本地为目录时bos路径结尾不论是否有”/”都会以prefix为目录名在bos端新建目录; 并将dir中Object全部拷贝到prefix目录下。
    • 执行批量上传时,local-path只能是本地目录且以"/"结尾,bos-path必须为bucket/prefix。
    • 上传Object过程中可以通过storage-class参数指定Object的存储类型,storage-class默认为STANDARD即标准存储,storage-class为STANDARD_IA或者COLD时表示存储为低频存储或者冷存储类型。如果storage-class输入参数错误依旧会按照STANDARD进行存储,不会提示错误信息。
    • --disable-bar:禁止使用进度条。

示例:

  • 同步当前目录下的sample目录到bos:/bce-test/test下

    操作示例: bcecmd bos sync ./sample/ bos:/bce-test/test

    返回示例:

    Upload: sample/BOS_Batch_Delete.png to bos:/bce-test/test/BOS_Batch_Delete.png
    Upload: sample/sample.log to bos:/bce-test/test/sample.log
    
  • 列出会执行的同步操作但不执行

    操作示例: bcecmd bos sync ./sample/ bos:/bce-test/test --dryrun

    返回示例:

    Upload: sample/BOS_DataImport.png to bos:/bce-test/test/BOS_DataImport.png
    
  • 同步上传但不输出任何中间过程

    操作示例:bcecmd bos sync ./sample/ bos:/bce-test/test --quiet

    返回示例: 无返回

  • 同步sample目录到bos:/bce-test/test上且删除BOS有而本地没有的文件

    操作示例:bcecmd bos sync ./sample/ bos:/bce-test/test --delete

    返回示例:

    Delete object: bos:/bce-test/test/sample.log
    
  • 同步sample目录到bos:/bce-test/test上并存储为低频存储类型

    操作示例: bcecmd bos sync ./sample/ bos:/bce-test/test --storage-class STANDARD_IA

    返回示例:

    Upload: sample/BOS_DataImport.png to bos:/bce-test/test/BOS_DataImport.png
    
  • 同步sample目录到bos:/bce-test/test上并存储为冷存储类型

    操作示例: bcecmd bos sync ./sample/ bos:/bce-test/test --storage-class COLD

    返回示例:

    Upload: sample/BOS_DataImport.png to bos:/bce-test/test/BOS_DataImport.png
    
  • 单文件上传

    操作示例:

    $ bcecmd bos cp text.txt bos:/mybucket/test.txt
    

    返回示例:

    Upload: test.txt to bos:/mybucket/test.txt
    
  • 批量上传

    操作示例:

    $ bcecmd bos cp ./temp/ bos:/bce-test -r
    

    返回示例:

    Upload: /home/users/username/temp/BAE.png to bos:/bce-test/BAE.png
    Upload: /home/users/username/tem/CreatePolicy.png to bos:/bce-test/CreatePolicy.png
    Upload: /home/users/username/tem/BAE_Pro.png to bos:/bce-test/BAE_Pro.png
    Upload: /home/users/username/tem/BCD.png to bos:/bce-test/BCD.png
    Upload: /home/users/username/tem/04Eng.png to bos:/bce-test/04Eng.png
    [5] object uploaded.
    
  • 上传Object并存储为低频存储类型

    操作示例:

    $ bcecmd bos cp text.txt bos:/mybucket/test.txt --storage-class STANDARD_IA
    

    返回示例:

    Upload: test.txt to bos:/mybucket/test.txt
    
  • 上传Object并存储为冷存储类型

    操作示例:

    $ bcecmd bos cp text.txt bos:/mybucket/test.txt --storage-class COLD
    

    返回示例:

    Upload: test.txt to bos:/mybucket/test.txt
    

Object下载

描述: BOS CMD支持同步下载、单个文件下载和批量文件下载。

同步下载默认支持批量操作,可以将BOS同步到本地目录。如果本地已经有同名文件,且本地文件修改时间晚于BOS上的同名文件,同步上传会忽略这些文件,只同步新文件或有改动的文件。

sync命令会同时列举本地和BOS侧文件, 对于不同情况分别执行以下动作:

  • 对于新增的文件(BOS的某个文件本地没有):下载
  • 对于已下载但是有改动的文件(BOS侧文件的创建时间晚于本地文件的更新时间, 或者BOS侧文件的大小跟本地不一致):覆盖下载
  • 对于已下载且没改动的文件:跳过不处理
  • 对于已下载但是BOS侧没有的文件:根据--delete参数来做不同的处理。

命令格式:

  • 同步下载Object: $ bcecmd bos sync <bos-dir> <local-dir> [--exclude EXCLUDE] [--include INCLUDE] [--delete] [--exclude-delete EXCLUDE-DELETE] [--dryrun] [--yes] [--quiet] [--sync-type SYNC-TYPE] [--download-tmp-path DOWNLOAD-TMP-PATH] [--concurrency CONCURRENCY] [--restart]

    说明:

    • 同步下载中,local-dir和bos-dir必须为目录,不能为单个文件。
    • --exclude:执行bos到本地的sync的时候, 需要跳过的文件, 支持通配符*和多项配置,
      如要跳过bucket sample下tmp文件和所有目录下的svn目录:--exclude bos:/sample/*.tmp --exclude bos:/sample/*/.svn/*
    • --include:执行bos到本地的sync的时候, 只同步指定文件, 支持通配符*和多项配置,
      如只同步bucket sample下的log文件和html文件: --include bos:/sample/*.log --include bos:/sample/*.html
    • --delete:删除本地有而BOS没有的文件,使本地和BOS的数据完全一致。执行后默认会提示用户是否要执行删除。
    • --exclude-delete:此选项需要同 --delete 一起使用,用于在删除在目的端存在而在源端不存在的文件时排除目的端特定文件或目录,具体用法请参考 --exclude的使用规则。
    • --dryrun:列出会执行的操作但不实际执行。
    • --yes:执行删除动作时不需要确认直接删除。
    • --quiet:同步下载但不输出任何中间过程。
    • --sync-type: 同步类型可以为 time-sizetime-size-crc32only-crc32, 默认为 time-size。 bcecmd 执行 sync 时首先会判断要同步的文件在目的端是否存在,如果不存在就会上传或者下载文件, 当源端和目的端都存在时, 就会根据同步类型来决定是否需要同步文件。
      time-size: 比较源端和目的端文件的修改日期和大小来判断是否同步,当源端文件的修改日期早于目的端文件时,不会同步文件;当源端文件的修改日期等于目的端文件的修改日期,且它们的大小相同时不同步文件, 否则同步;
      time-size-crc32: bcecmd 先使用 time-size 模式判断是否需要同步文件, 当time-size 输出结果为需要同步文件时, bcecmd 将比较源端和目的端文件的 crc32, 当crc32的值不同时才会同步文件;
      only-crc32: bcecmd 只会比较源端和目的端文件的crc32, 如果不同就会同步文件。
    • --download-tmp-path:用于手动指定断点下载时用于保存临时文件的目录, 如果不指定, 默认使用执行命令时所在目录。
    • --concurrency: 用于设置 sync 命令并发上传下载的文件数。
    • --restart: 忽略断点续传,重头开始上传文件。

    注意

    • 当--delete 与过滤(include 或exclude)同时使用时,如果一个文件被过滤,尽管它同时存在于源端和目的端,
      它也会被删除。因为bcecmd只会比较未被过滤的文件。
    • 需要注意 BOS 在2018年1月之后才全面支持CRC32, 所以当 bcecmd sync-type 选择为time-size-crc32only-crc32时,如果bcecmd 未能从BOS获取到 object 的 CRC32信息时, bcecmd 将总是会同步这些文件。
  • 下载单个Object:$ bcecmd bos cp <bos-path> <local-path> [--restart] [--storage-class STORAGE-CLASS] [--download-tmp-path DOWNLOAD-TMP-PATH] [--quiet] [--yes] [--disable-bar]

  • 批量下载Object:$ bcecmd bos cp <bos-path> <local-path> --recursive [--restart] [--storage-class STORAGE-CLASS] [--download-tmp-path DOWNLOAD-TMP-PATH] [--quiet] [--yes] [--disable-bar]

    说明:

    • 执行bcecmd bos cp bos:/bucket/file /tmp/file命令时,本地文件名可以任意指定,若本地文件存在会提示是否覆盖。
    • 执行bcecmd bos cp bos:/bucket/file /tmp/命令时,本地文件名会自动存为bos端文件名,若存在会提示是否覆盖。
    • 执行bcecmd bos cp bos:/bucket/file /tmp/ -r命令时,bos端为文件时会退化为单个文件下载,若存在会提示是否覆盖。
    • 执行bcecmd bos cp bos:/bucket/prefix/ /tmp/ -r命令时,本地路径如果为一个已存在的文件会报错,本地目录不存在时会创建。
    • 执行批量下载时,local-path只能是本地目录,bos-path必须为bucket/prefix。如果bos路径为Object,则为单个Object下载。
    • --restart: 忽略断点续传,重头开始下载文件。
    • --storage-class:下载时不管是否指定参数storage-class,都不影响下载,该参数会被自动忽略,不起作用。
    • --download-tmp-path:用于手动指定断点下载时用于保存临时文件的目录, 如果不指定, 默认使用执行命令时所在目录。
    • --quiet:同步下载但不输出任何中间过程。
    • --yes:执行删除动作时不需要确认直接删除。
    • --disable-bar: 不显示进度条。

示例:

  • 同步下载bos:/mybucket/pre/下文件到当前目录下的temp目录

    操作示例:

    $ bcecmd bos sync bos:/mybucket/pre/ ./temp/
    

    返回示例:

    Download: bos:/mybucket/pre/sts1.png to /home/users/username/temp/sts1.png
    Download: bos:/mybucket/pre/sts2.png to /home/users/username/temp/sts2.png
    Sync done: bos:/mybucket/pre/ to ./temp/, [2] success [0] failure
    
  • 下载Object

    操作示例:

    $ bcecmd bos cp bos:/mybucket/test.txt text.txt
    

    返回示例:

    Download: bos:/mybucket/test.txt to test.txt
    
  • 批量下载Object

    操作示例:

    $ bcecmd bos cp bos:/mybucket/pre/ temp -r
    

    返回示例:

    Download: bos:/mybucket/pre/sts1.png to /home/users/username/tmp/sts1.png
    Download: bos:/mybucket/pre/sts2.png to /home/users/username/tmp/sts2.png
    [2] objects downloaded.
    

拷贝Object

描述: BOS CMD支持在bucket间拷贝文件,支持同步拷贝、单个文件拷贝和批量文件拷贝。

同步拷贝默认支持批量操作,如果目的Bucket已经有同名文件,同步拷贝会忽略这些文件,只同步新文件或有改动的文件。

sync命令会同时列举源Bucket和目的Bucket的文件, 对于不同情况分别执行以下动作:

  • 对于新增的文件(源Bucket的某个文件目的Bucket没有):拷贝
  • 对于已拷贝但是有改动的文件(源Bucket文件的创建时间晚于目的Bucket文件的更新时间, 或者源Bucket侧文件的大小跟目的Bucket不一致):覆盖拷贝
  • 对于已拷贝且没改动的文件:跳过不处理
  • 对于已拷贝但是源Bucket没有的文件:根据--delete参数来做不同的处理。

命令格式:

  • 同步拷贝Object:$ bcecmd bos sync <bos-dir> <bos-dir> [--exclude EXCLUDE] [--include INCLUDE] [--delete] [--exclude-delete EXCLUDE-DELETE] [--dryrun] [--yes] [--quiet] [--storage-class STORAGE-CLASS] [--sync-type SYNC-TYPE] [--concurrency CONCURRENCY] [--restart]

    说明:

    • 同步拷贝中,bos-dir必须为目录,不能为单个文件。
    • --exclude:执行bos到bos的sync的时候, 需要跳过的文件, 支持通配符*和多项配置,
      如要跳过bucket source下tmp文件和所有目录下的svn目录: --exclude bos:/source/*.tmp --exclude bos:/source/*/.svn/*
    • --include:执行bos到bos的sync的时候, 只同步指定文件, 支持通配符*和多项配置,
      如只同步bucket source下的log文件和html文件: --include bos:/source/*.log --include bos:/source/*.html
    • --delete:删除源Bucket有而目的Bucket没有的文件,使源和目的Bucket的数据完全一致。执行后默认会提示用户是否要执行删除。
    • --exclude-delete:此选项需要同 --delete 一起使用,用于在删除在目的端存在而在源端不存在的文件时排除目的端特定文件或目录,具体用法请参考 --exclude的使用规则。
    • --dryrun:列出会执行的操作但不实际执行。
    • --yes:执行删除动作时不需要确认直接删除。
    • --quiet:同步上传但不输出任何中间过程。
    • --storage-class [STORAGE_CLASS]:通过storage-class参数指定同步上传的Object
      的存储类型。指定storage-class为STANDARD_IA或者COLD时表示存储为低频存
      储或者冷存储类型,指定的storage-class为STANDARD或者不指定storage-class时
      为标准存储。
    • --sync-type: 同步类型可以为 time-sizetime-size-crc32only-crc32, 默认为 time-size。 bcecmd 执行 sync 时首先会判断要同步的文件在目的端是否存在,如果不存在就会同步文件, 当源端和目的端都存在时, 就会根据同步类型来决定是否需要同步文件。
      time-size: 比较源端和目的端文件的修改日期和大小来判断是否同步,当源端文件的修改日期早于目的端文件时,不会同步文件;当源端文件的修改日期等于目的端文件的修改日期,且它们的大小相同时不同步文件, 否则同步;
      time-size-crc32: bcecmd 先使用 time-size 模式判断是否需要同步文件, 当time-size 输出结果为需要同步文件时, bcecmd 将比较源端和目的端文件的 crc32, 当crc32的值不同时才会同步文件;
      only-crc32: bcecmd 只会比较源端和目的端文件的crc32, 如果不同就会同步文件。
    • --concurrency: 用于设置 sync 命令并发拷贝的文件数。
    • --restart: 忽略断点续传,重头开始拷贝文件。

    注意

    • 当--delete 与过滤(include 或exclude)同时使用时,如果一个文件被过滤,尽管它同时存在于源端和目的端,它也会被删除。因为bcecmd只会比较未被过滤的文件。
    • 需要注意 BOS 在2018年1月之后才全面支持CRC32, 所以当 bcecmd sync-type 选择为time-size-crc32only-crc32时,如果bcecmd 未能从BOS获取到 object 的 CRC32信息时, bcecmd 将总是会同步这些文件。
  • 拷贝单个Object:$ bcecmd bos cp <bos-path> <bos-path> [--restart] [--storage-class STORAGE-CLASS] [--quiet] [--yes] [--disable-bar]

  • 批量拷贝Object:$ bcecmd bos cp <bos-path> <bos-path> --recursive [--restart] [--storage-class STORAGE-CLASS] [--quiet] [--yes] [--disable-bar]

    说明:

    • 执行bcecmd bos cp bos:/bucket/obj1 bos:/bucket/obj2命令时,复制的两个路径相同时会报错,目的路径若已存在会被覆盖。
    • 执行bcecmd bos cp bos:/bucket/obj1 bos:/bucket/prefix/命令时,obj1会被拷贝到prefix目录下,目的路径必须以“/”结尾,否则会当做一个新文件名新建一个文件。
    • 执行bcecmd bos cp bos:/bucket/obj1 bos:/bucket/prefix/ -r命令时,源路径为单个文件时退化为单个文件拷贝,obj1会被拷贝到prefix目录下。
    • 执行bcecmd bos cp bos:/bucket/prefix1/ bos:/bucket/prefix2/ -r命令,实现目录到目录的拷贝,两个路径都必须以“/”的结尾;若目的路径结尾不以“/”结尾会当做单个文件从而报错。
    • 执行批量拷贝时,bos-path必须为bucket/prefix。
    • 用户必须具备对源bucket的读权限和目标bucket的写权限。

示例:

  • 同步拷贝bos:/mybucket/pre/下文件到bos:/mybucket2/pre/

    操作示例:

    $ bcecmd bos sync bos:/mybucket/pre/ bos:/mybucket2/pre/
    

    返回示例:

    Copy: bos:/mybucket/pre/sts1.png to bos:/mybucket2/pre/sts1.png
    Copy: bos:/mybucket/pre/sts2.png to bos:/mybucket2/pre/sts2.png
    Sync done: bos:/mybucket/pre/ to bos:/mybucket2/pre/, [2] success [0] failure
    
  • 拷贝单个Object

    操作示例:

    $ bcecmd bos cp bos:/mybucket/test.txt bos:/mybucket2/test.txt
    

    返回示例:

    Copy: bos:/mybucket/test.txt to bos:/mybucket2/test.txt
    
  • 批量拷贝Object

    操作示例:

    $ bcecmd bos cp bos:/mybucket/pre1/ bos:/bce-test/pre/ -r
    

    返回示例:

    Copy: bos:/mybucket/pre1/s1.png to bos:/bce-test/pre/s1.png
    Copy: bos:/mybucket/pre1/s2.png to bos:/bce-test/pre/s2.png
    [2] objects remote copied.
    

罗列Object

描述: ls命令可以列出一个Bucket内的不超过1000条Objects,可以通过指定Prefix来过滤结果。ls会自动以/作为delimiter来达到模拟文件夹的效果。

命令格式: $ bcecmd bos ls bos:/<bucket-name>/[prefix]

操作示例: bcecmd bos ls bos:/mybucket/web

返回示例:

PRE  pre/
2016-04-01 16:43:01            8698     STANDARD  web_bos.png
2016-04-01 16:41:49           17188     STANDARD  web_server_bos.png
2016-04-01 16:43:53           24620  STANDARD_IA  webtobos_cors.png
2016-04-01 16:45:53           24623         COLD  cold_abc.png

说明

  • -a, --all:超过1000个Object时会全部显示出来。
  • -r, --recursive:不显示目录,直接显示下面的Object。
  • -s, --summerize:显示个数以及总大小等统计信息。
  • 示例输出第一列代表Object的创建日期,第二列代表创建时间,第三列代表Object的大小(以Byte为单位),第四列表示Object的存储类型,第五列表示Object的名称。
  • pre/表示为文件夹,不会显示创建时间及大小信息。

获取Object的URL

描述: gen_signed_url命令可以获取指定Object的URL,根据提供的URL可以下载Object。

命令格式 $ bcecmd bos gen_signed_url bos:/<bucket-name>/<object-key> [-eTIME]

说明:

  • 获取的URL地址输入浏览器中可以直接下载Object。生成URL前,需要确认配置的AK/SK与Bucket对应账户的AK/SK一致,否则生成的URL无效不能正常下载Object。

  • -e: 指定URL过期时间(单位秒),值必须大于等于-1,其中-1表示URL永久有效。

  • 不指定过期时间时默认过期时间为1800秒。

注意:

参数-e 与过期时间之前不能有空格。

示例:

  • 不指定过期时间

    操作示例:

    $ bcecmd bos gen_signed_url bos:/bce-test/test/BOS_DataImport.png
    

    返回示例:

    http://bj.bcebos.com/bce-test/test/BOS_DataImport.png?authorization=bce-auth-v1%2Fd35a0b8750114e49b3567e0b0542c2f1%2F2016-08-25T02%3A03%3A57Z%2F1800%2F%2F96d77180ec2cb7e8de522c15ca42bf67c30bae0edb47bad495fe8e7953794a4f
    
  • 指定过期时间为100秒

    操作示例:

    $ bcecmd bos gen_signed_url bos:/bce-test/test/BOS_DataImport.png -e100
    

    返回示例:

    http://bj.bcebos.com/bce-test/test/BOS_DataImport.png?authorization=bce-auth-v1%2F637986f41b0046248e3a333817371502%2F2017-08-31T03%3A19%3A42Z%2F100%2F%2F3e77accca7f0206460c662b0a9596b7ec353599214d42b124bb797a48da7359a
    
  • 指定URL永久有效

    操作示例:

    $ bcecmd bos gen_signed_url bos:/bce-test/test/BOS_DataImport.png -e-1
    

    返回示例:

    http://bj.bcebos.com/bce-test/test/BOS_DataImport.png?authorization=bce-auth-v1%2F637986f41b0046248e3a333817371502%2F2017-08-31T03%3A19%3A42Z%2F-12F%2F3e77accca7f0206460c662b0a9596b7ec353599214d42b124bb797a48da7359a
    

删除Object

命令格式:

  • 删除单个Object:$ bcecmd bos rm [-y, --yes] bos:/<bucket-name>/<object-key>
  • 批量删除Object:$ bcecmd bos rm [-y, --yes] [-r, --recursive] bos:/<bucket-name>/<prefix>

说明:

  • -y, --yes: 使用该选项时跳过确认步骤。
  • -r, --recursive:批量删除object。

示例:

  • 删除单个Object

    操作示例:

    $ bcecmd bos rm bos:/bce-temp/s1.png
    

    返回示例:

    Do you really want to REMOVE object bos:/bce-temp/s1.png? (Y/N) **Y**
    Delete object: bos:/bce-temp/s1.png
    
  • 批量删除Object

    操作示例:

    $ bcecmd bos rm bos:/bce-test/pre/ -r
    

    返回示例:

    Delete object: bos:/bce-test/pre/s1.png
    Delete object: bos:/bce-test/pre/s2.png
    [2] objects removed on remote.
    

BOSAPI接口管理

BOSAPI接口管理包括Bucket ACL、Bucket默认存储类型、生命周期管理和日志管理。命令行通用格式为bcecmd bosapi [--help]

设置 Bucket ACL

描述: 配置Bucket ACL有两种方法: 1. 使用CannedAcl; 2. 通过上传ACL配置文件设置Bucket ACL。

命令格式:

bcecmd bosapi put-bucket-acl --bucket-name BUCKET-NAME [--acl-config-file ACL-CONFIG-FILE] [--canned CANNED]

说明:

  • 使用--acl-config-file 指定ACL配置文件,ACL配置文件格式请参考 Bucket权限控制
  • 使用 --canned 设置 CannedACL,当前支持的CannedAcl包括 private(私有)、public-read(公共读)、public-read-write(公共读写);
  • --acl-config-file--canned 不能同时使用;
  • 配置CannedACL时,如果配置失败则会打印错误信息,如果配置成功则不会输出任何消息;
  • 通过上传ACL配置文件设置Bucket ACL时,如果设置成功会打印ACL配置信息,失败则会打印ACL配置文件的内容和错误信息。

示例:

  • 使用CannedAcl方式的权限控制

    操作示例:

    $ bcecmd bosapi put-bucket-acl --bucket-name bucket1 --canned private
    

    返回示例:

  • 通过上传ACL配置文件设置Bucket ACL

    操作示例:

    $ bcecmd bosapi put-bucket-acl --bucket-name bucket1 --acl-config-file acl-config.json
    

    返回示例:

    {
        "accessControlList": [
          {
            "grantee": [
              {
                "id": "e13b12d213213213232323f492323"
              }
            ],
            "permission": [
                "READ"
            ]
          }
        ]
    }
    

获取Bucket ACL

描述: 获取Bucket 的ACL配置。

命令格式:

bcecmd bosapi get-bucket-acl --bucket-name BUCKET-NAME

操作示例:

```
bcecmd bosapi get-bucket-acl --bucket-name bucket1
```

返回示例:

```
{
  "accessControlList": [
    {
      "grantee": [
        {
          "id": "e13b12d213213213232323f492323"
        }
      ],
      "permission": [
        "FULL_CONTROL"
      ],
      "condition": {
        "ipAddress": null,
        "referer": {
          "stringLike": null,
          "stringEquals": null
        }
      }
    }
  ],
  "owner": {
    "id": "e13b12d213213213232323f492323"
  }
}
```

设置生命周期

描述: 按照提供的生命周期管理文件为指定的Bucket设置生命周期管理规则,或生成生命管理文件模板。

命令格式:

  • 生成Transition的配置模板:bcecmd bosapi put-lifecycle --template
  • 按照指定的配置文件为Bucket设置生命周期管理规则: bcecmd bosapi put-lifecycle --lifecycle-config-file LIFECYCLE_CONFIG_FILE --bucket-name BUCKET_NAME

示例:

  • 生成Transition的配置模板

    操作示例:

    $ bcecmd bosapi put-lifecycle --template
    

    返回示例:

    {
      "rule": [
        {
          "action": {
            "name": "Transition",
            "storageClass": "STANDARD_IA"
          },
          "status": "enabled",
          "resource": [
            "${bucket_name}/${prefix}/*"
          ],
          "id": "sample-id",
          "condition": {
            "time:": {
              "dateGreaterThan": "$(lastModified)+P30D"
            }
          }
        }
      ]
    }
    
  • 按照配置文件1.txt为Bucket1设置生命周期管理规则

    操作示例:

    bcecmd bosapi put-lifecycle --lifecycle-config-file lifecycle_bj.json --bucket-name bucket1
    

    返回示例:

    {
      "rule": [
        {
          "status": "enabled",
          "action": {
            "name": "Transition",
            "storageClass": "STANDARD_IA"
          },
          "resource": [
            "bucket1/*"
          ],
          "id": "sample-rule-transition",
          "condition": {
            "time": {
              "dateGreaterThan": "$(lastModified)+P180D"
            }
          }
        }
      ]
    }
    

    说明:设置成功后会返回生命周期配置文件,否则报错。

获取生命周期配置

描述: 获取某个指定Bucket的生命周期配置。

命令格式: bcecmd bosapi get-lifecycle --bucket-name BUCKET_NAME

操作示例: bcecmd bosapi get-lifecycle --bucket-name bucket1

返回示例:

{
  "rule": [
    {
      "action": {
        "name": "Transition",
        "storageClass": "STANDARD_IA"
      },
      "status": "enabled",
      "resource": [
        "bucket1/prefix1/*"
      ],
      "id": "sample-id",
      "condition": {
        "time:": {
          "dateGreaterThan": "$(lastModified)+P30D"
        }
      }
    }
  ]
}

删除生命周期配置

描述: 删除指定Bucket的生命周期管理配置。

命令格式: bcecmd bosapi delete-lifecycle --bucket-name BUCKET_NAME

操作示例: bcecmd bosapi delete-lifecycle --bucket-name bucket1

返回示例:

设置日志规则

描述: 为Bucket开启访问日志功能,并保存到指定Bucket的prefix中。

命令格式: bcecmd bosapi put-logging --target-bucket TARGET_BUCKET --target-prefix TARGET_PREFIX --bucket-name BUCKET_NAME

操作示例: bcecmd bosapi put-logging --target-bucket bucket2 --target-prefix log --bucket-name bucket1

返回示例:

获取日志规则

描述: 获取指定Bucket的访问日志配置情况。

命令格式: bcecmd bosapi get-logging --bucket-name BUCKET_NAME

操作示例: bcecmd bosapi get-logging --bucket-name bucket1

返回示例:

$ bcecmd bosapi get-logging --bucket-name bucket1
{
  "status": "enabled",
  "targetPrefix": "loggin/",
  "targetBucket": "bucket1"
}

删除日志规则

描述: 删除指定Bucket的访问日志设置。

命令格式: bcecmd bosapi delete-logging --bucket-name BUCKET_NAME

操作示例: bcecmd bosapi delete-logging --bucket-name b1

返回示例:

设置Bucket默认存储类型

描述: 设置某个指定Bucket的默认存储类型。

如果用户使用API、CLI或者SDK上传的Object未指定存储类型,则继承Bucket的默认存储类型。如果上传Object指定的存储类型和Bucket默认存储类型不一致时,以Object的存储类型为准。存储类型包含标准存储(STANDARD)、低频存储(STANDARD_IA)和冷存储(COLD)三种,具体使用场景和性能请参见分级存储,通过Console控制台设置Bucket默认存储类型请参见创建Bucket

命令格式:

bcecmd bosapi put-bucket-storage-class --bucket-name BUCKET_NAME --storage-class STORAGE_CLASS

操作示例:

bcecmd bosapi put-bucket-storage-class --bucket-name bucket1 --storage-class COLD`

返回示例: 无返回

查询Bucket默认存储类型

描述: 该命令用于查询某个Bucket的默认存储类型,Bucket默认存储类型包括标准存储、低频存储和冷存储。

命令格式:

bcecmd bosapi get-bucket-storage-class --bucket-name BUCKET_NAME

操作示例:

bcecmd bosapi get-bucket-storage-class --bucket-name bucket1

返回示例:

{
    "storageClass":"COLD"
}

BOS CMD版本变更记录

  • BCE CMD工具包 [2019-05-14] 版本号0.2.5

    变更记录:

    • 修改bcecmd返回值:上传、下载和 sync时,部分文件出错bcecmd也以1退出。
    • 修复Bug。
  • BCE CMD工具包 [2019-03-19] 版本号0.2.4

    变更记录:

    • 修复Bug和性能优化。
    • 为 bcecmd sync 添加三种同步模式(time-size, time-size-crc32 和 only-crc32)。
    • 为 bcecmd bos sync 添加 --exclude-delete--download-tmp-path 选项。
  • BCE CMD工具包 [2018-11-01] 版本号0.2.3

    变更记录:

    • 支持三步COPY。
    • 支持以断点续传方式上传、下载和拷贝大文件。
    • 为上传、下载和拷贝大文件添加进度条。
    • 支持bos前缀 bos://
  • BCE CMD工具包 [2018-05-29] 版本号0.2.2

    变更记录:

    • 支持用户手动配置分块上传的分块大小。
    • 优化CMD上传下载性能。
    • 修复Bug。
  • BCE CMD工具包 [2018-04-04] 版本号0.2.1

    变更记录:

    • 优化CMD性能。
    • 修复Bug。
  • BCE CMD工具包 [2018-02-01] 版本号0.2.0

    变更记录:

    • 支持BOSAPI接口,包含Bucket ACL、生命周期、日志和默认存储类型等管理接口。
    • 为sync 添加 exclude 和 include 过滤。
    • 修复Bug。
  • BCE CMD工具包 [2017-12-27] 版本号0.1

    变更记录:

    • Bucket创建和删除,Object的上传、下载、删除和拷贝等功能。
    • 支持sync操作。
    • 支持根据操作的Bucket自动切换域名。