对象存储BOS

    通过BOS-Util使用BOS服务

    命令格式

    该工具的通用格式如下:

        java -jar bosutil.jar -endpoint {endpoint} -ak {access_key} -sk {secret_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

    LIST_OBJECTS命令

    功能

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

    语法

    java -jar bosutil.jar -endpoint {endpoint} -ak {access_key} -sk {secret_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_secret_key" \
        -cmd LIST_OBJECTS -bucketName "bucket"

    SET_CONTENT_TYPE_BY_FILE_EXTENSION命令

    功能

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

    语法

    java -jar bosutil.jar -endpoint {endpoint} -ak {access_key} -sk {secret_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_secret_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_secret_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 {secret_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_secret_key" \
        -cmd GET_OBJECTS_META \
        -objectList "./a/filelist"
    java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_secret_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 {secret_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=1800cacheControl:|__user_meta_path: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_secret_key" \
            -cmd SET_OBJECTS_META \
            -objectName "test-bueckt" \
            -prefix "test-" \
            -meta 'cacheControl:|\__user_meta__path:aa/bb|contentDisposition:attachment;filename="${object_basename}"' \
    -   windows:注意双引号`"`的转义
    
    ```shell
    java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_secret_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 {secret_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_secret_key" \
        -cmd DELETE_OBJECTS \
        -objectList "./a/filelist"
    java -jar bosutil.jar -endpoint "http://bj.bcebos.com" -ak "your_access_key" -sk "your_secret_key" \
        -cmd DELETE_OBJECTS \
        -bucketName "test-bucket" \
        -prefix "test-"

    RENAME_OBJECTS命令

    功能

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

    语法

    java -jar bosutil.jar -endpoint {endpoint} -ak {access_key} -sk {secret_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_secret_key" \
        -cmd RENAME_OBJECTS \
        -objectList "./rename-file-list"

    CHANGE_PREFIX命令

    功能

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

    语法

    java -jar bosutil.jar -endpoint {endpoint} -ak {access_key} -sk {secret_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_secret_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 {secret_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被计算到。该命令未统计碎片Object占用的空间,而控制台上的占用空间大小包括碎片。

    使用示例

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

    TEST_SPEED命令

    功能

    测试下载速度。

    语法

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

    选项

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

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

    说明

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

    上一篇
    安装BOS-Util
    下一篇
    版本变更记录