BOS Util云端批量操作工具

概述

该命令行工具基于java命令行编写,提供对BOS端数据的批量操作,主要包含批量设置metadata、批量删除文件、批量重命名文件、修改prefix(目录)、计算给定prefix(目录)下所有文件大小的总和等功能。

下载地址bosutil-0.1.2.zip

MD5码:97427bee1857b287e7cd32e241b16af8

安装与配置

该工具以jar包形式发布,作为java命令行的"-jar"参数使用,不需要任何安装过程也无任何外部依赖。只需要有java运行环境,且版本在1.6及以上,可以使用命令javac -version检测,若显示java版本为1.6及以上即可,否则请安装或升级java环境。

格式

该工具的通用格式如下:

java -jar bosutil.jar -endpoint {endpoint} -ak {access_key} -sk {security_key}
        -cmd {command} [-bucketName {bucket_name}] [-other_options {option_value}...]

上述格式中使用"{}"的字段为必需参数,对应参数值应使用双引号包含,如:-endpoint "http://bj.bcebos.com"
使用"[]"的字段为可选参数,具体由cmd参数决定。对于"-cmd"这个选项,只能从以下支持的命令中选取一个执行:

命令 作用
LIST_OBJECTS 列举存在bos上的object
SET_CONTENT_TYPE_BY_FILE_EXTENSION 根据object的后缀名设置content-type
GET_OBJECTS_META 批量获取object的meta
DELETE_OBJECTS 批量删除object
SET_OBJECTS_META 设置object的meta
TEST_CONTENT_TYPE 查看某种类型在本工具中对应的content-type
RENAME_OBJECTS 批量重命名object
CHANGE_PREFIX 批量修改object的prefix
COMPUTE_SIZE 计算某个bucket和prefix
TEST_SPEED 测试上传下载速度

说明:以下示例均为Linux/Unix环境下, 如果在windows下使用需要注意:

  • 命令折行使用^
  • "的使用: windows下不能使用'括起参数, 必须使用", 如果参数中包含", 需要使用\"进行转义。

命令详细说明

下面详细说明所支持的命令与选项。

公共选项

下表列举了命令行支持的公共选项,这四个选项为命令格式中给出的必需选项,其它选项依据指定cmd选择设置。

选项 描述 是否有参数值 默认值 示例
-ak access key,如何获取AK/SK,请参见如何获取AK/SK yes - -
-sk secret key,如何获取AK/SK,请参见如何获取AK/SK yes - -
-endpoint BOS endpoint,关于BOS endpoint的详细描述请参见BOS访问域名 yes - http://bj.bcebos.com
-cmd 当前将要执行的命令 yes - SET_OBJECTS_META

该工具所有涉及到输入参数包含中文内容的地方(包括各个参数的值、输入的objectList文件),一律使用UTF-8编码,所有涉及到输出的结果(命令行输出、保存的结果文件)也一律使用UTF-8编码。

LIST_OBJECTS

功能

递归列举用户给定bucket下的所有objects信息到文件。

语法

java -jar bosutil.jar -endpoint {endpoint} -ak {access_key} -sk {security_key}
    -cmd LIST_OBJECTS -bucketName {bucket_name}

选项

必需的ak、sk、endpoint、cmd参数,以及列举的bucket的名称参数bucketName。

选项 描述 示例 是否必选
bucketName bucket 名称 "bucket1"

其他额外参数若指定会忽略。

详细说明

该命令会列举指定bucket下所有objects列表到一个本地文件中,该文件保存在java运行时的同一目录下,以给出的bucketName与"_object_list"组合作为文件名称。如给出的bucketName为"mybucekt",当前java运行目录为"/home/user1",则会生成一个"/home/user1/mybucket_object_list"的文件,该文件每一行为一个object的信息,分别为bucket名称、object全称(包含prefix)、object大小、object的最后修改时间以及obejct的etag,输出文件各列按照\t(tab)分隔,输出文件的格式示例如下:

BucketName\tObjectKey\tSize\tLastModified\tEtag\n
... ... ... ...

使用示例

java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_security_key" \
    -cmd LIST_OBJECTS -bucketName "bucket"

SET_CONTENT_TYPE_BY_FILE_EXTENSION

功能

该命令设置给定object的contentType信息。

语法

java -jar bosutil.jar -endpoint {endpoint} -ak {access_key} -sk {security_key}
    -cmd SET_CONTENT_TYPE_BY_FILE_EXTENSION
    [-objectList {objectListFilePath}] |
    [-bucketName {bucket_name}
    -objectName {object_name}
    -prefix {prefix}
    -marker {marker}
    -contentType {content-type}
    -defaultContentType {default content-type}

选项

除了必需的ak、sk、endpoint、cmd参数外,其它参数参见下表:

选项 描述 示例 是否必选
bucketName bucket名称 "bucket1"
objectName object名称 "prefix1/object1"
prefix 待设置object的prefix "prefix1"
marker 待设置object的marker ""
objectList 包含bucket与object名称列表的文件路径,文件中具体内容依赖使用的命令,文件编码必需为utf8,每行的格式为"BucketName\tObjectName"(其中\t代表tab制表符)。 "list-file-name"
contentType 用户指定的Content-Type metadata信息 ".txt:text/plain;.flv:video/flv"
defaultContentType 依据后缀查找的Content-Type在失败时使用的默认值 "application/otect-stream"

详细说明

该命令依据AK/SK信息,在指定的endpoint下,为选项中指定的Object设置content-type信息。

该工具内置了一个常见后缀名与Content-Type的字典。对于待设置Content-Type的object,Util工具会根据用户指定的contentType参数、内置字典和defaultContentType参数,依据如下规则决定其Content-Type:

  1. 先获得该object的后缀名,和命令行中的contentType参数进行匹配,若精确指定了就使用指定的contentType参数。如某个object的后缀名为".js",而contentType参数中存在一项为".js:text/javascript"则精确指定了。
  2. 若命令行中没有精确指定contentType参数,就判断contentType中是否有模糊指定".*:text/plain",若有则使用之;若模糊指定没有,或者没有给出contentType参数,就前往内置字典获取该object的后缀名对应的Content-Type。若获取成功就使用内置的Content-Type进行设置;
  3. 若内置字典也没有匹配到,则按照命令行中defaultContentType参数指定的值进行设置。若命令行中没有设置defaultContentType参数,则直接返回,对该object不作任何设置,并将该object打印到命令行。

该命令提供两种方式指定待设置Content-Type的object。

  • -objectList方式: 即提供一个object列表文件,各列使用\t(tab)分隔,每行的格式为"BucketName\tObjectName"(其中\t代表tab制表符)。
  • -bucketName -objectName -prefix -marker方式: 即使用bucketName、prefix、marker、objectName进行匹配。该方式必须提供bucketName参数指定bucket,其余参数支持以objectName进行精确指定的方式进行,同时支持使用prefix、marker的方式进行模糊匹配。其中marker的使用方式是:用户初次执行只需要输入prefix, 如果执行到一半失败了, 不必重新开始执行, 只需要找到当前目录下last_marker+${bucket_name}.txt这个文件, 拿到最后一行(是一个object的名字), 将其作为marker的值再次执行命令则可继续上次未完成的批量操作任务。

使用示例

java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_security_key" \
    -cmd SET_CONTENT_TYPE_BY_FILE_EXTENSION \
    -defaultContentType "text/plain" \
    -contentType ".js:text/javascript;.flv:video/flv" \
    -objectList "./a/filelist"
java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_security_key" \
    -cmd SET_CONTENT_TYPE_BY_FILE_EXTENSION \
    -defaultContentType "text/plain" \
    -contentType ".js:text/javascript;.flv:video/flv" \
    -bucketName "abc" \
    -objectName "test-object"

TEST_CONTENT_TYPE

功能

Util工具内置了一个常见后缀名与Content-Type的字典,可以通过TEST_CONTENT_TYPE命令测试字典里所预置的Content-Type。

语法

java -jar bosutil.jar \
    -cmd TEST_CONTENT_TYPE \
    -extension {extension-value}

选项

必需的参数为cmd以及extension参数。

选项 描述 示例 是否必选
extension 文件扩展名 .txt

其他额外参数若指定会忽略。

详细说明

该命令仅用来进行获取指定后缀名的Content-Type信息,因此不需要与bos端交互,无需指定AK/SK以及endpoint信息,只需提供待测试的后缀名参数,然后根据内部支持的Content-Type设置规则返回相应信息到命令行,对于不支持的后缀名返回不支持的提示信息。

使用示例

java -jar bosutil.jar -cmd TEST_CONTENT_TYPE -extension ".mp4"

GET_OBJECTS_META

功能

依据用户指定的object获取方式获取这些object的metadata信息。

语法

java -jar bosutil.jar -endpoint {endpoint} -ak {access_key} -sk {security_key}
    -cmd GET_OBJECTS_META
    [-objectList {objectListFilePath}] |
    [-bucketName {bucket_name}
    -objectName {object_name}
    -prefix {prefix}
    -marker {marker}

选项

除了必需的ak、sk、endpoint、cmd参数外,其它参数参见下表:

选项 描述 示例 是否必选
bucketName bucket名称 "bucket1"
objectName object名称 "prefix1/object1"
prefix object的prefix "prefix1"
marker object的marker ""
objectList 包含bucket与object名称列表的文件路径,文件中具体内容依赖使用的命令,文件编码必需为utf8,每行的格式为"BucketName\tObjectName"(其中\t代表tab制表符)。 "list-file-name"

详细说明

该命令依据AK/SK信息,在指定的endpoint下,依据选项中说明的两种方式获取Object并获取这些object的metadata信息,每个object的metadata信息为一行输出到命令行显示。

支持如下两种方式获取object,从而进行metadata信息的获取:

  • -objectList方式: 即提供一个object列表文件,各列使用\t(tab)分隔,各列使用\t(tab)分隔,每行的格式为"BucketName\ObjectName"(其中\t代表tab制表符)。
  • -bucketName -objectName -prefix -marker方式: 即使用bucketName、prefix、marker、objectName进行匹配。该方式必须提供bucketName参数指定bucket,其余参数支持以objectName进行精确指定的方式进行,同时支持使用prefix、marker的方式进行模糊匹配。其中marker的使用方式是:用户初次执行只需要输入prefix, 如果执行到一半失败了, 不必重新开始执行, 只需要找到当前目录下last_marker+${bucket_name}.txt这个文件, 拿到最后一行(是一个object的名字), 将其作为marker的值再次执行命令则可继续上次未完成的批量操作任务。

上述两种方式由用户选取一种即可,若同时指定,则会选取第一种从objectList参数中读取的方式,忽略第二种方式指定的参数。其他额外参数若指定会忽略。

使用示例

java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_security_key" \
    -cmd GET_OBJECTS_META \
    -objectList "./a/filelist"
java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_security_key" \
    -cmd GET_OBJECTS_META \
    -bucketName "abc" \
    -objectName "test-object"

SET_OBJECTS_META

功能

依据用户指定的object获取方式设置这些object的metadata信息。

语法

java -jar bosutil.jar -endpoint {endpoint} -ak {access_key} -sk {security_key}
    -cmd SET_OBJECTS_META
    -bucketName {bucket_name}
    -objectName {object_name}
    -prefix {prefix}
    -marker {marker}
    -meta {metadata string}
    -replace
    -threadNumber {concurrent number}

选项

除了必需的ak、sk、endpoint、cmd参数外,其它参数参见下表:

选项 描述 示例 是否必选
bucketName bucket名称 "bucket1"
objectName object名称 "prefix1/object1"
prefix 待设置object的prefix,或修改的prefix "prefix1"
marker 待设置object的marker ""
meta object的meta信息 cacheControl:max-age 18080cacheControl:|user_metapath:aa/bb|contentDisposition:attachment;
filename="${object_basename}"
replace 设置meta信息时是否替换原有meta数据,取值为true和false true
threadNumber 并发数, 默认值是1 10

必选参数meta和replace说明如下,其他额外参数若指定会忽略:

  • meta: 以"key:value"方式给出metadata信息,多条信息以"|"连接,作为一个字符串参数提供。

    • meta value内容支持变量表达式:如cacheControl:|__user_meta__path:aa/bb|contentDisposition:attachment;filename="${object_basename}",其中${object_basename}表示object的basename。在批量处理object的meta时,可以通过变量表达式设置所有Object的某一个meta字段,实现meta值不一样。
    • meta中用户可以自定义user meta, user meta的key必须以__user_meta__开头
  • replace : 该参数如果提供表示替换object原有的metadata信息,否则不进行替换(默认不替换)。不替换即将原先的meta和新的meta合并,如果新meta和原meta内容有重复则用新meta。

详细说明

该命令依据AK/SK信息,在指定的endpoint下,依据选项中说明的object获取方式,并根据meta和replace参数依次对获取的这些object的metadata信息进行设置。成功或错误信息会输出到命令行中。

使用如下方式获取需要设置metadata的objects:

-bucketName -objectName -prefix -marker方式: 即使用bucketName、prefix、marker、objectName进行匹配。该方式必须提供bucketName参数指定bucket,其余参数支持以objectName进行精确指定的方式进行,同时支持使用prefix、marker的方式进行模糊匹配。其中marker的使用方式是:用户初次执行只需要输入prefix, 如果执行到一半失败了, 不必重新开始执行, 只需要找到当前目录下last_marker+${bucket_name}.txt这个文件, 拿到最后一行(是一个object的名字), 将其作为marker的值再次执行命令则可继续上次未完成的批量操作任务。

使用示例

  • linux/macOS

    java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_security_key" \
        -cmd SET_OBJECTS_META \
        -objectName "test-bueckt" \
        -prefix "test-" \
        -meta 'cacheControl:|__user_meta__path:aa/bb|contentDisposition:attachment;filename="${object_basename}"' \
    
  • windows:注意双引号"的转义

java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_security_key" ^
    -cmd SET_OBJECTS_META ^
    -bucketName "test-bueckt" ^
    -prefix "test-" ^
    -meta "contentType:text/javascript|contentEncoding:gb18030|contentDisposition:attachment; filename=\"${object_basename}\"|__user_meta__path:a/b" ^
    -replace

DELETE_OBJECTS

功能

依据用户指定的object获取方式批量删除获取的Object。

注意:*该操作执行后不可恢复,请慎重操作*。

语法

java -jar bosutil.jar -endpoint {endpoint} -ak {access_key} -sk {security_key}
    -cmd DELETE_OBJECTS
    [-objectList {objectListFilePath}] |
    [-bucketName {bucket_name}
    -objectName {object_name}
    -prefix {prefix}
    -marker {marker}

选项

除了必需的ak、sk、endpoint、cmd参数外,其它参数参见下表:

选项 描述 示例 是否必选
bucketName bucket 名称 "bucket1"
objectName object 名称 "prefix1/object1"
prefix 列举object时的prefix,或修改的prefix "prefix1"
marker 列举object时的marker ""
objectList 包含bucket与object名称列表的文件路径,文件中具体内容依赖使用的命令,文件编码必需为utf8,每行的格式为"BucketName\tObjectName"(其中\t代表tab制表符)。 "list-file-name"

详细说明

该命令依据AK/SK信息,在指定的endpoint下,批量删除选项中指定方式获取的Object,若有删除出错的object,会讲错误信息打印到命令行中。该命令在执行过程中若同时有object上传,且Object的prefix与正在删除的prefix匹配,此时无法保证新上传的object被删除。

如果指定objectList,则只删除这个文件列举的所有文件,文件中各列按照\t(tab)
分隔,内容格式为

${bucketName}\t${objectName}

使用示例

java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_security_key" \
    -cmd DELETE_OBJECTS \
    -objectList "./a/filelist"
java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_security_key" \
    -cmd DELETE_OBJECTS \
    -bucketName "test-bucket" \
    -prefix "test-"

RENAME_OBJECTS

功能

依据用户指定的object重命名信息的文件批量进行重命名操作。

语法

java -jar bosutil.jar -endpoint {endpoint} -ak {access_key} -sk {security_key}
    -cmd RENAME_OBJECTS
    -objectList {objectListFilePath}

选项

除了必需的ak、sk、endpoint、cmd参数外,其它参数参见下表:

选项 描述 示例 是否必选
objectList 提供一个每一行都为一条重命名信息的文件的路径,各列使用\t(tab)分隔,每行的格式为:SrcBucketName\tSrcObjectName\tDstBucketName\tDstObjectName(其中\t代表tab制表符)。 "list-file-name"

详细说明

该命令依据AK/SK信息,在指定的endpoint下,对选项中指定的文件,批量操作该文件提供的每条重命名信息,进行重命名操作。该命令的操作分为两步,首先进行复制操作,再进行删除操作,因此如果有任何一步出错都会执行恢复操作进行回退,并输出出错信息。

该命令会自动读取文件并对每一行指定源object与新的名称进行批量重命名操作,处理的这个文件的进度信息保存在以"last_marker_"开头,后接objectList文件名的basename,再以".txt"为扩展名的文件中(如last_marker_objectlist.txt),保存了objectList行数与实际处理的object数目。其他额外参数若指定会忽略。

使用示例

java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_security_key" \
    -cmd RENAME_OBJECTS \
    -objectList "./rename-file-list"

CHANGE_PREFIX

功能

依据用户指定的bucket下的prefix,对prefix进行修改。

语法

java -jar bosutil.jar -endpoint {endpoint} -ak {access_key} -sk {security_key}
    -cmd CHANGE_PREFIX
    -bucketName : {bucket-name}
    -prefix {original-preifx}
    -newPrefix {new-prefix}

选项

除了必需的ak、sk、endpoint、cmd参数外,其它参数参见下表:

选项 描述 示例 是否必选
bucketName 需要修改的bucket名称 "bucket1"
prefix 需要修改的prefix名称,类似需要修改的目录名称 "prefix1"
newPrefix 修改后的新的prefix名称,类似新文件夹名称 "prefix2"

其他额外参数若指定会忽略。

详细说明

该命令模拟文件夹方式进行目录重命名操作。依据AK/SK信息,在指定endpoint下的bucket中,找到preifx下所有obejct,依次对每个object构造新的prefix下的名称,批量进行重命名。每个重命名prefix的操作分为两步,首先进行复制操作,再进行删除操作,因此如果有任何一步出错都会执行恢复操作进行回退,并输出出错信息。在执行过程中若同时有object上传到相同prefix下不能保证新上传的Object被修改。

使用示例

java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_security_key" \
    -cmd CHANGE_PREFIX \
    -bucketName "mybucket" \
    -prefix "test" \
    -newPrefix "demo"

COMPUTE_SIZE

功能

依据用户指定的bucket下的prefix,计算整个prefix下所有object的总大小。

语法

java -jar bosutil.jar -endpoint {endpoint} -ak {access_key} -sk {security_key}
    -cmd COMPUTE_SIZE
    -bucketName : {bucket-name}
    -prefix {preifx}

选项

除了必需的ak、sk、endpoint、cmd参数外,其它参数参见下表:

选项 描述 示例 是否必选
bucketName 操作的bucket名称 "bucket1"
prefix 需要计算大小prefix名称,类似需要计算大小的的目录名 "prefix1"
friendly 设置计算prefix的大小时是否以可读的友好方式输出,默认值为false -

其他额外参数若指定会忽略。

详细说明

该命令模拟文件夹进行目录大小计算的操作。将依据AK/SK信息,在指定endpoint下的bucket中,找到preifx下所有obejct,依次获取每个object的大小并进行批量累积计算,最后输出该prefix的总大小,类似于计算整个目录的总大小。在执行过程中若同时有object上传到相同prefix下不能保证新上传的Object被计算到。

使用示例

java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_security_key" \
    -cmd COMPUTE_SIZE \
    -bucketName "mybucket" \
    -prefix "test"

TEST_SPEED

功能

测试下载速度。

语法

java -jar bosutil.jar -endpoint {endpoint} -ak {access_key} -sk {security_key}
    -cmd TEST_SPEED
    [-testSize 10485760]

选项

除了必需的ak, sk, endpoint, cmd参数外, 其它参数参见下表:

选项 描述 示例 是否必选
testSize 测试的文件大小, 此文件完全放在内存, 默认为10485760 1000000

说明

其他额外参数若指定会忽略。

版本变更记录

  • BOS Util工具包 [2017-03-16] 版本号0.1.2

    • set_objects_meta命令支持变量${object_basename}可以批量修改meta值功能。
    • 新增test_speed命令用于测试不同size的bos object上传下载速度。
    • 提高 compute size性能。
  • BOS Util工具包 [2016-09-13] 版本号0.1.1

    更新README中的sample code。

  • BOS Util工具包 [2016-09-02] 版本号0.1.0

    第一次发布。提供对BOS端数据的批量操作,主要包含批量设置metadata、批量删除文件、批量重命名文件、修改prefix、计算给定prefix(目录)下所有文件大小的总和等功能。