通过BOS-Util使用BOS服务

命令格式

该工具的通用格式如下:

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

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

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

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

公共选项

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

LIST_OBJECTS命令

功能

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

语法

1java -jar bosutil.jar -endpoint {endpoint} -ak {access_key} -sk {secret_key}
2    -cmd LIST_OBJECTS -bucketName {bucket_name}

选项

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

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

详细说明

该命令会列举指定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)分隔，输出文件的格式示例如下：

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

使用示例

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

SET_CONTENT_TYPE_BY_FILE_EXTENSION命令

功能

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

语法

1    java -jar bosutil.jar -endpoint {endpoint} -ak {access_key} -sk {secret_key}
2        -cmd SET_CONTENT_TYPE_BY_FILE_EXTENSION
3        [-objectList {objectListFilePath}] |
4        [-bucketName {bucket_name}
5        -objectName {object_name}
6        -prefix {prefix}
7        -marker {marker}
8        -contentType {content-type}
9        -defaultContentType {default content-type}

选项

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

详细说明

该命令依据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名字 已完成任务数量>), 将object名字作为marker的值再次执行命令则可继续上次未完成的批量操作任务。

使用示例

1java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_secret_key" \
2    -cmd SET_CONTENT_TYPE_BY_FILE_EXTENSION \
3    -defaultContentType "text/plain" \
4    -contentType ".js:text/javascript;.flv:video/flv" \
5    -objectList "./a/filelist"

1java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_secret_key" \
2    -cmd SET_CONTENT_TYPE_BY_FILE_EXTENSION \
3    -defaultContentType "text/plain" \
4    -contentType ".js:text/javascript;.flv:video/flv" \
5    -bucketName "abc" \
6    -objectName "test-object"

SET_OBJECTS_ACL

功能

该命令设置给定object的acl信息

语法

1java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_secret_key"
2    -cmd SET_OBJECTS_ACL
3    -bucketName {bucket_name}
4    [-objectName {object_name}] |
5    [-prefix {prefix}]
6    [-marker {marker}]
7    [-canned {canned acl}] |
8    [-aclConfigFile {acl_config_file}]
9    [-threadNumber {concurrent number}]

选项

除了必须的ak、sk、endpoint、cmd参数外，其他参数见下表：

详细说明

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

该工具支持两种方式为object设置acl信息：

1. 通过canned参数，指定object的访问权限，支持PRIVATE和PUBLIC-READ；
2. 通过aclConfigFile参数，提供一个ACL文件，文件内容为JSON格式，具体如下：

1{
2    "accessControlList": [
3        {
4            "grantee": [
5                {
6                    "id": "e13b12d0131b4c8bae959df4969387b8"
7                }
8            ],
9            "permission": [
10                "READ"
11            ]
12        }
13    ]
14}

该命令提供指定待设置acl的object方式如下：

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

使用示例

1java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_secret_key" \
2    -cmd SET_OBJECTS_ACL \
3    -bucketName "bucket1" \
4    -objectNmae "prefix1/object1" \
5    -canned "PRIVATE"

1java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_secret_key" \
2    -cmd SET_OBJECTS_ACL \
3    -bucketName "bucket1" \
4    -prefix "prefix" \
5    -marker "" \
6    -canned "PRIVATE"

1java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_secret_key" \
2    -cmd SET_OBJECTS_ACL \
3    -bucketName "bucket1" \
4    -prefix "prefix" \
5    -marker "" \
6    -aclConfigFile "example.txt"

TEST_CONTENT_TYPE命令

功能

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

语法

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

选项

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

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

详细说明

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

使用示例

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

GET_OBJECTS_META命令

功能

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

语法

1java -jar bosutil.jar -endpoint {endpoint} -ak {access_key} -sk {secret_key}
2    -cmd GET_OBJECTS_META
3    [-objectList {objectListFilePath}] |
4    [-bucketName {bucket_name}
5    -objectName {object_name}
6    -prefix {prefix}
7    -marker {marker}

选项

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

详细说明

该命令依据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名字 已完成任务数量>), 将object名字作为marker的值再次执行命令则可继续上次未完成的批量操作任务。

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

使用示例

1java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_secret_key" \
2    -cmd GET_OBJECTS_META \
3    -objectList "./a/filelist"

1java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_secret_key" \
2    -cmd GET_OBJECTS_META \
3    -bucketName "abc" \
4    -objectName "test-object"

SET_OBJECTS_META命令

功能

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

语法

1java -jar bosutil.jar -endpoint {endpoint} -ak {access_key} -sk {secret_key}
2    -cmd SET_OBJECTS_META
3    -bucketName {bucket_name}
4    -objectName {object_name}
5    -prefix {prefix}
6    -marker {marker}
7    -meta {metadata_string}
8    -replace
9    -threadNumber {concurrent_number}

选项

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

必选参数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名字 已完成任务数量>), 将object名字作为marker的值再次执行命令则可继续上次未完成的批量操作任务。

使用示例

• linux/macOS

  Shell 复制

  1 java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_secret_key" \
  2      -cmd SET_OBJECTS_META \
  3      -objectName "test-bueckt" \
  4      -prefix "test-" \
  5      -meta 'cacheControl:|\__user_meta__path:aa/bb|contentDisposition:attachment;filename="${object_basename}"' \

1-   windows：注意双引号`"`的转义
2
3```shell
4java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_secret_key" ^
5 -cmd SET_OBJECTS_META ^
6 -bucketName "test-bueckt" ^
7 -prefix "test-" ^
8 -meta "contentType:text/javascript|contentEncoding:gb18030|contentDisposition:attachment; filename=\"${object_basename}\"|__user_meta__path:a/b" ^
9 -replace

DELETE_OBJECTS命令

功能

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

注意：该操作执行后不可恢复，请慎重操作。

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

选项

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

详细说明

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

使用include正则匹配删除object时，确保正则表达式是符合预期的情况下再执行命令，可以配合preview参数提前获取即将删除的object列表。

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

1${bucketName}\t${objectName}

使用示例

1java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_secret_key" \
2    -cmd DELETE_OBJECTS \
3    -objectList "./a/filelist"

1java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_secret_key" \
2    -cmd DELETE_OBJECTS \
3    -bucketName "test-bucket" \
4    -prefix "test-"

1java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_secret_key" \
2    -cmd DELETE_OBJECTS \
3    -bucketName "test-bucket" \
4    -prefix "test-"
5    -include "test-.*jpeg"
6    -preview "true"

RENAME_OBJECTS命令

功能

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

语法

1java -jar bosutil.jar -endpoint {endpoint} -ak {access_key} -sk {secret_key}
2    -cmd RENAME_OBJECTS
3    -objectList {objectListFilePath}

选项

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

详细说明

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

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

使用示例

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

CHANGE_PREFIX命令

功能

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

语法

1java -jar bosutil.jar -endpoint {endpoint} -ak {access_key} -sk {secret_key}
2    -cmd CHANGE_PREFIX
3    -bucketName {bucket_name}
4    -prefix {original_preifx}
5    -newPrefix {new_prefix}

选项

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

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

详细说明

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

使用示例

1java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_secret_key" \
2    -cmd CHANGE_PREFIX \
3    -bucketName "mybucket" \
4    -prefix "test" \
5    -newPrefix "demo"

COMPUTE_SIZE命令

功能

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

语法

1java -jar bosutil.jar -endpoint {endpoint} -ak {access_key} -sk {secret_key}
2    -cmd COMPUTE_SIZE
3    -bucketName {bucket_name}
4    [-prefix {preifx}]
5    [-friendly {friendly}]
6    [-level {level}]
7    [-threadNumber {concurrent_number}]

选项

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

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

详细说明

该命令模拟文件夹进行目录大小计算的操作。将依据AK/SK信息，在指定endpoint下的bucket中，找到preifx下所有obejct，依次获取每个object的大小并进行批量累积计算，最后输出该prefix的总大小，类似于计算整个目录的总大小。在执行过程中若同时有object上传到相同prefix下不能保证新上传的Object被计算到, 可以通过设置合适的level和threadNumber值提高计算并发度，节省运行时间。该命令未统计碎片Object占用的空间，而控制台上的占用空间大小包括碎片。

使用示例

1java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_secret_key" \
2    -cmd COMPUTE_SIZE \
3    -bucketName "mybucket" \
4    -prefix "test"

1java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_security_key" \
2    -cmd COMPUTE_SIZE \
3    -bucketName "mybucket" \
4    -level "2" \
5    -threadNumber "20"

TEST_SPEED命令

功能

测试下载速度。

语法

1java -jar bosutil.jar -endpoint {endpoint} -ak {access_key} -sk {secret_key}
2    -cmd TEST_SPEED
3    [-testSize 10485760]

选项

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

说明

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