最近更新时间:2025-02-25 15:35:11
本文为您介绍KS3Util的通用选项参数和过滤规则示例。
表格中为ks3util的通用选项,可以在大部分命令中使用:
选项参数 | 说明 |
---|---|
-c, --config-file | ks3util工具的配置文件路径,ks3util启动时从配置文件读取配置,在config命令中,ks3util将配置写入该文件。 |
-e, --endpoint | 设置Bucket所在地域的域名信息(该选项值会覆盖配置文件中的相应设置),支持HTTP和HTTPS访问。填写内容示例: |
-i, --access-key-id | 访问ks3使用的AccessKeyID(该选项值会覆盖配置文件中的相应设置)。 |
-k, --access-key-secret | 访问ks3使用的AccessKeySecret(该选项值会覆盖配置文件中的相应设置)。 |
-r, --recursive | 递归进行操作。对于支持该选项的命令,当指定该选项时,命令会对指定目录下所有符合条件的文件进行操作,否则只对指定的单个文件进行操作。 |
-f, --force | 强制操作,不进行询问提示。 |
--retry-times | 当错误发生时的重试次数,默认值:10,取值范围:1-500。 |
--loglevel | 日志级别,默认为off(该选项值会覆盖配置文件中的相应设置)。可选值:off | error | warn | info | debug。
|
--read-timeout | 表示客户端读超时的时间,单位为秒,缺省值为60。 |
--connect-timeout | 表示客户端连接超时的时间,单位为秒,缺省值为60。 |
--include | 包含对象匹配模式,满足匹配规则的文件将会被选中,如:*.jpg。 该选项可以出现多次,多个--include规则取并集。 |
--exclude | 不包含对象匹配模式,满足匹配规则的文件将会被排除,如:*.txt。 该选项可以出现多次,多个--exclude规则取并集。 |
-j, --jobs | 多文件操作时的并发数,默认值:5,取值范围:1-10000。 1. 该参数决定有多少个文件并行上传/下载/拷贝。 2. 批量操作文件时适合调整该参数。 3. Util2.9.0版本默认值由3改为5。 |
--parallel | 单文件内部操作的并发任务数,取值范围:1-10000。 1. 默认KS3 Util会根据操作类型和文件大小自动决定,自动取值范围是1-12。 2. 该参数决定单个文件有多少个块并行上传/下载/拷贝。 3. 操作单个大文件时适合调整该参数。 4. 总并发数= jobs * parallel。 |
-L, --language | 设置ks3util工具的语言。取值如下:EN:英文;CH(默认值):中文。设置为CH时,请确保系统编码方式为UTF-8。 |
--object-file | 需对其进行操作的文件列表,每个objectKey为一行(不包含ks3://bucket/ 部分)。 |
--enable-regex | 匹配模式,指定该选项时,--include与--exclude将使用正则表达式匹配,若不指定该选项,则使用默认模式匹配。 |
--path-matching | 路径匹配,指定该选项时,--include与--exclude将对文件路径(ObjectKey)使用过滤规则,若不指定该选项,则对文件名(FileName)使用过滤规则。 |
--time-range | 时间段匹配模式,仅匹配最后修改时间在该时间段内的文件。时间段格式为:time1-time2,其中time1、time2需要填写UTC时间,格式为:yyyyMMddHHmmss。 1、time1-time2表示匹配最后修改时间大于等于time1且小于等于time2的所有文件。 2、*-time2表示匹配最后修改时间小于等于time2的所有文件。 3、time1-*表示匹配最后修改时间大于等于time1的所有文件。 |
--disable-endpoint-redirect | 禁用endpoint重定向,不会自动重定向到桶所在region对应的endpoint,始终使用配置中的endpoint。 |
--proxy | 指定代理服务器。配置值可以为以下几种:
配置这些环境变量后,将代理服务器选项的值设置为 |
用户可以使用--include
或--exclude
参数,根据文件的名称过滤文件。从2.7.0版本开始,支持根据文件路径过滤文件。为避免特殊字符的影响,建议将过滤规则使用双引号""
包含。
从2.7.0版本开始,KS3Util修改了过滤规则的匹配流程,多个规则填写的顺序不会影响匹配结果,具体细节请参照以下文档。
*:匹配所有字符。例如:"*.txt"
表示匹配所有TXT格式的文件。
?:匹配单个字符。例如:"file?.txt"
表示匹配file+任意一个字符的txt文件,如:file2.txt。
[sequence]:匹配sequence的任意字符,例如:"abc[1-5].jpg"
表示匹配文件名为abc1.jpg~abc5.jpg的文件。
[!sequence]:匹配不在sequence的任意字符,例如:"abc[!1-5].jpg"
表示匹配文件名不为abc1.jpg~abc5.jpg的文件。
从2.7.0版本开始,该匹配模式将作为默认模式。
--include
和--exclude
可以出现多次。每个文件从左到右逐一运用每个规则,直至最后才能最终确定匹配的结果。
例如指定生效的文件夹中包含名为file5.txt
的文件,匹配不同的规则产生的结果如下:
规则一:--include "*file*" --exclude "*.txt"
,当规则匹配到--include "*file*"
,匹配的结果为file5.txt符合条件;当规则继续匹配到--exclude "*.txt"
时,因file5.txt文件名包含.txt,所以被排除;则匹配的最终结果为file5.txt不符合条件。
规则二:--exclude "*.txt" --include "*file*"
,当规则匹配到--exclude "*.txt"
,匹配的结果为file5.txt不符合条件;当规则继续匹配到--include "*file*"
,因file5.txt文件名包含file,所以符合条件;则匹配的最终结果为file5.txt符合条件。
规则三:--include "*file*" --exclude "*.txt" --include "file?.txt"
,当规则匹配到--include "*file*"
,匹配的结果为file5.txt符合条件;当规则继续匹配到--exclude "*.txt"
时,因file5.txt文件名包含.txt,所以被排除;当规则最后匹配到--include "file?.txt"
时,因file5.txt符合条件,所以被包含;则匹配的最终结果为file5.txt符合条件。
规则不支持带目录的格式,例如:--include "/usr/*/test/*.jpg"。
2.7.0及以上版本支持两种匹配模式:默认模式和正则模式。命令中不添加额外参数时,遵循默认模式匹配,--include
和--exclude
填写的值需要符合默认模式的规则;当添加--enable-regex
参数后,将使用正则模式匹配,此时--include
和--exclude
中需要填写标准的正则表达式。
若exclude存在,且只要有一个exclude匹配成功,文件被排除。
若exclude不存在,或所有exclude匹配失败,则由include决定匹配结果。
若include存在,且只要有一个include匹配成功,文件被选中。若所有include匹配失败,文件被排除。
若exclude和include都不存在,表示不过滤,文件被选中。
具体示例图如下:
1.根据文件名匹配
以下示例均采用默认匹配模式,例如指定生效的文件夹中包含名为file5.txt
的文件,具体规则生效示例如下。
1.1单规则匹配示例
规则一:--exclude "*test*"
该规则的含义:排除所有文件名包含test的文件
先匹配--exclude规则,当规则匹配到--exclude "*test*"
时,因为file5.txt不包含test,所以未被排除,则匹配的最终结果为file5.txt符合条件。
规则二:--exclude "*file*"
该规则的含义:排除所有文件名包含file的文件
先匹配--exclude规则,当规则匹配到--exclude "*file*"
时,因为file5.txt包含file,所以被排除,则匹配的最终结果为file5.txt不符合条件。
规则三:--include "*test*"
该规则的含义:选中所有文件名包含test的文件
先匹配--exclude规则,发现无--exclude规则,再匹配--include规则,当规则匹配到--include "*test*"
时,因为file5.txt不包含test,所以未被选中,则匹配的最终结果为file5.txt不符合条件。
规则四:--include "*file*"
该规则的含义:选中所有文件名包含file的文件
先匹配--exclude规则,发现无--exclude规则,再匹配--include规则,当规则匹配到--include "*file*"
时,因为file5.txt包含file,所以被选中,则匹配的最终结果为file5.txt符合条件。
1.2多规则匹配示例
规则一:--include "*.txt" --exclude "*test*"
该规则的含义:排除所有文件名包含test的文件后,选中文件结尾是.txt的文件
先匹配--exclude规则,当规则匹配到--exclude "*test*"
时,因为file5.txt不包含test,所以未被排除;再匹配--include规则,当规则匹配到--include "*.txt"
时,因为file5.txt包含.txt,所以被选中,则匹配的最终结果为file5.txt符合条件。
规则二:--include "*.txt" --exclude "*file*"
该规则的含义:排除所有文件名包含file的文件后,选中文件结尾是.txt的文件
先匹配--exclude规则,当规则匹配到--exclude "*file*"
时,因为file5.txt包含file,所以被排除,则匹配的最终结果为file5.txt不符合条件。
规则三:--include "*.txt" --exclude "*test*" --include "*abc*" --exclude "*.png"
该规则的含义:排除所有文件名包含test或后缀是.png的文件后,选中文件结尾是.txt或包含abc的文件
先匹配--exclude规则,当规则匹配到--exclude "*test*"
时,因为file5.txt不包含test,所以未被排除,当规则匹配到--exclude "*.png"
时,因为file5.txt不包含.png,所以未被排除;再匹配--include规则,当规则匹配到--include "*.txt"
时,因为file5.txt包含.txt,所以被选中,则匹配的最终结果为file5.txt符合条件。
规则四:--include "*.txt" --exclude "*file*" --include "*abc*" --exclude "*.png"
该规则的含义:排除所有文件名包含file或后缀是.png的文件后,选中文件结尾是.txt或包含abc的文件
先匹配--exclude规则,当规则匹配到--exclude "*file*"
时,因为file5.txt包含file,所以被排除,则匹配的最终结果为file5.txt不符合条件。
2.根据文件路径匹配
默认情况下,KS3Util的过滤规则匹配文件名,命令中填写--path-matching
参数后,KS3Util的过滤规则将匹配文件路径。
在使用路径匹配时,推荐使用正则模式--enable-regex。
2.1 匹配单个文件示例
上传时,如本地文件的绝对路径为:/root/files/upload/abc.txt
规则一:--include ".*\.txt" --path-matching --enable-regex
该规则的含义:选中文件路径结尾是.txt的文件
因为/root/files/upload/abc.txt包含.txt,所以被选中,则匹配的最终结果为abc.txt符合条件。
规则二:--include ".*upload.*" --path-matching --enable-regex
该规则的含义:选中文件路径包含upload的文件
因为/root/files/upload/abc.txt包含upload,所以被选中,则匹配的最终结果为abc.txt符合条件。
下载时,如有KS3中文件的Key为:files/download/abc.txt
规则一:--include ".*\.txt" --path-matching --enable-regex
该规则的含义:选中文件路径结尾是.txt的文件
因为files/download/abc.txt包含.txt,所以被选中,则匹配的最终结果为abc.txt符合条件。
规则二:--include ".*download.*" --path-matching --enable-regex
该规则的含义:选中文件路径包含download的文件
因为files/download/abc.txt包含download,所以被选中,则匹配的最终结果为abc.txt符合条件。
2.2 匹配文件夹示例
上传示例:
假如在/root/test/目录下有1000个子目录,命名为part+序号,如:part0001、part1000,现需上传part0001-part0099的目录,可通过以下命令实现:
./ks3util cp /root/test/ ks3://bucket/prefix/ -r --include ".*/part00\d{2}/.*" --path-matching --enable-regex
在过滤规则中:.*
表示匹配任意个任意字符,/
表示匹配一个路径分隔符,part00
表示匹配part00字符串,\d{2}
表示匹配两个数字,/
表示匹配一个路径分隔符,.*
表示匹配任意个任意字符。
--path-matching
表示使用路径匹配模式,此时--include
或--exclude
匹配的是文件完整路径。
--enable-regex
表示使用正则表达式匹配,此时--include
或--exclude
需填写正则表达式。
下载示例:
假如在bucket桶的prefix/test/目录下有若干个子目录,如:unfinished-xxx、completed-xxx,现需下载所有以unfinished-开头的子目录,可通过以下命令实现:
./ks3util cp ks3://bucket/prefix/test/ files/ -r --include ".*/unfinished-.*/.*" --path-matching --enable-regex
在过滤规则中:.*
表示匹配任意个任意字符,/
表示匹配一个路径分隔符,unfinished-
表示匹配unfinished-字符串,.*
表示匹配任意个任意字符,/
表示匹配一个路径分隔符,.*
表示匹配任意个任意字符。
--path-matching
表示使用路径匹配模式,此时--include
或--exclude
匹配的是对象完整的key。
--enable-regex
表示使用正则表达式匹配,此时--include
或--exclude
需填写正则表达式。
3.时间段匹配示例
从2.9.0版本开始,KS3Util新增根据文件的最后修改时间匹配,具体生效规则请查看通用选项--time-range。
示例一:匹配最后修改时间在2024-11-06 12:00:00 到 2024-11-10 12:00:00 之间的文件(UTC时间)。
./ks3util cp local_dir ks3://samplebcket/dest_prefix/ -r --time-range "20241106120000-20241110120000"
示例二:匹配最后修改时间在2024-11-06 12:00:00 到 2024-11-10 12:00:00 之间的文件(北京时间)。
./ks3util cp local_dir ks3://samplebcket/dest_prefix/ -r --time-range "20241106040000-20241110040000"
示例三:匹配最后修改时间在2024-11-06 12:00:00 之前的文件(UTC时间)。
./ks3util cp local_dir ks3://samplebcket/dest_prefix/ -r --time-range "*-20241106120000"
示例四:匹配最后修改时间在2024-11-06 12:00:00 之前的文件(北京时间)。
./ks3util cp local_dir ks3://samplebcket/dest_prefix/ -r --time-range "*-20241106040000"
示例五:匹配最后修改时间在 2024-11-10 12:00:00 之后的文件(UTC时间)。
./ks3util cp local_dir ks3://samplebcket/dest_prefix/ -r --time-range "20241110120000-*"
示例六:匹配最后修改时间在 2024-11-10 12:00:00 之后的文件(北京时间)。
./ks3util cp local_dir ks3://samplebcket/dest_prefix/ -r --time-range "20241110040000-*"
纯净模式