KS3Util命令行工具

最近更新时间:2021-11-23 10:10:57

查看PDF

版本历史

版本号 修改内容 时间
ks3util-1.2.3-dist 增加移动对象功能
2021年10月27日
ks3util-1.2.2-dist 支持上传对象指定存储类型
2021年9月1日
ks3util-1.2.1-dist 支持按本地目录结构上传 2021年6月8日
ks3util-1.2.0-dist(beta) 1:省略配置文件,启动根据提示输入配置信息生成文件
2:将所有指令格式进行统一重构
3:整合get, put,multi-move指令到cp指令(上传下载复制)支持多文件,过滤器以及不同账号桶下的迁移复制操作
4:增加cp指令显示指定路径下各个目录大小
5:ls,du命令列举优化控制台输出信息
2020年12月30日
ks3util-1.1.3-dist 修复了批量复制的Bug 2019年5月21日
ks3util-1.1.2-dist List命令增加了显示文件大小、文件MD5值的可选项 2018年1月29日
ks3util-1.1.1-dist 增加了Bucket统计容量的功能 2017年6月7日
ks3util-1.1.0-dist 包括功能:List、上传、下载、批量下载、批量删除、批量设置ACL 2017年6月2日

一、介绍

KS3Util工具是KS3为用户提供的命令行工具,方便用户实现对象的批量上传、下载、查询、复制、设置元数据等操作。

二、功能列表

三、运行环境

用户系统需要具备JDK 1.8以上环境。

Windows安装JDK方法参考:环境安装与配置-WIN7下JDK安装与配置。安装完成后,在命令提示符下,执行java –version,来确认是否安装成功。

c:\>java -version
java version "1.8.0_301"
Java(TM) SE Runtime Environment (build 1.8.0_301-b09)
Java HotSpot(TM) Client VM (build 25.301-b09, mixed mode)

Linux安装JDK方法参考:环境安装与配置-Linux下JDK安装与配置。安装完成后,在终端下执行java -version,来确认是否安装成功。

#java -version
java version "1.8.0_301"
Java(TM) SE Runtime Environment (build 1.8.0_301-b09)
Java HotSpot(TM) Client VM (build 25.301-b09, mixed mode)

四. 安装

1. Linux系统

  • 下载KS3Util(以ks3util 1.2.3版本为例)。
wget https://ks3tools-online.ks3-cn-beijing.ksyuncs.com/tools/beta/ks3util-1.2.3-dist.zip
  • 解压文件。
unzip ks3util-{VERSION}-dist.zip
  • 修改文件执行权限。
cd ks3util-{VERSION}

chmod 755 bin/ks3util
  • 使用交互方式生成配置文件。

在第一次执行ks3util命令时,可通过交互方式设置访问KS3时所需要的域名EndpointAccess Key ID和Access Secret Key。例如,第一次执行list buckets操作时,会提示输入配置信息。

./bin/ks3util ls -b

输出:

请输入AK

AKLTYS2***********

请输入SK

OE23G***********

请输入ENDPOINT

ks3-cn-beijing.ksyuncs.com

配置之后,默认在KS3Util的安装路径下自动生成sample.conf配置文件。您也可以在命令行中指定-c参数,来指定配置文件。例如,在list buckets时指定配置文件。

./bin/ks3util ls -b -c /home/ks3util-1.2.2/sample.conf

2. Windows系统

  • 单击下载链接下载工具。

  • 将工具解压。

打开CMD命令提示符工具,进入KS3Util的安装目录。在第一次执行ks3util命令时,可通过交互方式设置访问KS3时所需要的域名EndpointAccess Key ID和Access Secret Key。例如,第一次执行list buckets操作时,会提示输入配置信息。

ks3util ls -b

输出:

请输入AK

AKLTYS2***********

请输入SK

OE23G***********

请输入ENDPOINT

ks3-cn-beijing.ksyuncs.com

配置之后,默认在KS3Util的安装路径下自动生成bin/sample.conf配置文件。

您也可以通过在命令行中指定-c 参数,来指定配置文件。例如,在list buckets时指定配置文件。

ks3util ls -b -c d:/sample.conf

五、 常用命令

以下以Linux系统为例,说明工具的常用命令使用方法。

ks3util文件在bin目录下。

1. 查看工具支持的命令

描述

help指令用于介绍ks3util各个命令的语法格式。

命令格式

./ks3util help

输出


usage: ks3util <command> [ <args> ]

 

Commands are:

    cp                     Batch upload/download/copy

    du                     Calculate sum of object size

    get                    Download a file from ks3

    help                   Display help information

    ls                     List ks3 object keys

    multi-change-meta      Batch change user meta

    multi-del              Multi delete ks3 keys

    multi-get              Batch download

    multi-move             Batch move from one bucket to another

    multiChangeMeta        Batch change user meta

    put                    Upload a file to ks3

    rm                     Rm Command to Multi delete ks3 keys

    set-acl                Batch set ks3 objects acl

    setAcl                 Batch set ks3 objects acl

    toUrl                  Get urls

 

See 'ks3util help <command>' for more information on a specific command.

其中get,put,multi-del,set-acl,multi-move,multi-get,multi-change-meta,toUrl 命令是旧版本命令,建议您使用新版本命令。

如果要查看某个子命令的使用方式,可以执行ks3util help 。例如,查看ls命令的使用方式。

./ks3util help ls

2. 列举存储空间

描述

ls命令用于列举存储空间(Bucket)和对象(Object)。

2.1. 列举存储空间

命令格式

./ks3util ls -b [-c config_file]

常用参数

参数名称 描述
-b 列举所有Bucket
-c 指定ks3util配置文件的路径

使用示例

  • 列举Bucket
./ks3util ls -b

输出:包括bucket名称、创建时间、所在地域、存储类型和数量。

========================= Buckets List =========================

CreationTime         Region    StorageClass    BucketName

-------------------  --------  ------------  ---------------------  

2020-08-19 14:45:38  BEIJING   NORMAL          uptooz-test       

2020-09-01 15:31:22  BEIJING   NORMAL          bucket-1

-------------------  --------  ------------  ---------------------  

Bucket Number is:2

2.2. 列举对象

命令格式

./ks3util ls ks3://bucketName[/objectPrefix] [-c config_file] [-d] [-exclude exclude_pattern] [-include include_pattern] [-k keys_file] [-m marker] [-o] [-T time_range] [-u urls_file]

常用参数

参数名称 描述
bucketName Bucket名称
objectPrefix Object名称前缀。当您要列举Bucket中指定前缀的Object时添加此项。
-c 指定ks3util配置文件的路径。
-d 返回当前目录下的文件(合并成一个目录形式输出)和子目录。
-exclude 导出Object列表时,不导出包含指定名称的Object(模糊匹配),多个Object名称用英文逗号分隔。
-include 导出Object列表时,仅导出包含指定名称的Object(模糊匹配),多个Object名称用英文逗号分隔。
-k 导出Object名称到指定文件。
-m 列举名称字母排序在marker之后的Object。
-o 导出文件的同时增加文件的属性信息。
-T 列举lastmodified在规定时间内的文件,例如:“2021-01-01 00:00:00#2021-01-31 23:59:00”
-u 导出Object的共享URL列表到指定文件。共享URL根据用户配置的AccessKeyID和SecretKey生成。

使用示例

  • 列举指定Bucket下所有的Object。
./ks3util ls ks3://examplebucket/ -k objectKeys.txt
  • 列举指定Bucket下所有以”abc/”开头的Object。
./ks3util ls ks3://examplebucket/abc -k objectKeys.txt
  • 列举指定Bucket下所有目录
./ks3util ls ks3://examplebucket -d

输出:目录名称、包含的对象个数、目录总大小

============= Object  List =============

PrefixDir           ContainsNum  TotalSize

------------------  -----------  ---------

目录文件集合              3            13.99 MB

testDir                 209          280.23 MB

------------------  -----------  ---------

Direction Number is:2

total num 212 个

total size 308517940 Bytes, 294.23 MB
  • 列举Object时指定marker参数,列举出指定marker之后的对象。
./ks3util ls ks3://examplebucket -k objectKeys.txt -m objectMarker
  • 导出object URL列表到指定文件
./bin/ks3util ls ks3://examplebucket -u keys.txt
  • 导出文件的同时增加文件的属性信息,包括文件的ETag,文件大小和最后修改时间。
./bin/ks3util ls ks3://examplebucket -o -k keys.txt
  • 导出lastmodified在规定时间内的文件,例如:“2021-10-10 00:00:00#2021-10-15 00:00:00”
./bin/ks3util ls ks3://examplebucket -T "2021-10-10 00:00:00#2021-10-15 00:00:00" -k keys.txt
  • 导出object列表时,不导出名称中包含mp4的object。
./bin/ks3util ls ks3://examplebucket -exclude mp4 -k keys.txt
  • 导出object列表时,仅导出名称中包含mp4的object。
./bin/ks3util ls ks3://examplebucket -include mp4 -k keys.txt

3. 对象上传

描述

cp命令可以批量上传本地路径下的文件到KS3 bucket中。当上传的文件较大时,cp命令将自动使用分块上传和断点续传。

命令格式

 ./ks3util cp LocalPath ks3://bucketName/objectPath [-a|--acl acl] [-c config_file] [-exclude exclude_pattern] <-f fail_keys_file> [-i upload_hidden_files] [-include include_pattern] [-r use_relative_path] [-s|--storageclass storage_class] [--update|-u update_exist_files] [-z use_last_dir_name]

常用参数

参数名称 描述
LocalPath 本地文件路径。例如Linux系统文件路径/localPath/examplefile.txt,Windows系统文件路径D:\localPath\examplefile.txt。也可以配置为本地目录,表示上传目录下的文件。
bucketName Bucket名称。
objectPath 将Object上传到Bucket指定路径下。
-a 设置文件的ACL权限,枚举值:Private(私有),PublicRead(公共读),默认Private。
-c 指定ks3util配置文件的路径。
-exclude 不上传包含指定名称的Object(模糊匹配),多个Object名称用英文逗号分隔。
-f 导出上传失败的Object列表文件。
-i 是否上传隐藏文件,枚举值:yes,no(默认)
-include 仅上传包含指定名称的Object(模糊匹配),多个Object名称用英文逗号分隔。
-r 路径是否是相对路径,枚举值:yes,no
-s 指定文件的存储类型 枚举值:STANDARD(标准存储)、STANDARD_IA(低频存储)、ARCHIVE(归档存储),默认跟随bucket存储类型。
-u 上传时如bucket中已有同名文件存在的处理方式,枚举值: 0(根据最后修改时间判断是否重传,新文件覆盖旧文件),1(最后修改时间或文件大小判断是否重传),2(全部覆盖),3(全部跳过),默认是0。
-z 是否将文件所在的当前目录名称作为object名称前缀,枚举值:yes(默认),no。

使用示例

以Linux系统为例,将本地文件或文件夹上传至KS3中。您在实际使用中,请根据您的系统和使用环境修改对应参数。

  • 本地文件:examplefile.txt(相对目录下的文件)

  • 本地文件夹:LocalPath(相对目录下的文件夹)

  • 目标Bucket:examplebucket

  • 目标Bucket指定目录:desPath

  • 上传单个文件,如果不指定上传至KS3的文件名,则默认使用原文件名进行保存;如果指定文件名,则按照指定的文件名保存在KS3中。上传失败的文件列表输出到fail.txt。

./ks3util cp examplefile.txt ks3://examplebucket/desPath/ -f fail.txt

输出:包括上传的文件名称,文件个数,文件大小,重复文件个数,失败文件个数,上传时长等信息。

[Upload] SUCCESS objectKey:examplefile.txt  storageClass:STANDARD [success:1/total:1]

[Upload DONE]totalKeys=1,filterFetchNum=0,SuccessTotalNum=1,SuccessFileSize=6,repeatNum=0,failedNum=0 cost=87
  • 上传文件夹和文件夹下的所有文件(包括子文件夹和子文件夹中的文件)。上传失败的文件列表输出到fail.txt。
./ks3util cp LocalPath/ ks3://examplebucket/desPath/ -f fail.txt

输出:包括上传的文件名称,文件个数,文件大小,重复文件个数,失败文件个数,上传时长等信息。

[Upload] SUCCESS objectKey:LocalPath/s3util-1.2.2/LocalPath/  storageClass:STANDARD [success:1/total:1]

[Upload] SUCCESS objectKey:LocalPath/s3util-1.2.2/LocalPath/subPath/  storageClass:STANDARD [success:2/total:2]

[Upload] SUCCESS objectKey:LocalPath/s3util-1.2.2/LocalPath/subPath/33.txt  storageClass:STANDARD [success:3/total:3]

[Upload] SUCCESS objectKey:LocalPath/s3util-1.2.2/LocalPath/abc.txt  storageClass:STANDARD [success:4/total:4]

[Upload] SUCCESS objectKey:LocalPath/s3util-1.2.2/LocalPath/111.txt  storageClass:STANDARD [success:5/total:5]

[Upload DONE]totalKeys=5,filterFetchNum=0,SuccessTotalNum=5,SuccessFileSize=8192,repeatNum=0,failedNum=0 cost=425
  • 上传本地文件时,指定文件权限为公有读。
./ks3util cp LocalPath/ ks3://examplebucket/Path/ -f fail.txt -a PublicRead
  • 上传本地文件时,不上传名称中包含txt的object。
./ks3util cp LocalPath/ ks3://examplebucket/Path/ -f fail.txt -exclude txt
  • 上传本地文件时,仅上传名称中包含txt的object。
./ks3util cp LocalPath/ ks3://examplebucket/Path/ -f fail.txt -include txt
  • 上传本地文件时,使用绝对路径方式指定本地路径。
./ks3util cp /home/user/LocalPath/ ks3://examplebucket/Path/ -f fail.txt -r no
  • 上传本地文件时,设置文件存储类型为低频存储。
./ks3util cp LocalPath/ ks3://examplebucket/Path/ -f fail.txt -s STANDARD_IA
  • 上传本地文件时,如KS3 bucket中已有同名文件存在,则全部覆盖。
./ks3util cp LocalPath/ ks3://examplebucket/Path/ -f fail.txt -u 2
  • 上传本地文件时,不将文件所在的当前目录名称作为object名称前缀
./ks3util cp LocalPath/  ks3://examplebucket/Path/ -f fail.txt -z no

4. 对象复制

描述

cp命令可以将KS3 Bucket中的文件(Object)拷贝至其他Bucket。

命令格式

./ks3util cp ks3_path ks3_path [-exclude exclude_pattern] <-f fail_keys_file> [-include include_pattern] [-r retry_times]

常用选项

您可以在使用cp命令时附加如下选项指定列举模式及列举的内容:

选项名称 描述
ks3_path 分别填写KS3源文件和目标文件路径。格式为ks3://bucketname/objectname。例如,将目标存储空间examplebucket下的源文件srcobject.txt拷贝到存储空间examplebucket2下的目标文件destobject.txt,则源文件路径填写为ks3://examplebucket/srcobject.txt,目标文件路径填写为ks3://examplebucket2/destobject.txt。
-c 指定ks3util配置文件的路径。
-f 导出拷贝失败的Object列表文件
-r 失败重试次数
-include 仅拷贝包含指定名称的Object(模糊匹配),多个Object名称用英文逗号分隔。
-exclude 不拷贝包含指定名称的Object(模糊匹配),多个Object名称用英文逗号分隔。

使用示例

以Linux系统为例,在不同Bucket之间拷贝文件。您在实际使用中,请根据您的系统和使用环境修改对应参数。

  • 源Bucket:examplebucket1

  • 源Bucket指定目录1:srcPath

  • 源文件:examplefile.txt

  • 目标Bucket:examplebucket2

  • 目标Bucket指定目录:desPath

  • 复制单个文件,目标bucket中的文件名与源文件名相同,上传失败的文件列表输出到fail.txt。

./ks3util cp ks3://examplebucket1/srcPath/examplefile.txt ks3://examplebucket2/desPath/ -f fail.txt

第一次复制对象时,需要配置目标bucket对应的域名Endpoint,Access Key ID和Access Secret Key。配置之后,ks3util默认将配置信息保存在sample.conf配置文件。

配置完成后可以拷贝对象,并输出拷贝的文件名称,文件个数等信息。

复制

请输入目标账户AK

AKLTYS2***********

请输入目标账户SK

OE23G***********

请输入目标账号ENDPOINT

ks3-cn-beijing-internal.ksyuncs.com


[Copy] SUCCESS examplefile.txt[success:1/total:1]
[Copy] DONE,totalKeys=1,SuccessTotalNum=1,filterFetchNum=0,repeatNum=0,failedNum=0
  • 批量复制多个文件,将examplebucket1中srcPath目录下的文件批量拷贝到examplebucket2的desPath目录下。
./ks3util cp ks3://examplebucket1/srcPath/ ks3://examplebucket2/desPath/ -f fail.txt

5. 对象下载

描述

cp命令可以将KS3 bucket中的文件或文件夹,批量下载至本地。

命令格式

./ks3util cp ks3://bucketName/objectPath LocalPath/ [-c config_file] [-exclude exclude_pattern] <-f fail_keys_file> [-include include_pattern] 
 

常用参数

参数名称 描述
LocalPath 本地文件路径。例如Linux系统文件路径localPath/,Windows系统文件路径D:\localPath。
bucketName Bucket名称
-c 指定ks3util配置文件的路径。
-exclude 不下载包含指定名称的Object(模糊匹配),多个Object名称用英文逗号分隔。
-f 导出下载失败的Object列表文件
-include 仅下载包含指定名称的Object(模糊匹配),多个Object名称用英文逗号分隔。

使用示例

以Linux系统为例,将KS3中的文件或文件夹下载至本地。您在实际使用中,请根据您的系统和使用环境修改对应参数。

  • 目标Bucket:examplebucket

  • 目标Bucket指定目录:desPath

  • 目标Bucket中的文件:examplefile.txt

  • 本地文件夹:LocalPath(相对目录下的文件夹)

  • 下载单个文件,如果不指定下载到本地的文件名,则默认使用原文件名进行保存;如果指定文件名,则按照指定的文件名保存在本地。下载失败的文件列表输出到fail.txt。

./ks3util cp ks3://examplebucket/desPath/examplefile.txt LocalPath/ -f fail.txt

输出:下载后的文件路径。

[Download]File write to /home/user/ks3util-1.2.2/LocalPath/examplefile.txt
  • 下载文件夹和文件夹下的所有文件(包括子文件夹和子文件夹中的文件)。下载失败的文件列表输出到fail.txt。
./ks3util cp ks3://examplebucket/desPath/ LocalPath/ -f fail.txt

输出:包括下载后的文件路径。

[Download]OK   LocalPath/desPath/examplefile.txt[success:1/total:1]

[Download] DONE,totalKeys=1,filterFetchNum=1,SuccessTotalNum=1,findRepeatNum=0,failKeys=0
  • 下载文件时,不下载名称中包含txt的object。
./ks3util cp ks3://examplebucket/Path/ LocalPath/ -f fail.txt -exclude txt
  • 下载本地文件时,仅下载名称中包含txt的object。
./ks3util cp ks3://examplebucket/Path/ LocalPath/ -f fail.txt -include txt

6. 移动对象

描述

mv命令可以批量移动本地路径下的文件到KS3 bucket中,或者批量移动KS3中的对象到本地,或者在KS3 bucket之间移动对象,移动之后会删除源对象。当移动的文件较大时,mv命令将自动使用分块上传和断点续传。

命令格式

移动本地路径下的文件到KS3 bucket

./ks3util mv LocalPath ks3://bucketName/objectPath [-a|--acl acl] [-c config_file] [-exclude exclude_pattern] <-f fail_keys_file> [-i upload_hidden_files] [-include include_pattern] [-r use_relative_path] [-s|--storageclass storage_class] [--update|-u update_exist_files] [-z use_last_dir_name]

移动KS3中的对象到本地

./ks3util mv ks3://bucketName/objectPath LocalPath/ [-c config_file] [-exclude exclude_pattern] <-f fail_keys_file> [-include include_pattern] 

在KS3 bucket之间移动对象

./ks3util mv ks3_path ks3_path [-exclude exclude_pattern] <-f fail_keys_file> [-include include_pattern]

常用参数

参数名称 描述
LocalPath 本地文件路径。例如Linux系统文件路径/localPath/examplefile.txt,Windows系统文件路径D:\localPath\examplefile.txt。也可以配置为本地目录,表示移动目录下的文件。
bucketName Bucket名称。
objectPath 将Object移动到Bucket指定路径下。
-a 设置文件的ACL权限,枚举值:Private(私有),PublicRead(公共读),默认Private。
-c 指定ks3util配置文件的路径。
-exclude 不移动包含指定名称的Object(模糊匹配),多个Object名称用英文逗号分隔。
-f 导出移动失败的Object列表文件。
-i 是否移动隐藏文件,枚举值:yes,no(默认)
-include 仅移动包含指定名称的Object(模糊匹配),多个Object名称用英文逗号分隔。
-r 路径是否是相对路径,枚举值:yes,no
-s 指定文件的存储类型 枚举值:STANDARD(标准存储)、STANDARD_IA(低频存储)、ARCHIVE(归档存储),默认跟随bucket存储类型。
-u 移动时如bucket中已有同名文件存在的处理方式,枚举值: 0(根据最后修改时间判断是否重传,新文件覆盖旧文件),1(最后修改时间或文件大小判断是否重传),2(全部覆盖),3(全部跳过),默认是0。
-z 是否将文件所在的当前目录名称作为object名称前缀,枚举值:yes(默认),no。

使用示例

以Linux系统为例,进行移动文件的操作。您在实际使用中,请根据您的系统和使用环境修改对应参数。

  • 本地文件:examplefile.txt(相对目录下的文件)

  • 本地文件夹:LocalPath(相对目录下的文件夹)

  • 目标Bucket:examplebucket

  • 目标Bucket指定目录:desPath

  • 移动单个文件到KS3,如果不指定移动至KS3的文件名,则默认使用原文件名进行保存;如果指定文件名,则按照指定的文件名保存在KS3中。移动失败的文件列表输出到fail.txt。

./ks3util mv examplefile.txt ks3://examplebucket/desPath/ -f fail.txt

输出:包括移动的文件名称,文件个数,文件大小,重复文件个数,失败文件个数,上传时长等信息。

[Upload] SUCCESS objectKey:des/sample.conf storageClass:STANDARD [success:1/total:1]
[Upload DONE]totalKeys=1,filterFetchNum=0,SuccessTotalNum=1,SuccessFileSize=0,repeatNum=0,failedNum=1 cost=2082
  • 移动文件夹和文件夹下的所有文件到KS3(包括子文件夹和子文件夹中的文件)到KS3。移动失败的文件列表输出到fail.txt。
./ks3util mv LocalPath/ ks3://examplebucket/desPath/ -f fail.txt
  • 移动本地文件到KS3时,指定文件权限为公有读。
./ks3util mv LocalPath/ ks3://examplebucket/Path/ -f fail.txt -a PublicRead
  • 移动本地文件到KS3时,不移动名称中包含txt的object。
./ks3util mv LocalPath/ ks3://examplebucket/Path/ -f fail.txt -exclude txt
  • 移动本地文件到KS3时,仅移动名称中包含txt的object。
./ks3util mv LocalPath/ ks3://examplebucket/Path/ -f fail.txt -include txt
  • 移动本地文件到KS3时,使用绝对路径方式指定本地路径。
./ks3util mv /home/user/LocalPath/ ks3://examplebucket/Path/ -f fail.txt -r no
  • 移动本地文件到KS3时,设置文件存储类型为低频存储。
./ks3util mv LocalPath/ ks3://examplebucket/Path/ -f fail.txt -s STANDARD_IA
  • 移动本地文件到KS3时,如KS3 bucket中已有同名文件存在,则全部覆盖。
./ks3util mv LocalPath/ ks3://examplebucket/Path/ -f fail.txt -u 2
  • 移动本地文件到KS3时,不将文件所在的当前目录名称作为object名称前缀
./ks3util mv /home/user/LocalPath/ ks3://examplebucket/Path/ -f fail.txt -z no
  • 从KS3移动单个文件到本地,如果不指定下载到本地的文件名,则默认使用原文件名进行保存;如果指定文件名,则按照指定的文件名保存在本地。移动失败的文件列表输出到fail.txt。
./ks3util mv ks3://examplebucket/desPath/examplefile.txt LocalPath/ -f fail.txt

输出:下载后的文件路径。

[Download]File write to /home/user/ks3util-1.2.2/LocalPath/examplefile.txt
  • 从KS3移动文件夹和文件夹下的所有文件(包括子文件夹和子文件夹中的文件)到本地。移动失败的文件列表输出到fail.txt。
./ks3util mv ks3://examplebucket/desPath/* LocalPath/ -f fail.txt
  • 在KS3之间移动单个文件,目标bucket中的文件名与源文件名相同,移动失败的文件列表输出到fail.txt。
./ks3util mv ks3://examplebucket1/srcPath/examplefile.txt ks3://examplebucket2/desPath/ -f fail.txt

第一次移动对象时,需要配置目标bucket对应的域名Endpoint,Access Key ID和Access Secret Key。配置之后,ks3util默认将配置信息保存在sample.conf配置文件。

配置完成后可以移动对象,并输出移动的文件名称,文件个数等信息。

请输入目标账户AK

AKLTYS2***********

请输入目标账号SK

OE23G**********

请输入目标账号ENDPOINT

ks3-cn-beijing.ksyuncs.com



[Move] SUCCESS examplefile.txt[success:1/total:1]
[Move] DONE,totalKeys=1,SuccessTotalNum=1,filterFetchNum=0,repeatNum=0,failedNum=0
  • 批量移动多个文件,将examplebucket1中srcPath目录下的文件批量移动到examplebucket2的desPath目录下。
./ks3util mv ks3://examplebucket1/srcPath/* ks3://examplebucket2/desPath/ -f fail.txt

7. 删除存储空间或对象

描述

rm命令用于删除存储空间桶(Bucket)或对象(Object)。

命令格式

./ks3util rm ks3://bucketName[/objectPath] [-b] [-c] [-exclude] [-f] [-include] [-r]

常用参数

参数名 描述
bucketName bucket名称
objectPath 删除指定路径下的对象
-b 删除存储空间,删除前请先删除存储空间下的所有对象。
-c 指定ks3util配置文件的路径。
-exclude 不删除包含指定名称的Object(模糊匹配),多个Object名称用英文逗号分隔。
-f 导出删除失败的Object列表文件。
-include 仅删除包含指定名称的Object(模糊匹配),多个Object名称用英文逗号分隔。
-r 失败重试次数

使用示例

以Linux系统为例,删除KS3中的bucket或者object。您在实际使用中,请根据您的系统和使用环境修改对应参数。

  • 文件:examplefile.txt

  • Bucket:examplebucket

  • 删除指定Bucket下的指定object

./ks3util rm ks3://examplebucket/Path/examplefile.txt -f fail.txt

输出:包括删除的对象名称,对象个数,删除时长等信息。

[RM]delete Success :Path/examplefile.txt

[RM]Done:totalKeys=1, deleted =1,filter Intercepts=0, failKeys=0 ,cost=326 ms,Check log for more information
  • 删除指定Bucket下某目录中所有文件
./ks3util rm ks3://examplebucket/Path/ -f fail.txt

输出:包括删除的对象名称,对象个数,删除时长等信息。

[RM]delete Success :Path/3.txt

[RM]delete Success :Path/1.txt

[RM]delete Success :Path/2.txt

[RM]delete Success :Path/

[RM]Done:totalKeys=4, deleted =4,filter Intercepts=0, failKeys=0 ,cost=362 ms,Check log for more information
  • 删除空的Bucket
./ks3util rm ks3://examplebucket -b -f fail.txt

8. 修改元数据

描述

multiChangeMeta命令用于批量修改对象元数据信息。

./ks3util multiChangeMeta ks3_path [-a acl] [-c] [-f fail_Keys_file] [-i meta_info] [-m metaType] [-s storage_class]

常用参数

选项名称 描述
ks3_path 可以修改单个对象的元数据信息,格式为ks3://bucketname/objectname。也可以批量修改对象的元数据信息,格式为ks3://examplebucket/prefix/。
-a 设置文件的ACL权限,枚举值:Private(私有),PublicRead(公共读),默认Private。
-c 指定ks3util配置文件的路径。
-f 导出修改失败的Object列表文件。
-i 设置的元数据信息,格式为 key=value#key=value 使用utf-8编码,自定义的元素头将保存为以x-kss-meta开头。
-m 操作类型,枚举值:add (新增元数据),rewrite (修改元数据)。
-s 指定文件的存储类型 枚举值:STANDARD(标准存储)、STANDARD_IA(低频存储)、ARCHIVE(归档存储),默认跟随bucket存储类型。

使用示例

以Linux系统为例,修改KS3中对象的元数据信息。您在实际使用中,请根据您的系统和使用环境修改对应参数。

  • 文件:examplefile.txt

  • Bucket:examplebucket

  • 对以prefix为开头的所有对象,新增自定义元数据

./ks3util multiChangeMeta ks3://examplebucket/prefix/ -f fail.txt -m add -i yourMetaKey1=yourMetaValue1#yourMetaKey2=yourMetaValue2

输出以下信息,包括各个对象的元数据。

{x-kss-metadata-directive=REPLACE, ETag=d41d8cd98f00b204e9800998ecf8427e, Ctime=Fri, 15 Oct 2021 08:02:09 GMT, x-kss-acl=public-read, Last-Modified=Fri Oct 15 16:02:09 CST 2021, x-kss-meta-yourMetaKey2=yourMetaValue2, Content-Length=0, x-kss-meta-yourMetaKey1=yourMetaValue1,Content-Type=application/octet-stream, Content-MD5=1B2M2Y8AsgTpgAmY7PhCfg==}

{x-kss-metadata-directive=REPLACE, ETag=bbb8aae57c104cda40c93843ad5e6db8, Ctime=Fri, 15 Oct 2021 08:02:20 GMT, x-kss-acl=public-read, Last-Modified=Fri Oct 15 16:02:20 CST 2021, x-kss-meta-yourMetaKey2=yourMetaValue2, Content-Length=9, x-kss-meta-yourMetaKey1=yourMetaValue1, Content-Type=text/plain, Content-MD5=u7iq5XwQTNpAyThDrV5tuA==}

success key = prefix/

success key = prefix/1.txt

All files change meta success,totalKeys=2,filterFetchKeys=0,failKeys=0
  • 对以prefix为开头的所有对象,修改自定义元数据
./ks3util multiChangeMeta ks3://examplebucket/prefix/ -f fail.txt -m rewrite -i yourMetaKey1=yourMetaValue11

输出以下信息,包括各个对象的元数据。

{x-kss-metadata-directive=REPLACE, ETag=d41d8cd98f00b204e9800998ecf8427e, Ctime=Fri, 15 Oct 2021 08:02:09 GMT, x-kss-acl=public-read, Last-Modified=Fri Oct 15 16:02:55 CST 2021, Content-Length=0, x-kss-meta-yourMetaKey1=yourMetaValue11, Content-Type=application/octet-stream, Content-MD5=1B2M2Y8AsgTpgAmY7PhCfg==}

{x-kss-metadata-directive=REPLACE, ETag=bbb8aae57c104cda40c93843ad5e6db8, Ctime=Fri, 15 Oct 2021 08:02:20 GMT, x-kss-acl=public-read, Last-Modified=Fri Oct 15 16:02:55 CST 2021, Content-Length=9, x-kss-meta-yourMetaKey1=yourMetaValue11, Content-Type=text/plain, Content-MD5=u7iq5XwQTNpAyThDrV5tuA==}

success key = prefix/

success key = prefix/1.txt

All files change meta success,totalKeys=2,filterFetchKeys=0,failKeys=0
  • 修改单个对象的自定义元数据,并设置访问权限为公有读,存储类型为低频。
./ks3util multiChangeMeta ks3://examplebucket/prefix/ -f fail.txt -m rewrite -i yourMetaKey1=yourMetaValue11 -a PublicRead -s STANDARD_IA

输出以下信息,包括各个对象的元数据。

{x-kss-metadata-directive=REPLACE, x-kss-storage-class=STANDARD_IA, ETag=bbb8aae57c104cda40c93843ad5e6db8, Ctime=Fri, 15 Oct 2021 08:02:20 GMT, x-kss-acl=public-read, Last-Modified=Fri Oct 15 17:33:48 CST 2021, Content-Length=9, x-kss-meta-yourMetaKey1=yourMetaValue11, Content-Type=text/plain, Content-MD5=u7iq5XwQTNpAyThDrV5tuA==}

{x-kss-metadata-directive=REPLACE, x-kss-storage-class=STANDARD_IA, ETag=d41d8cd98f00b204e9800998ecf8427e, Ctime=Fri, 15 Oct 2021 08:02:09 GMT, x-kss-acl=public-read, Last-Modified=Fri Oct 15 17:33:48 CST 2021, Content-Length=0, x-kss-meta-yourMetaKey1=yourMetaValue11, Content-Type=application/octet-stream, Content-MD5=1B2M2Y8AsgTpgAmY7PhCfg==}

success key = prefix/1.txt

success key = prefix/

All files change meta success,totalKeys=2,filterFetchKeys=0,failKeys=0

9. 设置ACL

描述

setAcl指令可以批量设置文件的权限ACL。

命令格式

./ks3util setAcl ks3_path <-a> [-c] [-exclude exclude_pattern] [-include include_pattern]

常用参数

选项名称 描述
ks3_path 可以设置单个对象的ACL,格式为ks3://bucketname/objectname。也可以批量设置对象的元数据信息,格式为ks3://examplebucket/prefix/。
-a 设置文件的ACL权限,枚举值:Private(私有),PublicRead(公共读),默认Private。
-c 指定ks3util配置文件的路径。
-exclude 不设置包含指定名称的Object(模糊匹配),多个Object名称用英文逗号分隔。
-include 仅设置包含指定名称的Object(模糊匹配),多个Object名称用英文逗号分隔。

使用示例

以Linux系统为例,修改KS3中对象的元数据信息。您在实际使用中,请根据您的系统和使用环境修改对应参数。

  • 文件:examplefile.txt

  • Bucket:examplebucket

  • 设置单个文件的ACL权限。

./bin/ks3util setAcl ks3://examplebucket/examplefile.txt -a Private

批量设置prefix目录下的多个文件的ACL权限。

./bin/ks3util setAcl ks3://examplebucket/prefix -a Private

10. 计算对象总大小

描述

du命令用于计算对象(Object)总大小。

命令格式

./ks3util du ks3://bucketName[/objectPath] [-c] [-exclude] [-f] [-include] [-r]

常用参数

参数名称 描述
bucketName Bucket名称
objectPath 统计objectPath下的所有对象大小,如果不填写,则统计Bucket中的所有对象大小。
-c 指定ks3util配置文件的路径。
-exclude 不统计包含指定名称的Object(模糊匹配),多个Object名称用英文逗号分隔。
-include 仅统计包含指定名称的Object(模糊匹配),多个Object名称用英文逗号分隔。
-m 列举名称字母排序在marker之后的Object。

使用示例

以Linux系统为例,统计KS3 Bucket中的对象大小。您在实际使用中,请根据您的系统和使用环境修改对应参数。

  • Bucket:examplebucket

  • Bucket指定目录:desPath

  • 统计Bucket中desPath目录下的所有对象大小

./ks3util du ks3://examplebucket/desPath 

输出:包括统计的对象个数,对象总大小,统计时长等信息。

list 17 object, cost 581 ms
total num 17 个
total size 14672097 Bytes, 13.99 MB

六、配置文件

1.2.0之后的版本,可在第一次执行KS3Util命令时以交互方式填写配置信息,KS3Util将生成sample.conf配置文件,无需用户手动填写配置文件。用户可以手动修改配置文件中的参数,各参数含义如下。

字段 说明 是否必填
ks3.ak 账户AK,参考获取AK/SK。
ks3.sk 账户SK,参考获取AK/SK。
ks3.endpoint bucket所在region的endpoint,对应列表参看官方文档。
http.conn.timeout http连接超时,默认为10000ms,一般不需要更改。
http.so.timeout http通讯超时,默认为10000ms,一般不需要更改。
http.max.connections http连接数,默认值:100。
async.queuesize 批量处理时的队列长度,默认:200,该值越大内存使用率越大。
async.max.threads 批量处理时最大并发数,默认:100。
async.core.threads 批量处理时最小并发数,默认:4。
ks3.movedest.ak cp和multi-move操作时的目标账号AK。 cp 和 multi-move操作时必填
ks3.movedest.sk cp和multi-move操作时的目标账号SK。 cp 和 multi-move操作时必填
ks3.movedest.endpoint cp和multi-move操作时的目标Bucket所在的endpoint。 cp 和 multi-move操作时必填

七、 常见问题

  • KS3Util工具上传同名文件时,会覆盖还是跳过?
    KS3Util工具上传文件时,可以设置-u参数,取值为:0(根据最后修改时间判断是否重传,新文件覆盖旧文件),1(根据最后修改时间或文件大小判断是否重传),2(全部覆盖),3(全部跳过),默认是0。您可以根据实际需要设置参数值。

  • KS3Util工具最大支持上传多大的文件?
    KS3单个文件(对象)最大支持48.8TB。KS3Util上传大文件时,会自动进行切分,通过分块上传的方式上传大文件。

  • KS3Util工具传输大量文件时,如何提高传输速度?
    可适当调整配置文件中的http.max.connections 参数值,来增加并发处理的线程数。

  • KS3Util工具可以同时管理多个账号的存储空间吗?
    KS3Util配置文件中只能配置一个账号,如您需要管理不同账号下的存储空间,可以保存多个账号的配置文件,在执行KS3Util命令时,通过-c参数来指定不同的配置文件,从而达到切换账号的效果。例如

./bin/ks3util ls -b -c user1_config.conf
  • KS3Util工具执行异常时,如何排查问题?
    KS3Util工具在执行操作时,会记录日志,目录是KS3Util的安装路径/logs,您可以通过日志初步排查问题,或者将错误日志发送给我们排查。

  • 配置文件中的Access Key ID和Access Secret Key都填写正确,但是执行KS3Util命令失败,是什么原因?
    请检查安装KS3Util工具的服务器时间是否正确,如果与标准时间相差15分钟以上,将无法执行操作。

  • KS3Util工具上传文件时,如何排除某些目录或某些文件?
    上传文件时,可以通过-exclude参数来排除某些目录和文件。例如,要上传LocalPath/中的目录和文件,并排除mp4目录下的文件,和文件名中包含mp4的文件。

./ks3util cp LocalPath/ ks3://examplebucket/desPath -f fail.txt -exclude mp4

文档内容是否对您有帮助?

根本没帮助
文档较差
文档一般
文档不错
文档很好

在文档使用中是否遇到以下问题

内容不全,不深入
内容更新不及时
描述不清晰,比较混乱
系统或功能太复杂,缺乏足够的引导
内容冗长

更多建议

0/200

评价建议不能为空

提交成功!

非常感谢您的反馈,我们会继续努力做到更好!

问题反馈