最近更新时间:2024-12-13 18:50:37
本文以 Linux系统为例,介绍使用 KS3Util工具的对象操作的命令和相关示例。
cp命令可以用于将本地文件上传至KS3。
./ks3util cp file_url cloud_url
[-r, --recursive]
[-f, --force]
[-u, --update]
[--bigfile-threshold <value>]
[--part-size <value>]
[--only-current-dir]
[--acl <value>]
[--meta <value>]
[--tagging <value>]
[--include <value>]
[--exclude <value>]
[-j, --jobs <value>]
[--parallel <value>]
[--checkpoint-dir <value>]
[--disable-crc64]
[--enable-symlink-dir]
[--cycle-symlink-check]
参数 | 说明 |
---|---|
file_url | 本地文件或目录路径。 |
cloud_url | KS3文件路径,格式为ks3://bucketname/objectname。 |
-r, --recursive | 递归进行操作。对于支持该选项的命令,当指定该选项时,命令会对目录下所有符合条件的文件进行操作,否则只对file_url中指定的单个文件进行操作。 |
-f, --force | 强制操作,不进行询问提示。 |
-u, --update | 更新操作,只有当目标文件不存在,或源文件的最后修改时间晚于目标文件时,KS3Util才会执行上传操作。 |
--bigfile-threshold | 开启大文件断点续传的文件大小阈值,单位为Byte,默认值:104857600(100M),取值范围:0-5368709120(Byte)。 |
--part-size | 分片大小,单位为Byte,默认情况下KS3Util根据文件大小自行计算合适的分片大小值。如果有特殊需求或者需要性能调优,可以设置该值,取值范围:1-5368709120(Byte)。 |
--only-current-dir | 表示仅操作当前目录下的文件,忽略子目录。 |
--acl | acl信息的配置。 |
--meta | 设置Object的meta为[header:value#header:value…],如:Cache-Control:no-cache#Content-Encoding:gzip。 |
--tagging | 设置Object的tagging,取值格式如 |
--include | 包含对象匹配模式,如:*.jpg。 |
--exclude | 不包含对象匹配模式,如:*.txt。 |
-j, --jobs | 多文件操作时的并发数,默认值:3,取值范围:1-10000。 1. 该参数决定有多少个文件并行上传。 2. 批量操作文件时适合调整该参数。 |
--parallel | 单文件内部操作的并发任务数,取值范围:1-10000。 1. 默认KS3 Util会根据操作类型和文件大小自动决定,自动取值范围是1-12。 2. 该参数决定单个文件有多少个块并行上传。 3. 操作单个大文件时适合调整该参数。 4. 总并发数= jobs * parallel。 |
--checkpoint-dir | checkpoint目录的路径(默认值为:.ks3util_checkpoint),断点续传时,操作失败KS3Utill会自动创建该目录,并在该目录下记录checkpoint信息,操作成功会删除该目录。如果指定了该选项,请确保所指定的目录可以被删除。 |
--disable-crc64 | 关闭CRC64数据校验。默认情况下,KS3Util进行数据传输时都会打开CRC64校验。 |
--enable-symlink-dir | 表示允许上传软链接子目录指向的源文件。使用该参数请确保软链接无循环嵌套情况,否则可能存在数据循环上传风险。可通过 |
--cycle-symlink-check | 表示上传之前进行软链接循环检测 |
示例一:上传单文件,上传文件时,如果dest_prefix以/结尾,则objectKey为dest_prefix + 原文件名,否则objectKey为dest_prefix。
# 例1: 上传后的对象为ks3://samplebucket/abc/sample.txt
./ks3util cp /home/sample.txt ks3://samplebucket/abc/
# 例2: 上传后的对象为ks3://samplebucket/abc
./ks3util cp /home/sample.txt ks3://samplebucket/abc
示例二:上传文件夹,将文件夹(包括子文件夹)内的文件上传至KS3指定路径。使用-r选项时,如果指定路径不以/结尾,则会自动加上/。
# 例1: 假设有以下文件
# /home/logs/a.log
# /home/logs/bak/b.log
# 上传后的文件为
# ks3://samplebucket/my-files/a.log
# ks3://samplebucket/my-files/bak/a.log
./ks3util cp /home/logs/ ks3://samplebucket/my-files/ -r
1. 如果需要保留文件夹名,则指定路径需以文件夹名结尾。
2. 当文件夹内存在软链接子目录时,默认会把软链接子目录当成一个空文件上传,不会上传软链接子目录对应的源文件。KS3Util提供了--enable-symlink-dir
参数支持上传软链接子目录指向的源文件。
示例三:上传文件夹,上传软链接子目录指向的源文件。
./ks3util cp local_dir ks3://samplebcket/dest_prefix/ -r --enable-symlink-dir
示例四:上传文件夹,上传软链接子目录指向的源文件,且在上传之前进行软链接循环嵌套风险检测。
./ks3util cp local_dir ks3://samplebcket/dest_prefix/ -r --enable-symlink-dir --cycle-symlink-check
示例五:仅上传当前目录下的文件,忽略子目录下的文件。
./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r --only-current-dir
示例六:上传文件夹内的文件,并跳过已存在的文件
批量上传失败重传时,可以指定–update(可缩写为-u)选项跳过已经上传成功的文件,实现增量上传。
./ks3util cp local_dir ks3://samplebcket/dest_prefix/ -r -u
示例七:上传文件并指定读写权限ACL。
./ks3util cp sample.txt ks3://samplebucket/sample.txt --acl private
示例八:上传文件并指定存储类型。
./ks3util cp sample.txt ks3://samplebucket/sample.txt --storage-class STANDARD
示例九:上传文件并指定meta。
./ks3util cp sample.txt ks3://samplebucket/sample.txt --meta Content-Type:text/plain#Cache-Control:no-cache#X-Kss-Meta-A:a
示例十:上传文件并指定标签tagging。
./ks3util cp sample.txt ks3://samplebucket/sample.txt --tagging "a=1&b=2"
示例十一:上传符合条件的文件
上传文件夹中,文件后缀包含.txt
的文件。
./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r --include "*.txt"
上传文件夹时,如果指定--include
和--exclude
选项,KS3Util会上传符合指定条件的文件。
上传文件夹中,文件后缀包含.txt
的文件,使用正则匹配模式。
./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r --enable-regex --include ".*\.txt"
上传文件夹中,文件路径包含20240626的文件,使用正则匹配模式。
./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r --enable-regex --path-matching --include ".*20240626.*"
上传文件夹中,文件后缀包含.png
,但排除文件名中有temp
的文件,使用正则匹配模式。
./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r --enable-regex --include ".*\.png" --exclude ".*temp.*"
上传文件夹中,文件路径包含20240626,但排除文件后缀为.txt
的文件,使用正则匹配模式。
./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r --enable-regex --path-matching --include ".*20240626.*" --exclude ".*\.txt"
cp命令可以用于将存储于KS3的文件下载到本地。
./ks3util cp cloud_url file_url
[-r, --recursive]
[-f, --force]
[-u, --update]
[--bigfile-threshold <value>]
[--part-size <value>]
[--include <value>]
[--exclude <value>]
[-j, --jobs <value>]
[--parallel <value>]
[--checkpoint-dir <value>]
[--disable-crc64]
参数 | 说明 |
---|---|
file_url | 本地文件或目录路径。 |
cloud_url | KS3文件路径,格式为ks3://bucketname/objectname。 |
-r, --recursive | 递归进行操作。对于支持该选项的命令,当指定该选项时,命令会对目录下所有符合条件的文件进行操作,否则只对file_url中指定的单个文件进行操作。 |
-f, --force | 强制操作,不进行询问提示。 |
-u, --update | 更新操作,只有当目标文件不存在,或源文件的最后修改时间晚于目标文件时,KS3Util才会执行上传操作。 |
--bigfile-threshold | 开启大文件断点续传的文件大小阈值,单位为Byte,默认值:104857600(100M),取值范围:0-5368709120(Byte)。 |
--part-size | 分片大小,单位为Byte,默认情况下KS3Util根据文件大小自行计算合适的分片大小值。如果有特殊需求或者需要性能调优,可以设置该值,取值范围:1-5368709120(Byte)。 |
--only-current-dir | 表示仅操作当前目录下的文件,忽略子目录。 |
--tagging | 设置Object的tagging,取值格式如 |
--include | 包含对象匹配模式,如:*.jpg。 |
--exclude | 不包含对象匹配模式,如:*.txt。 |
-j, --jobs | 多文件操作时的并发数,默认值:3,取值范围:1-10000。 1. 该参数决定有多少个文件并行上传。 2. 批量操作文件时适合调整该参数。 |
--parallel | 单文件内部操作的并发任务数,取值范围:1-10000。 1. 默认KS3 Util会根据操作类型和文件大小自动决定,自动取值范围是1-12。 2. 该参数决定单个文件有多少个块并行上传。 3. 操作单个大文件时适合调整该参数。 4. 总并发数= jobs * parallel。 |
--checkpoint-dir | checkpoint目录的路径(默认值为:.ks3util_checkpoint),断点续传时,操作失败KS3Util会自动创建该目录,并在该目录下记录checkpoint信息,操作成功会删除该目录。如果指定了该选项,请确保所指定的目录可以被删除。 |
--disable-crc64 | 关闭CRC64数据校验。默认情况下,KS3Util进行数据传输时都会打开CRC64校验。 |
示例一:下载单个文件
没有指定文件名,则使用原文件名保存到本地。
./ks3util cp ks3://samplebucket/src-prefix/sample.txt local-dir/
若指定了文件名,使用指定的文件名保存到本地。
./ks3util cp ks3://samplebucket/src-prefix/sample.txt local-dir/sample-file.txt
示例二:下载目录
下载目录下所有文件,包括子目录。
./ks3util cp ks3://samplebucket/src-prefix/ local-dir/ -r
当批量下载失败或需要增量下载文件时,可以通过指定--update
(可缩写为-u)选项选择跳过已经成功下载的文件。如果本地与KS3没有同名文件,或本地同名文件的最后修改时间早于KS3文件,KS3Util会下载该文件。如果本地已有同名文件,且文件的最后修改时间晚于KS3内文件时,KS3Util会跳过该文件。
./ks3util cp ks3://samplebucket/src-prefix/ local-dir/ -r -u
仅下载当前目录下的文件,忽略子目录。
./ks3util cp ks3://samplebucket/src-prefix/ local-dir/ -r --only-current-dir
按规则匹配文件名下载
使用–include和–exclude选项选择符合条件的文件下载。
./ks3util cp ks3://samplebucket/src-prefix/ local-dir/ -r --include *.jpg --exclude *screenshot*
cp命令可用于将存储在KS3的文件复制到同Bucket的其他目录,或同区域的其他Bucket内。
./ks3util cp file_url cloud_url
[-r, --recursive]
[-f, --force]
[-u, --update]
[--bigfile-threshold <value>]
[--part-size <value>]
[--only-current-dir]
[--acl <value>]
[--meta <value>]
[--tagging <value>]
[--include <value>]
[--exclude <value>]
[-j, --jobs <value>]
[--parallel <value>]
[--checkpoint-dir <value>]
参数 | 说明 |
---|---|
file_url | 本地文件或目录路径。 |
cloud_url | KS3文件路径,格式为ks3://bucketname/objectname。 |
-r, --recursive | 递归进行操作。对于支持该选项的命令,当指定该选项时,命令会对目录下所有符合条件的文件进行操作,否则只对file_url中指定的单个文件进行操作。 |
-f, --force | 强制操作,不进行询问提示。 |
-u, --update | 更新操作,只有当目标文件不存在,或源文件的最后修改时间晚于目标文件时,KS3Util才会执行上传操作。 |
--bigfile-threshold | 开启大文件断点续传的文件大小阈值,单位为Byte,默认值:104857600(100M),取值范围:0-5368709120(Byte)。 |
--part-size | 分片大小,单位为Byte,默认情况下KS3Util根据文件大小自行计算合适的分片大小值。如果有特殊需求或者需要性能调优,可以设置该值,取值范围:1-5368709120(Byte)。 |
--only-current-dir | 表示仅操作当前目录下的文件,忽略子目录。 |
--acl | acl信息的配置。 |
--meta | 设置Object的meta为[header:value#header:value…],如:Cache-Control:no-cache#Content-Encoding:gzip。 |
--tagging | 设置Object的tagging,取值格式如 |
--include | 包含对象匹配模式,如:*.jpg。 |
--exclude | 不包含对象匹配模式,如:*.txt。 |
-j, --jobs | 多文件操作时的并发数,默认值:3,取值范围:1-10000。 1. 该参数决定有多少个文件并行上传。 2. 批量操作文件时适合调整该参数。 |
--parallel | 单文件内部操作的并发任务数,取值范围:1-10000。 1. 默认KS3 Util会根据操作类型和文件大小自动决定,自动取值范围是1-12。 2. 该参数决定单个文件有多少个块并行上传。 3. 操作单个大文件时适合调整该参数。 4. 总并发数= jobs * parallel。 |
--checkpoint-dir | checkpoint目录的路径(默认值为:.ks3util_checkpoint),断点续传时,操作失败KS3Util会自动创建该目录,并在该目录下记录checkpoint信息,操作成功会删除该目录。如果指定了该选项,请确保所指定的目录可以被删除。 |
复制单个文件
如果没有指定目标文件名,则使用原文件名保存。
./ks3util cp ks3://samplebucket/src-prefix/sample.txt ks3://samplebucket/dst-prefix/
若指定了目标文件名,则使用指定的文件名保存。
./ks3util cp ks3://samplebucket/src-prefix/sample.txt ks3://samplebucket/dst-prefix/sample-file.txt
按目录复制
复制目录下所有文件,包括子目录。
./ks3util cp ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r
当批量复制失败或需要增量复制时,可以使用--update
(可缩写为-u)选项跳过已存在且最后修改时间晚于原文件的文件。
./ks3util cp ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r -u
仅复制当前目录下的文件,忽略子目录。
./ks3util cp ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r --only-current-dir
按条件复制
使用--include
和--exclude
选项复制符合匹配规则的文件。
./ks3util cp ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r --include *.jpg --exclude *screenshot*
修改目标文件读写权限ACL
./ks3util cp ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r --acl public-read
修改目标文件读存储类型
./ks3util cp ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r --storage-class STANDARD_IA
修改目标文件标签
./ks3util cp ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r --tagging "a=1&b=2"
修改文件meta
./ks3util cp ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r --meta Cache-Control:no-cache#X-Kss-Meta-A:1
append命令用于在已上传的追加类型文件(Appendable Object)末尾直接追加内容。当对象不存在时,使用该命令会创建新对象。
./ks3util append local_file ks3://bucketname/objectname
[--meta <value>]
参数 | 说明 |
---|---|
local_file | 本地文件完整路径。 |
bucketname | 目标Bucket名称。 |
objectname | 目标Object名称。追加上传时可直接将本地文件名称保留为Object名称,也可以自定义上传至Bucket后的Object名称。 |
--meta | 设置Object的meta信息。仅支持在首次追加上传时附加此选项,例如--meta "x-kss-acl:public-read#x-kss-meta-key1:value1"。 Object的meta信息配置完成后,您可以通过set-meta(管理文件元信息)命令修改Object的meta信息。 |
将本地文件sample.txt首次追加上传至目标存储空间samplebucket,并设置meta信息。
./ks3util append sample.txt ks3://samplebucket/sampleobject.txt --meta "x-kss-acl:public-read#x-kss-meta-key1:value1"
以下输出结果表明sample.txt已追加上传至目标Bucket,此时文件大小为25.28MB。
Succeed: The local file size: 25.28MB, The object original size: 0.00B, The object new size: 25.28MB
平均速度:3.32MB/s
7.799511(s) elapsed
在sampleobject.txt文件末尾追加文件sample2.txt的内容。
./ks3util append sample2.txt ks3://samplebucket/sampleobject.txt
以下输出结果已在sampleobject.txt文件后追加了内容,此时文件大小为55.74MB。
Succeed: The local file size: 30.46MB, The object original size: 25.28MB, The object new size: 55.74MB
平均速度:3.37MB/s
9.230269(s) elapsed
如果需要在sampleobject.txt文件末尾多次追加内容,请替换示例中的待追加上传文件再执行命令。
listpart命令用于列举未完成分块上传的Object包含的碎片(Part)信息。
./ks3util listpart ks3://bucketname/objectname uploadId
参数 | 说明 |
---|---|
bucketname | 目标桶名称。 |
objectname | 未完成分块上传操作的对象名称。 |
uploadId | 初始化Multipart Upload事件时返回的KS3服务器创建的全局唯一的Upload ID,用于标识本次Multipart Upload事件。您可以通过Upload ID进行Multipart Upload的中止或查询等操作。 |
列举目标存储空间examplebucket下未完成分块上传的文件exampleobject.txt包含的碎片信息
./ks3util listpart ks3://examplebucket/exampleobject 655d52aa954e4ea1b7556fad6247****
以下返回结果表明已成功获取exampleobject文件的碎片对应的Number、ETag值、碎片大小、碎片的最后修改时间等信息。
PartNumber Etag Size(Byte) LastModifyTime
3 *** 5242880 2024-01-04 14:24:14
4 *** 5242880 2024-01-04 14:24:19
5 *** 5242880 2024-01-04 14:24:14
7 *** 5242880 2024-01-04 14:24:34
total part count: 4 total part size(MB): 20
0.202618(s) elapsed
rm用于删除存储在KS3存储桶内的文件或者碎片。
删除后无法恢复,请谨慎操作!
./ks3util rm ks3://bucketname[/prefix]
[-r, --recursive]
[-f, --force]
[-b, --bucket]
[-m, --multipart]
[-a, --all-type]
[--include <value>]
[--exclude <value>]
[--only-current-dir]
参数 | 说明 |
---|---|
bucketname | 操作的桶名。 |
prefix | 操作的对象的前缀。 |
-r, --recursive | 递归进行操作。对于支持该选项的命令,当指定该选项时,命令会对目录下所有符合条件的文件进行操作,否则只对file_url中指定的单个文件进行操作。 |
-f, --force | 强制操作,不进行询问提示。 |
-b, --bucket | 对Bucket进行操作,该选项用于确认操作作用于Bucket。 |
-m, --multipart | 指定操作的对象为Bucket中未完成的Multipart事件,而非默认情况下的Object。 |
-a, --all-type | 指定操作的对象为Bucket中符合prefix条件的Object和未完成的Multipart事件。 |
--include | 包含对象匹配模式,如:*.jpg。 |
--exclude | 不包含对象匹配模式,如:*.txt。 |
--only-current-dir | 表示仅操作当前目录下的文件,忽略子目录。 |
a.删除文件
示例一:删除单个文件
./ks3util rm ks3://samplebucket/src-prefix/sample.txt
示例二:批量删除文件
删除指定前缀的文件。
./ks3util rm ks3://samplebucket/src-prefix/ -r
按匹配条件删除。
./ks3util rm ks3://samplebucket/src-prefix/ -r --include *screenshot* --exclude *important*
按指定列表文件进行删除。
./ks3util rm ks3://samplebucket/ --object-file object_keys_file
注:object_keys_file为本地.txt文件的路径,文件内填写指定Object列表,每个objectKey为一行(不包含ks3://bucket/ 部分)。
示例三:删除指定目录下的文件,不递归子目录
./ks3util rm ks3://samplebucket/abc/ -r --only-current-dir
b.删除碎片
示例一:删除单文件碎片
删除单个文件未完成的Multipart事件产生的Part。
./ks3util rm ks3://samplebucket/src-prefix/sample.txt -m
删除单个文件、以及未完成的Multipart事件所产生的Part。
./ks3util rm ks3://samplebucket/src-prefix/sample.txt -a
示例二:删除指定前缀文件碎片
删除指定前缀的所有文件未完成的Multipart事件产生的Part。
./ks3util rm ks3://samplebucket/src-prefix/ -m -r
删除指定前缀的所有文件、以及未完成的Multipart事件所产生的Part。
./ks3util rm ks3://samplebucket/src-prefix/ -a -r
删除匹配条件的文件未完成的Multipart事件产生的Part。
./ks3util rm ks3://samplebucket/src-prefix/ -m -r --include *screenshot* --exclude *important*
删除匹配条件的文件、以及未完成的Multipart事件产生的Part。
./ks3util rm ks3://samplebucket/src-prefix/ -a -r --include *screenshot* --exclude *important*
mv命令可用于将存储在KS3的文件移动到同Bucket的其他目录,或同区域的其他Bucket内。
./ks3util mv file_url cloud_url
[-r, --recursive]
[-f, --force]
[-u, --update]
[--bigfile-threshold <value>]
[--part-size <value>]
[--only-current-dir]
[--acl <value>]
[--meta <value>]
[--tagging <value>]
[--include <value>]
[--exclude <value>]
[-j, --jobs <value>]
[--parallel <value>]
[--checkpoint-dir <value>]
参数 | 说明 |
---|---|
file_url | 本地文件或目录路径。 |
cloud_url | KS3文件路径,格式为ks3://bucketname/objectname。 |
-r, --recursive | 递归进行操作。对于支持该选项的命令,当指定该选项时,命令会对目录下所有符合条件的文件进行操作,否则只对file_url中指定的单个文件进行操作。 |
-f, --force | 强制操作,不进行询问提示。 |
-u, --update | 更新操作,只有当目标文件不存在,或源文件的最后修改时间晚于目标文件时,KS3Util才会执行上传操作。 |
--bigfile-threshold | 开启大文件断点续传的文件大小阈值,单位为Byte,默认值:104857600(100M),取值范围:0-5368709120(Byte)。 |
--part-size | 分片大小,单位为Byte,默认情况下KS3Util根据文件大小自行计算合适的分片大小值。如果有特殊需求或者需要性能调优,可以设置该值,取值范围:1-5368709120(Byte)。 |
--only-current-dir | 表示仅操作当前目录下的文件,忽略子目录。 |
--acl | acl信息的配置。 |
--meta | 设置Object的meta为[header:value#header:value…],如:Cache-Control:no-cache#Content-Encoding:gzip。 |
--tagging | 设置Object的tagging,取值格式如 |
--include | 包含对象匹配模式,如:*.jpg。 |
--exclude | 不包含对象匹配模式,如:*.txt。 |
-j, --jobs | 多文件操作时的并发任务数,默认值:3,取值范围:1-10000。 1. 该参数决定有多少个文件并行拷贝。 2. 批量操作文件时适合调整该参数。 |
--parallel | 单文件内部操作的并发任务数,取值范围:1-10000。 1. 默认KS3 Util会根据操作类型和文件大小自动决定,自动取值范围是1-12。 2. 该参数决定单个文件有多少个块并行拷贝。 3. 操作单个大文件时适合调整该参数。 4. 总并发数= jobs * parallel。 |
--checkpoint-dir | checkpoint目录的路径(默认值为:.ks3util_checkpoint),断点续传时,操作失败KS3Util会自动创建该目录,并在该目录下记录checkpoint信息,操作成功会删除该目录。如果指定了该选项,请确保所指定的目录可以被删除。 |
示例一:移动单个文件
若没有指定目标文件名,则使用原文件名保存。
./ks3util mv ks3://samplebucket/src-prefix/sample.txt ks3://samplebucket/dst-prefix/
若指定了目标文件名,则使用指定的文件名保存。
./ks3util mv ks3://samplebucket/src-prefix/sample.txt ks3://samplebucket/dst-prefix/sample-file.txt
示例二:按目录移动
移动目录下所有文件,包括子目录。
./ks3util mv ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r
当批量移动失败或需要增量移动时,可以使用--update
(可缩写为-u)选项跳过已存在且最后修改时间晚于原文件的文件。
./ks3util mv ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r -u
仅移动当前目录下的文件,忽略子目录。
./ks3util mv ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r --only-current-dir
按条件移动
使用--include
和--exclude
选项移动符合匹配规则的文件。
./ks3util mv ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r --include *.jpg --exclude *screenshot*
移动文件并修改文件读写权限ACL。
./ks3util mv ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r --acl public-read
移动文件并修改文件读存储类型。
./ks3util mv ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r --storage-class STANDARD_IA
移动文件并修改文件标签。
./ks3util mv ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r --tagging "a=1&b=2"
移动文件并修改文件meta。
./ks3util mv ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r --meta Cache-Control:no-cache#X-Kss-Meta-A:1
mkdir命令用于在Bucket中创建目录。
./ks3util mkdir ks3://bucketname/dir_name
参数 | 说明 |
---|---|
bucketname | 目标Bucket名称。 |
dir_name | 创建的目录名称。目录名称须以正斜线(/)结尾。若未添加正斜线(/),KS3Util会在目录末尾自动添加。 |
创建单级目录
./ks3util mkdir ks3://samplebucket/sampledir/
创建多级目录
./ks3util mkdir ks3://samplebucket/sampledir/subdir/
如果删除了subdir/目录,且上一级目录sampledir/下文件个数为0,则sampledir/目录也会被自动移除。
set-acl命令用于设置Object的读写权限ACL。
./ks3util set-acl ks3://bucketname[/prefix] <acl>
[-r, --recursive]
[-f, --force]
[-b, --bucket]
[--include <value>]
[--exclude <value>]
[-j, --jobs]
参数 | 说明 |
---|---|
bucketname | 操作的桶名。 |
prefix | 操作的对象的前缀。 |
acl | 读写权限ACL,可选值:private,public-read。 |
-r, --recursive | 递归进行操作。对于支持该选项的命令,当指定该选项时,命令会对目录下所有符合条件的文件进行操作,否则只对指定的单个文件进行操作。 |
f, --force | 强制操作,不进行询问提示。 |
-b, --bucket | 对Bucket进行操作,该选项用于确认操作作用于Bucket。 |
--include | 包含对象匹配模式,如:*.jpg。 |
--exclude | 不包含对象匹配模式,如:*.txt。 |
-j, --jobs | 多文件操作时的并发任务数,默认值:3,取值范围:1-10000。 |
示例一:给单个文件设置acl
./ks3util set-acl ks3://samplebucket/src-prefix/sample.txt private
示例二:批量设置acl
批量给指定前缀的文件设置acl。
./ks3util set-acl ks3://samplebucket/src-prefix/ private -r
批量给符合匹配规则的文件设置acl。
./ks3util set-acl ks3://samplebucket/src-prefix/ private -r --include *screenshot* --exclude *important*
批量给指定列表文件设置acl。
./ks3util set-acl ks3://samplebucket/ public-read --object-file object_keys_file
object_keys_file为本地.txt文件的路径,文件内填写指定Object列表,每个objectKey为一行(不包含ks3://bucket/ 部分)。
文件元信息是对文件(Object)的属性描述,包括HTTP标准属性(HTTP Header)和用户自定义元数据(User Meta)两种。其中,HTTP Header可用于自定义HTTP请求的策略,用户自定义元数据可用于标识文件的用途或属性等。可以通过set-meta命令为已上传的文件(Object)设置、修改或者删除文件元信息。
./ks3util set-meta ks3://bucketname[/prefix] <meta>
[-r, --recursive]
[-f, --force]
[-u, --update]
[--delete]
[--include <value>]
[--exclude <value>]
[-j, --jobs]
参数 | 说明 |
---|---|
bucketname | 操作的桶名。 |
prefix | 操作的对象的前缀。 |
meta | 文件元信息,格式:header:value#header:value。header不区分大小写,但value区分大小写。 |
-r, --recursive | 递归进行操作。对于支持该选项的命令,当指定该选项时,命令会对目录下所有符合条件的文件进行操作,否则只对指定的单个文件进行操作。 |
-f, --force | 强制操作,不进行询问提示。 |
-u, --update | 更新操作。 |
--delete | 删除指定的元信息。 |
--include | 包含对象匹配模式,如:*.jpg。 |
--exclude | 不包含对象匹配模式,如:*.txt。 |
-j, --jobs | 多文件操作时的并发任务数,默认值:3,取值范围:1-10000。 |
可选的header列表如下:
Expires
Content-Type
Cache-Control
Content-Encoding
Content-Disposition
以X-Kss-Meta-开头的header(不区分大小写)
设置全量值meta
如果用户未指定 --update
选项和 --delete
选项,KS3Util会设置指定Objects的meta为用户输入的[header:value#header:value…]。
当缺失某个meta信息时,相当于删除meta信息(对于不可删除的headers,即:不以X-Kss-Meta-开头的headers,其值不会改变)。
给单个文件设置meta
./ks3util set-meta ks3://samplebucket/src-prefix/sample.txt Cache-Control:no-cache#X-Kss-Meta-A:1
给指定前缀的所有文件设置meta
./ks3util set-meta ks3://samplebucket/src-prefix/ Cache-Control:no-cache#X-Kss-Meta-A:1 -r
给匹配条件的所有文件设置meta
./ks3util set-meta ks3://samplebucket/src-prefix/ Cache-Control:no-cache#X-Kss-Meta-A:1 -r --include *.jpg --exclude screenshot*
给指定列表文件设置meta
./ks3util set-meta ks3://samplebucket/ Cache-Control:no-cache#X-Kss-Meta-A --object-file object_keys_file
object_keys_file为本地.txt文件的路径,文件内填写指定Object列表,每个objectKey为一行(不包含ks3://bucket/ 部分)。
更新文件meta
如果用户设置--update
选项,KS3Util会更新指定Objects的指定header为输入的value值,value值不可以为空。未指定的header的value值不会改变。此时不支持--delete
选项。
给单个文件更新meta
./ks3util set-meta ks3://samplebucket/src-prefix/sample.txt Cache-Control:no-cache#X-Kss-Meta-A:1 -u
给指定前缀的所有文件更新meta
./ks3util set-meta ks3://samplebucket/src-prefix/ Cache-Control:no-cache#X-Kss-Meta-A:1 -r -u
给匹配条件的所有文件更新meta
./ks3util set-meta ks3://samplebucket/src-prefix/ Cache-Control:no-cache#X-Kss-Meta-A:1 -r -u --include *.jpg --exclude screenshot*
给指定列表文件更新meta
./ks3util set-meta ks3://samplebucket/ Cache-Control:no-cache#X-Kss-Meta-A --object-file object_keys_file -u
object_keys_file为本地.txt文件的路径,文件内填写指定Object列表,每个objectKey为一行(不包含ks3://bucket/ 部分)。
删除meta
如果用户设置--delete
选项,KS3Util会删除指定Objects的指定header(不用指定value值,指定了的value值都会被忽略;对于不可删除的headers,即:不以X-Kss-Meta-开头的headers,该选项不起作用)。此时不支持--update
选项。
单个文件删除meta
./ks3util set-meta ks3://samplebucket/src-prefix/sample.txt X-Kss-Meta-A --delete
给指定前缀的所有文件删除meta
./ks3util set-meta ks3://samplebucket/src-prefix/ X-Kss-Meta-A --delete
给匹配条件的所有文件删除meta
./ks3util set-meta ks3://samplebucket/src-prefix/ X-Kss-Meta-A -r --delete --include *.jpg --exclude screenshot*
给指定列表文件删除meta
./ks3util set-meta ks3://samplebucket/ X-Kss-Meta-A --object-file object_keys_file --delete
object_keys_file为本地.txt文件的路径,文件内填写指定Object列表,每个objectKey为一行(不包含ks3://bucket/ 部分)。
该命令用于将本地文件目录或者ks3 prefix从源端同步到目的端。
不支持本地目录之间的同步。
该命令和cp命令类似:支持从本地文件系统上传文件到ks3,从ks3下载Object到本地文件系统,在ks3上进行Object拷贝;用于源端和目的端数据同步。
sync命令和cp命令不同之处如下:
当输入--delete
选项时,该命令会自动删除目的端存在而源端不存在的Object或者移走本地文件。如果目的端是ks3,则会删除多余的Object;如果目的端是本地文件,则会移走本地多余的文件。
警告:在没有完全搞清楚sync命令的行为之前,请慎用
--delete
sync强制是以recursive方式遍历文件或者Object的,所以不用输入-r --recursive。
当源端是ks3://bucket/prefix,sync命令会自动在prefix后面加上字符 ‘/’,但是cp命令不会。当目的端是ks3://bucket/prefix,sync命令会在prefix后面加上字符 ‘/’;cp命令在–recursive被输入时也会在prefix后面加上字符’/’。
--delete
选项
表示需要删除或者移走目的端存在而源端不存在的Object或者文件。
--backup-dir
选项
该选项表示用于备份目的端文件的目录,不能是目的端目录的子目录,如果输入了--delete
,该选项必须输入。
其他选项说明、用法和cp命令相同。
# 将本地目录同步到ks3 prefix
ks3util sync local_dir ks3://bucketname[/prefix]
[-f]
[-u]
[--delete]
[--backup-dir]
[--disable-crc64]
参数 | 说明 |
---|---|
local_dir | 本地目录。 |
bucketname | 操作的桶名。 |
prefix | 操作的对象前缀。 |
-f, --force | 强制操作,不进行询问提示。 |
-u, --update | 更新操作,只有当目标文件不存在,或源文件的最后修改时间晚于目标文件时,KS3Util才会执行上传操作。 |
--delete | 表示需要删除或者移走目的端存在而源端不存在的Object或者文件。 |
--backup-dir | 用于备份目的端文件的目录,不能是目的端目录的子目录,如果输入了–delete,该选项必须输入。 |
--disable-crc64 | 关闭CRC64数据校验。默认情况下,KS3Util进行数据传输时都会打开CRC64校验。 |
从本地目录同步到ks3
./ks3util sync ./test_dir ks3://samplebucket/test_sync/ -u -f
# 同步并删除ks3上多余的文件
./ks3util sync ./test_dir ks3://samplebucket/test_sync/ -u -f --delete
从ks3同步到本地目录
./ks3util sync ks3://samplebucket/test_sync/ ./test_dir -u -f
# 同步并移动本地目录多余的文件到./backup目录
./ks3util sync ks3://samplebucket/test_sync/ ./test_dir -u -f --delete --backup-dir ./backup
从ks3同步到ks3
./ks3util sync ks3://samplebucket/test_sync/ ks3://samplebucket/test_sync_2/ -u -f
# 同步并删除目的端上多余的文件
./ks3util sync ks3://samplebucket/test_sync/ ks3://samplebucket/test_sync_2/ -u -f --delete
restore命令用于解冻归档存储类型的文件。有关解冻规则的更多详情请参见文档:Restore Object。
./ks3util restore ks3://bucketname[/prefix]
[-r, --recursive]
[-f, --force]
[--include <value>]
[--exclude <value>]
[-j, --jobs]
[--days <value>]
参数 | 说明 |
---|---|
bucketname | 操作的桶名。 |
prefix | 操作的对象的前缀。 |
-r, --recursive | 递归进行操作。对于支持该选项的命令,当指定该选项时,命令会对目录下所有符合条件的文件进行操作,否则只对指定的单个文件进行操作。 |
-f, --force | 强制操作,不进行询问提示。 |
--include | 包含对象匹配模式,如:*.jpg。 |
--exclude | 不包含对象匹配模式,如:*.txt。 |
-j, --jobs | 多文件操作时的并发任务数,默认值:3,取值范围:1-10000。 |
--days | 表示解冻归档存储类型对象持续时间,当不加该参数时,表示解冻时间为1天。单位:天,默认值:1,取值范围:1-7。 |
给单个文件解冻,并设置解冻天数为7天
./ks3util restore ks3://samplebucket/src-prefix/sample.txt --days 7
批量给指定前缀的文件解冻,并设置解冻天数为7天
./ks3util restore ks3://samplebucket/src-prefix/ -r --days 7
批量给符合匹配规则的文件解冻
./ks3util restore ks3://samplebucket/src-prefix/ -r --days 7 --include *screenshot* --exclude *important*
给指定列表文件解冻
./ks3util restore ks3://samplebucket/ --object-file object_keys_file
object_keys_file为本地.txt文件的路径,文件内填写指定Object列表,每个objectKey为一行(不包含ks3://bucket/ 部分)。
该命令用于设置指定Objects的存储类型信息。
./ks3util set-storage-class ks3://bucketname/object-key <storage-class>
[-r]
[-f]
[--include <patten>]
[--exclude <patten>]
参数 | 说明 |
---|---|
-r, --recursive | 递归进行操作。 |
-f, --force | 强制操作,不进行询问提示。 |
--include | 包含对象匹配模式,如:*.jpg。 |
--exclude | 不包含对象匹配模式,如:*.txt。 |
设置单个文件的存储类型
./ks3util set-storage-class ks3://samplebucket/test-file STANDARD_IA
批量设置文件的存储类型
./ks3util set-storage-class ks3://samplebucket/logs/ STANDARD_IA -r -f
设置指定列表文件的存储类型
./ks3util set-storage-class ks3://samplebucket/ STANDARD_IA --object-file object_keys_file -f
object_keys_file为本地.txt文件的路径,文件内填写指定Object列表,每个objectKey为一行(不包含ks3://bucket/ 部分)。
stat命令用于查看指定对象(Object)的相关信息,可以通过该命令查看Object元信息。
./ks3util stat ks3://bucketname/objectname
参数 | 说明 |
---|---|
bucketname | 目标Bucket名称。 |
objectname | 目标Object名称。 |
查看Object的信息
./ks3util stat ks3://samplebucket/objectname
响应内容如下:
ACL : private
Accept-Ranges : bytes
Content-Length : 10240
Content-Md5 : t4oxPaDQPOIUDtXulemwgw==
Content-Type : application/octet-stream
Content-Encoding :
Content-Disposition :
Cache-Control :
Expires :
Etag : b78a313da0d03ce2140ed5ee95e9b083
Last-Modified : Fri, 22 Nov 2024 07:03:42 GMT
X-Kss-Checksum-Crc64ecma : 7168165721704423945
Owner : 123456
X-Kss-Storage-Class : STANDARD
X-Kss-Tagging-Count :
X-Kss-Server-Side-Encryption :
0.211489(s) elapsed
该命令可设置、更新、删除指定Objects的tagging信息。
tagging的key和value区分大小写。
./ks3util set-tag ks3://bucketname[/prefix] <tagging> [-r] [f]
[--update]
[--delete]
[--include <patten>]
[--exclude <patten>]
[-j, --jobs <num>]
参数 | 说明 |
---|---|
bucketname | 操作的桶名。 |
prefix | 操作的对象的名称或前缀。 |
-r, --recursive | 递归进行操作。对于支持该选项的命令,当指定该选项时,命令会对目录下所有符合条件的文件进行操作,否则只对指定的单个文件进行操作。 |
-f, --force | 强制操作,不进行询问提示。 |
-u, --update | 更新操作。 |
--delete | 删除所有tagging。 |
--include | 包含对象匹配模式,如:*.jpg。 |
--exclude | 不包含对象匹配模式,如:*.txt。 |
-j, --jobs | 多文件操作时的并发任务数,默认值:3,取值范围:1-10000。 |
设置标签
如果用户未指定--update
选项和--delete
选项,KS3Util会设置指定Objects的tagging为用户输入的"tag=value&tag=value"。
设置单个文件的标签
./ks3util set-tag ks3://samplebucket/test-files/sample.txt "belongs=kevin&test-file=true"
设置指定前缀的所有文件的标签
./ks3util set-tag ks3://samplebucket/test-files/ "belongs=kevin&test-file=true" -r
设置匹配条件的文件的标签
./ks3util set-tag ks3://samplebucket/test-files/ "belongs=kevin&test-file=true" -r --include *.log --exclude tom-*
设置指定列表文件的标签
./ks3util set-tag ks3://samplebucket/ "belongs=kevin&test-file=true" --object-file object_keys_file
object_keys_file为本地.txt文件的路径,文件内填写指定Object列表,每个objectKey为一行(不包含ks3://bucket/ 部分)。
更新标签
如果用户设置--update
选项,KS3Util会更新指定Objects的指定tagging为输入的value值,value值不可以为空,指定Objects的其他tagging信息不会改变。此时不支持--delete
选项。
更新单个文件的标签
./ks3util set-tag ks3://samplebucket/test-files/sample.txt "belongs=kevin&test-file=true" --update
更新指定前缀的所有文件的标签
./ks3util set-tag ks3://samplebucket/test-files/ "belongs=kevin&test-file=true" -r --update
更新匹配条件的文件的标签
./ks3util set-tag ks3://samplebucket/test-files/ "belongs=kevin&test-file=true" -r --include *.log --exclude tom-* --update
更新指定列表文件的标签
./ks3util set-tag ks3://samplebucket/ "belongs=kevin&test-file=true" --object-file object_keys_file --update
object_keys_file为本地.txt文件的路径,文件内填写指定Object列表,每个objectKey为一行(不包含ks3://bucket/ 部分)。
删除标签
如果用户设置--delete
选项,KS3Util会删除所有标签。此时不支持--update
选项。
删除单个文件的标签
./ks3util set-tag ks3://samplebucket/test-files/sample.txt --delete
删除指定前缀的所有文件的标签
./ks3util set-tag ks3://samplebucket/test-files/ -r --delete
删除匹配条件的文件的标签
./ks3util set-tag ks3://samplebucket/test-files/ -r --include *.log --exclude tom-* --delete
删除指定列表文件的标签
./ks3util set-tag ks3://samplebucket/ --object-file object_keys_file --delete
object_keys_file为本地.txt文件的路径,文件内填写指定Object列表,每个objectKey为一行(不包含ks3://bucket/ 部分)。
cat命令可以将ks3的Object内容输出到标准输出流,Object内容是文本格式比较好。
ks3util cat ks3://bucketname/objectKey
参数 | 说明 |
---|---|
bucketname | 操作的桶名。 |
objectKey | 操作的对象名。 |
输出到标准输出
ks3util cat ks3://samplebucket/ks3log_samplebucket_2023_01_01.log
与管道一起使用(Linux、MacOS)
ks3util cat ks3://samplebucket/ks3log_samplebucket_2023_01_01.log | grep 'REST.DELETE.OBJECT'
rcat命令用于流式上传文件,需与管道配合使用,如果ks3上已存在同名文件,则会覆盖。
./ks3util rcat ks3://bucketname/objectKey
[-f, --force]
[--acl <acl>]
[--meta <meta>]
[--tagging <tagging>]
[-j, --jobs <job-num>]
[--part-size <part-size>]
[--disable-crc64]
参数 | 说明 |
---|---|
bucketname | 操作的桶名 |
objectKey | 操作的对象名。 |
--acl | acl信息的配置。 |
--meta | 设置Object的meta为 |
--tagging | 设置Object的tagging,取值格式如 |
--storage-class | 对象的存储类型,取值:STANDARD,STANDARD_IA,ARCHIVE。 |
-j, --jobs | 多文件操作时的并发任务数,默认值:3,取值范围:1-10000。 |
--part-size | 分片大小,单位为Byte,默认情况下KS3Util根据文件大小自行计算合适的分片大小值。如果有特殊需求或者需要性能调优,可以设置该值,取值范围:1-5368709120(Byte)。 |
--disable-crc64 | 关闭CRC64数据校验。默认情况下,KS3Util进行数据传输时都会打开CRC64校验。 |
流式上传文件
grep 'REST.DELETE.OBJECT' ks3log_samplebucket_2023_01_01.log | ks3util rcat ks3://samplebucket/delete-object.log
流式上传文件并设置ACL等
grep 'REST.DELETE.OBJECT' ks3log_samplebucket_2023_01_01.log | ks3util rcat ks3://samplebucket/delete-object.log --acl public-read --storage-class STANDARD_IA --meta Content-Type:text/plain#X-Kss-Meta-belongs:kevin --tagging "log-file=true&test-file=true" -j 10 --part-size 5242880
sign命令用于该命令签名用户指定的cloud_url,生成经过签名的url可供第三方用户访问Object。
./ks3util sign ks3://bucketname[/prefix]
[-r, --recursive]
[-f, --force]
[--include <value>]
[--exclude <value>]
[--timeout <value>]
[--sign-method <value>]
[--network-type <value>]
参数 | 说明 |
---|---|
bucketname | 操作的桶名。 |
prefix | 操作的对象的前缀。 |
-r, --recursive | 递归进行操作。对于支持该选项的命令,当指定该选项时,命令会对目录下所有符合条件的文件进行操作,否则只对指定的单个文件进行操作。 |
-f, --force | 强制操作,不进行询问提示。 |
--include | 包含对象匹配模式,如:*.jpg。 |
--exclude | 不包含对象匹配模式,如:*.txt。 |
--timeout | 外链过期时间,默认值:10(单位秒) 。 |
--sign-method | 生成下载链接或者上传链接,默认值:get,可选值为 get 、put。 |
--network-type | 生成指定网络类型的链接,默认值:无,可选值:internal 、external。internal表示生成内网链接,external表示生成外网链接。 |
生成下载链接,单个签名默认 ‘GET’
./ks3util sign ks3://samplebucket/src-prefix/sample.txt
过期时间为签名时间+timeout时间。60秒后签名过期
./ks3util sign ks3://samplebucket/src-prefix/sample.txt --timeout 60
生成上传链接
./ks3util sign ks3://samplebucket/src-prefix/ -r --sign-method=PUT
批量签名目录
./ks3util sign ks3://samplebucket/src-prefix/ -r
批量给符合匹配规则的文件签名
./ks3util sign ks3://samplebucket/src-prefix -r --include *.txt
生成内网链接
./ks3util sign ks3://samplebucket/src-prefix/sample.txt --network-type internal
生成外网链接
./ks3util sign ks3://samplebucket/src-prefix/sample.txt --network-type external
纯净模式