BOS CLI

概述

为了方便用户使用百度智能云存储服务的API,BCE提供了可以通过命令行工具BCE CLI(Command Line Interface)调用BOS服务的方式,该工具基于BCE Python SDK实现。

BCE CLI当前只包含了BOS CLI的功能,所以下文都用BOS CLI代指BCE CLI。BOS CLI工具用于在命令行环境下使用BOS,可以通过CLI完成Bucket的创建和删除,Object的上传、下载、删除和拷贝等功能。

安装BOS CLI

前提条件

BOS CLI命令行工具(即BCE CLI)基于Python 2.7开发,根据操作系统安装相应Python 2.7,目前支持Windows 和Linux。

操作步骤

1.准备Python环境。

  • Windows环境

    Python官网下载python27.msi后,双击安装。

  • Linux环境

    以Ubuntu和Redhat为例:

    # Ubuntu
    $ sudo apt-get install python python-dev python-setuptools python-pip
    
    # Redhat
    $ sudo yum install python python-dev python-setuptools python-pip
    

说明: 安装完python后请先执行python -V查看python版本信息,确保python版本为2.7或之后的版本。对于使用百度智能云BCC Centos6.5系统的用户请按照后面的用百度智能云BCC Centos6.5系统的用户安装方法安装

2.安装BOS CLI工具。下载地址:CLI

  • Windows环境

    (1)解压CLI工具包。

    (2)在cmd中执行如下命令:

    cd $ BCE_PATH
    $ python setup.py install
    

    (3)将bce拷贝到用户需要执行程序的目录下方便使用。

    $ python $YOUR_DIR/bce
    
  • Linux环境

    (1)解压CLI工具包。

    $ unzip bce-cli-0.10.8.zip
    

    (2)将bcecli的库安装到系统的python目录下。

    $ python setup.py install
    

用百度智能云BCC Centos6.5系统的用户安装方法:

  1. 首先下载BCC Centos6.5镜像专用版CLI

  2. 解压CLI工具包。

    $ unzip bce-cli-0.10.8-centos6.5.zip
    
  3. 将bce-cli-0.10.8-centos6.5的安装目录加入环境变量中。

    export PATH=bce-cli-path:$PATH
    

    说明: 比如bce-cli-0.10.8-centos6.5.zip 解压后的路径为 /home/user1/bce-cli-0.10.8-centos6.5,您需要将路径/home/user1/bce-cli-0.10.8-centos6.5/加入环境变量中。

配置BOS CLI

通用配置

配置支持中文显示的CLI环境

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

$ export LANG=en_US.UTF-8

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

配置AK/SK、Region、Host信息

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

$ bce -c  [<conf-path>]
$ BOS Access Key ID [None]: Enter Your AK
$ BOS Secret Access Key [None]: Enter Your SK
$ BCE Security Token [None]: Enter Your Security Token
$ Default region name [bj]: Enter Your region
$ Default domain [bj.bcebos.com]: Enter Your host

说明:

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

注意:

  • 如果您使用的AK/SK是直接从百度智能云控制台的安全认证中获取的,请将Security Token设置为空或者none。

BOS相关配置

bce -c命令除了可以进行通用设置,还支持设置自动切换域名,另还支持设置BOS上传的相关属性,如断点续传有效期、是否使用HTTPS协议及分块上传的多线程数。

设置自动切换域名

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

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

$ bce -c [<conf-path>]
$ Default use auto switch domain [yes]:

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

设置断点续传有效期

CLI支持文件上传的断点续传。当某次上传因为意外中断,您可以重新执行命令,继续上一次的上传。断点续传功能需要设置有效期,有效期是指在该时间内,如出现中断,重新上传时可续传断点之后的部分;如超过该有效期,则会开始一次新的上传。

$ bce -c [<conf-path>]
$ Default breakpoint_file_expiration [7] days: Enter the period of keep breakpoint file

说明:续传有效期应设置为大于等于0的整数,设为为“-1”表示永久保留。缺省续传有效期为7天。

设置HTTPS协议上传

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

$ bce -c [<conf-path>]
$ Default use https protocol [no]:

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

设置分块并行上传线程数

大文件分块上传时,可以通过bce -c命令设置并行上传的线程数。

$ bce -c [<conf-path>]
$ Default multi upload thread num [10]:

说明:并行上传的线程数应设置为大于等于1的整数,缺省为10。

通过CLI使用BOS服务

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

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

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

参数解释

参数项 取值 说明
options BCE通用的Option,取值为-c-v-h-d--conf-path -
service 当前取值只能是bos -
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后面如果出现连续多个"/"会处理成一个"/"。
参数的值可以是简单的字符串或数字,如$ bce bos cp localfile.txt bos:/mybucket/remotefile.txt。如果字符串中包含空格及特殊字符,在Linux中需要使用单引号,在Windows中需要使用双引号包围。如$ bce bos cp 'my object 1' 'bos:/mybucket/my object 1'
+options BOS命令的Option,取值为-r-a-s等。 BOS各命令可配置的option不一样,详细的使用方法请参见各命令行解释。

CLI通用Option

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

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

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

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

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

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

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

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

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

Bucket管理

创建Bucket

描述: 创建一个空的Bucket。

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

说明:

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

示例:

  • 不指定创建Bucket所属地域

    操作示例:

    $ bce bos mb bos:/mybucket
    

    返回示例:

    Make bucket: mybucket
    
  • 指定创建Bucket所属地域

    操作示例:

    $ bce bos mb bos:/mybucket -r bj
    

    返回示例:

    Make bucket: mybucket
    

删除Bucket

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

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

说明:

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

操作示例: $ bce 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列表。

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

操作示例: $ bce 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 CLI支持同步上传、单文件上传、批量上传和流式上传四种方式,上传过程中可以指定Object的存储类型是标准存储还是低频存储冷存储。此外BOS CLI还支持:

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

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

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

命令格式:

  • 同步上传:$ bce bos sync <local_dir> bos:/<bucket_name>/[prefix] [--delete] [--yes] [--exclude] [--quiet] [--dryrun] [--storage-class [STORAGE_CLASS]] [--exclude-time TIME_RANGE] [--include-time TIME_RANGE]

    说明:

    • --dryrun:列出会执行的操作但不实际执行。
    • --quiet:同步上传但不输出任何中间过程。
    • --delete:删除BOS有而本地没有的文件,使BOS和本地的数据完全一致。执行后默认会提示用户是否要执行删除。
    • --yes:执行删除动作时不需要确认直接删除。
    • --exclude:执行本地到bos的sync的时候, 需要跳过的文件, 支持通配
      *和多项配置, 如要跳过tmp文件和当前目录所有子目录下的svn目录:
      --exclude ./*.tmp --exclude */.svn
    • --storage-class [STORAGE_CLASS]:通过storage-class参数指定同步上传的Object
      的存储类型。指定storage-class为STANDARD_IA或者COLD时表示存储为低频存
      储或者冷存储类型,指定的storage-class为STANDARD或者不指定storage-class时
      为标准存储。
    • local_dir必须为本地目录,不能为单个文件。也不支持通配符匹配的语法,如<local_dir>/* 以及<local_dir>/prefix*等。
    • --exclude-time:执行sync时,跳过在指定范围内创建或发生修改的文件,TIME-RANGE 表示您指定的时间区间,它的格式为 '[start, end)'。时间区间必须用 ‘[’ 和 ‘)’ 括起来(时间区间为左闭右右开,所以时间区间包含左边界时间,而不包含右边界时间)。
      例:如果您不想同步在2017-01-02 03:04:05到2017-01-03 03:04:05之间新生成或者发生修改的文件,您可以使用 --exclude-time '[2017-01-02 03:04:05, 2017-01-03 03:04:05)'。
    • --include-time: 执行sync时,只同步在指定时间范围内生成或发生修改的文件, 它的用法和--exclude-time相同。
    • --exclude-time 和 --include-time 不能同时使用。

    时间区间格式说明:

    时间区间的格式为'[start, end)',开始时间和结束时间可以是相对时间或绝对时间,也可以为空,但是不能同时为相对时间也不能同时为空。时间区间的具体格式如下:

    时间格式 说明
    开始时间或结束时间为空 如果开始时间为空,表示开始时间无穷小。如果结束时间为空,表示结束时间无穷大。例: '[, end]'表示开始时间为无穷小, '[start, ]' 表示结束时间无穷大。
    'now' 此变量为cli定义的魔法变量,表示当前时间。 例:如果现在是北京时间 2017-10-18 14:23:35, 那么时间区间'[2017-10-01 00:00:00, now)' 表示从2017-10-01 00:00:00 到2017-10-18 14:23:35这个时间范围(由于区间是左闭右开,所以不包含当前时间)。
    'midnight' 和'now‘一样,此变量为cli中定义的魔法变量,表示今天晚上的24:00:00。
    本地时间 本地时间的格式为 'YYYY-mm-DD HH:MM:SS', 比如2017-10-01 00:00:00。
    UTC时间 UTC时间的格式为 'YYYY-mm-DDTHH:MM:SSZ', 比如2017-01-02T23:04:54Z。
    时间戳 可以用时间戳表示开始时间或者结束时间。
    相对时间 遵循ISO8601中对时间段的表示,具体格式为 'PnnYnnMnnWnnDTnnHnnMnnS'(注意:并不是所有单元都需要,比如 P1D表示一天, 更多信息请参考 ISO8601)。 相对时间可以与'now'和'midnight'一起组成绝对时间, 比如'midnight-P1D'表示昨天晚上24:00:00。当开始时间为相对时间时,比如您指定的时间区间为 [duration, end), 其中duration表示相对时间, end表时间区间的结束时间 (由于时间区间必须包含一个绝对时间,所以end必须为绝对时间),那么此时间区间的开始时间应该为start = end - duration,结束时间为 end。同理,当结束时间时为相对时间时,如果开始时间为start,那么时间区间的结束时间为end = start + duration
  • 单文件上传:$ bce bos cp <local-path> <bos-path> [--storage-class [STORAGE_CLASS]]

  • 批量上传:$ bce bos cp <local-path> <bos-path> --recursive [--storage-class [STORAGE_CLASS]]
  • 流式上传: $ bce bos cp - <bos-path> [--storage-class [STORAGE_CLASS]]

BOS的四种上传方式都支持大文件断点续传功能,大文件续传的详细操作如下:

  1. 设定续传有效期:

    $ bce -c
    
    $ Default breakpoint_file_expiration [7] days: Enter the period of keep breakpoint file
    

    说明:续传有效期应设置为大于等于0的整数,设为为“-1”表示永久保留。

  2. 当出现传输中断后,重新执行一次上传命令,即可实现断点续传。如需要忽略断点续传,重头开始上传文件,可以通过在命令里增加--restart参数实现。

说明:

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

示例:

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

    操作示例: bce 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
    
  • 列出会执行的同步操作但不执行

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

    返回示例:

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

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

    返回示例: 无返回

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

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

    返回示例:

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

    操作示例: bce 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上并存储为冷存储类型

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

    返回示例:

    Upload: sample/BOS_DataImport.png to bos:/bce-test/test/BOS_DataImport.png
    

    说明:当没有文件触发sync操作时, 无返回。在windows和linux系统下, 硬链接文件和普通文件的处理方式一样,软链接文件夹和普通文件夹的处理方式一样,但软链接文件(指向文件的软链接)和普通文件的处理方式不一样。windows系统中当sync包含软链接文件的目录时, 软链接文件每次都会触发sync执行上传。linux系统下只有当软链接文件指向的文件有更改操作或者软链接文件本身被删除, 才会触发sync。

  • 同步当前目录下的sample目录到bos:/bce-test/test下, 但是只同步今天生成或发生修改的文件

    操作示例: bce bos sync ./sample/ bos:/bce-test/test --include-time '[P1D, midnight)'

    说明:

    • 今天早上00:00:00到晚上23:59:59 (包括23:59:59)。
    • 由于时间区间为左闭右开,所以此时间区间不包含右边界时间midnight。
  • 同步当前目录下的sample目录到bos:/bce-test/test下,但是只同步昨天生成或者发生修改的文件

    操作示例: bce bos sync ./sample/ bos:/bce-test/test --include-time '[P1D, midnight-P1D)'

  • 同步当前目录下的sample目录到bos:/bce-test/test下,但是只同步过去24小时内生成或者发生修改的文件

    操作示例: bce bos sync ./sample/ bos:/bce-test/test --include-time '[P1D, now)'

  • 同步当前目录下的sample目录到bos:/bce-test/test下,但是只同步前天和今天生成或者发生修改的文件

    操作示例: bce bos sync ./sample/ bos:/bce-test/test --include-time '[PT24H, midnight)' --include-time '[P1D, midnight-P2D)'

    说明:--include-time 可以多次使用。

  • 同步当前目录下的sample目录到bos:/bce-test/test下,但是只同步本地时间2017年1月2号3时4分5秒到2017年1月3号3时4分5秒之内发生修改或者新生成的文件

    操作示例: bce bos sync ./sample/ bos:/bce-test/test --include-time '[2017-01-02 03:04:05, 2017-01-03 03:04:05)'

    说明: 由于时间区间为左闭右开,所以上面的两个时间区间均不包含时间2017-01-03 03:04:05, 如果需要包含此时间可以将此时间加1秒,表示为'[2017-01-02 03:04:05, 2017-01-03 03:04:06)'。

  • 同步当前目录下的sample目录到bos:/bce-test/test下, 但是不同步前天和今天生成或者发生修改的文件

    操作示例: bce bos sync ./sample/ bos:/bce-test/test --exclude-time '[PT24H, midnight)' --exclude-time '[P1D, midnight-P2D)'

    说明: --exclude-time 可以多次使用。

  • 单文件上传

    操作示例:

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

    返回示例:

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

    操作示例:

    $ bce 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

    操作示例:

    $ tar -cz test.txt | bce bos cp - bos:/mybucket/test.txt.tar
    

    返回示例:

    $ Upload: stream to bos:/mybucket/test.txt.tar
    
  • 上传Object并存储为低频存储类型

    操作示例:

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

    返回示例:

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

    操作示例:

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

    返回示例:

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

下载Object

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

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

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

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

命令格式:

  • 同步下载Object: $ bce bos sync [--delete] [--yes] [--quiet] [--exclude] [--dryrun] <bos-dir> <local-dir> [--exclude-time TIME_RANGE] [--include-time TIME_RANGE]
  • 下载单个Object:$ bce bos cp <bos-path> <local-path>
  • 批量下载Object:$ bce bos cp <bos-path> <local-path> --recursive
  • 流操作下载Object:$ bce bos cp <bos-path> -

说明:

  • 执行bce bos cp bos:/bucket/file /tmp/file命令时,本地文件名可以任意指定,若本地文件存在会提示是否覆盖。
  • 执行bce bos cp bos:/bucket/file /tmp/命令时,本地文件名会自动存为bos端文件名,若存在会提示是否覆盖。
  • 执行bce bos cp bos:/bucket/file /tmp/ -r命令时,bos端为文件时会退化为单个文件下载,若存在会提示是否覆盖。
  • 执行bce bos cp bos:/bucket/prefix/ /tmp/ -r命令时,本地路径如果为一个已存在的文件会报错,本地目录不存在时会创建。
  • <local-path>为"-"时,表示从流中读数据或者写数据到流中,可用管道进行连接。
  • cp中的流操作只支持Linux环境操作,不支持Windows环境。
  • 执行批量下载时,local-path只能是本地目录,bos-path必须为bucket/prefix。如果bos路径为Object,则为单个Object下载。
  • 下载时不管是否指定参数storage-class,都不影响下载,该参数会被自动忽略,不起作用。
  • 同步下载中,local-dir和bos-dir必须为目录,不能为单个文件。
  • --dryrun:列出会执行的操作但不实际执行。
  • --quiet:同步下载但不输出任何中间过程。
  • --delete:删除本地有而BOS没有的文件,使本地和BOS的数据完全一致。执行后默认会提示用户是否要执行删除。
  • --yes:执行删除动作时不需要确认直接删除。
  • --exclude:执行bos到本地的sync的时候, 需要跳过的文件, 支持通配符和多项配置. 例:--exclude 'bos:/mybucket/\.tmp' --exclude 'bos:/mybucket/*.svn' --exclude 'bos:/mybucket/test*'。
  • --exclude-time 与 --include-time: 用法与同步上传文件相同。

示例:

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

    操作示例:

    $ bce 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

    操作示例:

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

    返回示例:

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

    操作示例:

    $ bce 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至管道,从管道中读数据并解压

    操作示例:

    $ bce bos cp bos:/mybucket/test.txt.tar - | tar -xz
    

    无返回

拷贝Object

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

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

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

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

命令格式:

  • 同步拷贝Object:$ bce bos sync [--delete] [--yes] [--quiet] [--exclude] [--dryrun] <bos-dir> <bos-dir> [--exclude-time TIME_RANGE] [--include-time TIME_RANGE]
  • 拷贝单个Object:$ bce bos cp <bos-path> <bos-path>
  • 批量拷贝Object:$ bce bos cp <bos-path> <bos-path> --recursive

说明:

  • 执行bce bos cp bos:/bucket/obj1 bos:/bucket/obj2命令时,复制的两个路径相同时会报错,目的路径若已存在会被覆盖。
  • 执行bce bos cp bos:/bucket/obj1 bos:/bucket/prefix/命令时,obj1会被拷贝到prefix目录下,目的路径必须以“/”结尾,否则会当做一个新文件名新建一个文件。
  • 执行bce bos cp bos:/bucket/obj1 bos:/bucket/prefix/ -r命令时,源路径为单个文件时退化为单个文件拷贝,obj1会被拷贝到prefix目录下。
  • 执行bce bos cp bos:/bucket/prefix1/ bos:/bucket/prefix2/ -r命令,实现目录到目录的拷贝,两个路径都必须以“/”的结尾;若目的路径结尾不以“/”结尾会当做单个文件从而报错。
  • 执行批量拷贝时,bos-path必须为bucket/prefix。
  • 用户必须具备对源bucket的读权限和目标bucket的写权限。
  • 同步拷贝中,bos-dir必须为目录,不能为单个文件。
  • --dryrun:列出会执行的操作但不实际执行。
  • --quiet:同步上传但不输出任何中间过程。
  • --delete:删除源Bucket有而目的Bucket没有的文件,使源和目的Bucket的数据完全一致。执行后默认会提示用户是否要执行删除。
  • --yes:执行删除动作时不需要确认直接删除。
  • --exclude:执行bos到bos的sync的时候, 需要跳过的文件, 支持通配符和多项配置. 例:--exclude 'bos:/mybucket/\.tmp' --exclude 'bos:/mybucket/*.svn' --exclude 'bos:/mybucket/test*'。
  • --exclude-time 与 --include-time: 用法与同步上传文件相同。

示例:

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

    操作示例:

    $ bce 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

    操作示例:

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

    返回示例:

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

    操作示例:

    $ bce 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来达到模拟文件夹的效果。

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

操作示例: bce 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。

命令格式 $ bce bos gen_signed_url bos:/<bucket-name>/<object-key> [--expires TIME]

说明:

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

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

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

示例:

  • 不指定过期时间

    操作示例:

    $ bce 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
    
  • 指定过期时间

    操作示例:

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

    返回示例:

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

删除Object

命令格式:

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

说明:

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

示例:

  • 删除单个Object

    操作示例:

    $ bce 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

    操作示例:

    $ bce 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接口管理包括生命周期管理和日志管理。命令行通用格式为bce bosapi [-h]

设置生命周期

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

命令格式:

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

示例:

  • 生成Transition的配置模板

    操作示例:

    $ bce 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设置生命周期管理规则

    操作示例:

    bce 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的生命周期配置。

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

操作示例: bce 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的生命周期管理配置。

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

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

返回示例:

设置日志规则

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

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

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

返回示例:

获取日志规则

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

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

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

返回示例:

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

删除日志规则

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

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

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

返回示例:

设置Bucket默认存储类型

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

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

命令格式:

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

操作示例:

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

返回示例: 无返回

查询Bucket默认存储类型

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

命令格式:

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

操作示例:

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

返回示例:

{"storageClass":"COLD"}

获取文件meta信息

描述: 此命令可以用于判断object是否存在,也可用于获取objetc的meta信息。具体规则如下:

  1. 如果您指定的object存在,bce 将输出此object的meta信息(输出的信息有 object名称、object大小、上次修改时间、object的存储类型),bce退出状态码为0;
  2. 如果您指定的object不存在,bce将打印"Failed: The specified object does not exist",并且退出状态码为2;
  3. 如果bce执行时发生错误,bce将打印错误信息,并且退出状态码为1.

命令格式:

bce bosapi get-object-meta --bucket-name BUCKET_NAME --object-name OBJECT_NAME [--schema SCHEMA | --quiet]

说明:

  • 如果文件存在,默认输出的meta信息有 object名称、object大小、上次修改时间、object的存储类型, 你也可以使用--schema定制需要输出的meta 信息。
  • --schema: 你可以指定要输出的meta信息,当前可以指定的值为 "object_name", "content_length", "last_modified", "bce_storage_class"
    (分表对应object名称、object大小、上次修改时间、object的存储类型), 您也可以指定输出object的多个属性,各个属性名称之间用逗号分隔。
    比如: 使用--schema "object_name,content_length" 指定输出object名称和object大小 ; 使用--schema "last_modified" 指定只输出object修改时间。
  • --quiet:bce 将不会输出任何中间过程(但是,如果发生错误,bce会打印错误信息)。

操作示例:

获取object的所有meta信息:

操作示例:

bce bosapi get-object-meta --bucket-name mybucket --object-name myobject

返回示例:

Success: {"object_name": "myobject", "content_length": "37", "last_modified": "Fri, 26 Jan 2018 08:51:38 GMT", "bce_storage_class": "STANDARD"}

获取object的大小和存储类型信息:

bce bosapi get-object-meta --bucket-name mybucket --object-name myobject  --schema "content_length,bce_storage_class"

返回示例:

Success: {"content_length": "37", "bce_storage_class": "STANDARD"}

获取不存在的object的meta信息:

操作示例:

bce bosapi get-object-meta --bucket-name mybucket --object-name noexist

返回示例:

Failed: The specified object does not exist

图像审核服务

描述: 对BOS上指定的图像进行审核,输出文字识别结果及图像类别归属的概率。

命令格式: bce bos process img-censor bos:/<bucket-name>/<object-key> --parameter <local json file>

说明:

  • bos://:要审核的图像文件。
  • --parameter: 本地json文件,内容是图像审核相关参数。参数是一个json描述,编码为无BOM的utf-8,如下所示:
    {
        "antiporn" : {},
        "terror" : {},
        "ocr" : {
            "detect_direction" : "false",
            "language_type" : "CHN_ENG",
            "recognize_granularity" : "big"
        }
      }
    
  • parameter可以为多个子服务的按需任意组合,也可以为单个子服务如“鉴黄”。图像审核服务支持的子服务列表有:

    • ocr:通用文字识别
    • face:人脸探测
    • antiporn:色情识别
    • politician:政治人物识别
    • terror:暴恐识别
    • public 公众人物识别
    • webimage:网图OCR识别
    • disgust 恶心图识别
    • watermark:水印二维码识别
    • quality:图像质量识别 value为各底层服务参数,参照河图OCR通用文字识别服务入参。

详细的子服务请求参数及返回参数解释参见服务子类型功能说明

操作示例:

  1. 建立图像审核参数文件,假设存放在~/param.txt,其内容为

    {
        "ocr" : {
          "detect_direct