通用选项&过滤规则

本文为您介绍KS3Util的通用选项参数和过滤规则示例。

通用选项

表格中为ks3util的通用选项，可以在大部分命令中使用：

选项参数	说明
-c, --config-file	ks3util工具的配置文件路径，ks3util启动时从配置文件读取配置，在config命令中，ks3util将配置写入该文件。
-e, --endpoint	设置Bucket所在地域的域名信息（该选项值会覆盖配置文件中的相应设置），支持HTTP和HTTPS访问。填写内容示例：ks3-cn-beijing.ksyuncs.com或https://ks3-cn-beijing.ksyuncs.com。
-i, --access-key-id	访问KS3使用的AccessKeyID（该选项值会覆盖配置文件中的相应设置）。
-k, --access-key-secret	访问KS3使用的AccessKeySecret（该选项值会覆盖配置文件中的相应设置）。
-t, --sts-token	访问KS3使用的STSToken，若您使用临时AK/SK访问，则需要填写该项（该选项值会覆盖配置文件中的相应设置）。
--no-sign-request	匿名访问KS3公开资源，不使用AK/SK签名请求。
-L, --language	设置工具的语言，默认值：跟随系统语言设置。 可选值： EN：英文 CH：中文（设置为CH时，请确保系统编码方式为UTF-8）
-r, --recursive	递归进行操作。对于支持该选项的命令，当指定该选项时，命令会对指定目录下所有符合条件的文件进行操作，否则只对指定的单个文件进行操作。
-f, --force	强制操作，不进行询问提示。
--retry-times	当错误发生时的重试次数，默认值：10，取值范围：1-500。
--loglevel	输出日志级别，默认值：info。 可选值： off：关闭日志 error：输出错误信息日志 warn：输出警告信息日志 info：输出提示信息日志 debug：输出详细信息日志（包括HTTP请求和响应信息）
--read-timeout	表示客户端读超时的时间，单位为秒，默认值：60。
--connect-timeout	表示客户端连接超时的时间，单位为秒，默认值：60。
-j, --jobs	多文件操作时的并发数，表示有多少个文件并行传输。默认值：5，取值范围：1-10000。
--parallel	单文件内部操作的并发任务数，表示单个大文件有多少个块并行传输。取值范围：1-10000。
--object-file	需对其进行操作的文件列表，每个objectKey为一行（不包含ks3://bucket/ 部分）。
--include	包含对象匹配模式，满足匹配规则的文件将会被选中，如：*.jpg。 该选项可以出现多次，多个--include规则取并集。
--exclude	不包含对象匹配模式，满足匹配规则的文件将会被排除，如：*.txt。 该选项可以出现多次，多个--exclude规则取并集。
--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的所有文件。
--metadata-include	元数据包含匹配规则，满足规则的文件将会被选中，格式为key=value，如：--metadata-include "X-Kss-Storage-Class=STANDARD"，表示只选中标准存储类型文件。 该选项可以出现多次，多个--metadata-include规则取并集。
--metadata-exclude	元数据排除匹配规则，满足规则的文件将会被排除，格式为key=value，如：--metadata-exclude "X-Kss-Storage-Class=ARCHIVE"，表示只排除归档存储类型文件。 该选项可以出现多次，多个--metadata-exclude规则取并集。
--min-size	操作的最小文件大小，大于等于该大小的文件会被选中，格式为：值+单位。单位可选，支持的单位：B、KB、MB、GB、TB，默认单位为B（Byte）。如：--min-size 100MB，表示只选中大于等于100MB的文件。
--max-size	操作的最大文件大小，小于等于该大小的文件会被选中，格式为：值+单位。单位可选，支持的单位：B、KB、MB、GB、TB，默认单位为B（Byte）。如：--max-size 1GB，表示只选中小于等于1GB的文件。
--disable-endpoint-redirect	禁用endpoint重定向，不会自动重定向到桶所在region对应的endpoint，始终使用配置中的endpoint。
--proxy	指定代理服务器。配置值可以为以下几种： 直接配置：可以直接指定代理服务器的详细信息，例如： http://proxy.example.com:8080 https://proxy.example.com:8443 env：表示使用环境变量 HTTP_PROXY 和 HTTPS_PROXY 来获取代理服务器信息。用户需要在操作系统中配置这两个环境变量，例如： HTTP_PROXY=http://proxy.example.com:8080 HTTPS_PROXY=https://proxy.example.com:8443 配置这些环境变量后，将代理服务器选项的值设置为 env，系统将自动使用这些环境变量中的代理设置。
--output-dir	批量操作时清单文件输出的目录，默认值：ks3util_output（工具当前执行目录的ks3util_output目录下）。
--output-item	批量操作时清单文件输出项，默认值：failed（表示只输出失败文件清单）。可填写多个值，以英文逗号分隔，例如：succeeded,failed,skipped。 可选值： all：输出所有文件清单 succeeded：输出成功文件清单 failed：输出失败文件清单 skipped：输出跳过文件清单
--pb-output-mode	进度条输出方式，默认值：refresh。 可选值： refresh：刷新输出 newline：换行输出
--pb-output-interval	进度条输出间隔时间，默认值：1，单位：秒，取值范围：1-60。

过滤规则

您可以使用 --include 或 --exclude 参数，根据文件名称（默认）或路径（从 2.7.0 起支持）过滤文件。具体匹配逻辑请参照下方文档。为避免特殊字符的影响，建议将过滤规则使用双引号 "" 包含。

该功能需要 KS3Util 2.7.0 及以上版本支持，建议您升级后使用。

匹配模式

默认模式

命令中不添加额外参数时，遵循默认模式匹配，--include和--exclude的值需要符合默认模式的规则。具体规则如下：

• *：匹配所有字符。例如："*.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的文件。

例如选中所有 txt 格式的文件可以写为：--include "*.txt"。

正则模式

当添加--enable-regex参数后，将使用正则模式匹配，此时--include和--exclude中需要填写标准的正则表达式。

例如选中所有 txt 格式的文件可以写为：--include ".*\.txt$"。

匹配流程

1. 若exclude存在，且只要有一个exclude匹配成功，文件被排除。

2. 若exclude不存在，或所有exclude匹配失败，则由include决定匹配结果。

3. 若include存在，且只要有一个include匹配成功，文件被选中。若所有include匹配失败，文件被排除。

4. 若exclude和include都不存在，表示不过滤，文件被选中。

具体示例图如下：

匹配示例

根据文件名匹配

1. 上传 local_dir 中所有 txt 格式的文件。

   ./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r -u --include "*.txt"

2. 上传 local_dir 中所有文件名包含 data 字符串的文件。

   ./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r -u --include "*data*"

3. 下载 samplebucket 桶的 src-prefix/ 下所有不是 jpg 且不是 png 格式的文件。

   ./ks3util cp ks3://samplebucket/src-prefix/ local-dir/ -r -u --exclude "*.jpg" --exclude "*.png"

根据目录名匹配

根据目录名匹配时，必须使用正则匹配模式（--enable-regex）和路径匹配模式（--path-matching）。

1. 上传 local_dir 中除 subdir 目录外的全部文件。

   ./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r -u --enable-regex --path-matching --exclude ".*/subdir/.*"

   

   在该示例中，如果有多个目录都叫 subdir，这些目录都会被排除。如果希望更加精确地匹配某一个目录，需要使用绝对路径写法，具体可参考示例二。

2. 上传 /mnt/local_dir 中除 /mnt/local_dir/subdir 子目录外的全部文件。

   ./ks3util cp /mnt/local_dir ks3://samplebucket/dest_prefix/ -r -u --enable-regex --path-matching --exclude "/mnt/local_dir/subdir/.*"

   

   该示例只会排除路径为 /mnt/local_dir/subdir 的目录。

3. 下载 samplebucket 桶的 src-prefix/ 下目录名以 data- 开头的全部文件。

   ./ks3util cp ks3://samplebucket/src-prefix/ local-dir/ -r -u  --enable-regex --path-matching --include ".*/data-.*/.*"

根据时间段匹配

从 2.9.0 版本开始，KS3Util 支持根据文件的最后修改时间进行过滤，具体用法请参见通用选项 --time-range。

1. 匹配最后修改时间在2024-11-06 12:00:00 到 2024-11-10 12:00:00 之间的文件（UTC时间）。

   ./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r --time-range "20241106120000-20241110120000"

   

   文件的最后修改时间采用 UTC 时区，--time-range 参数同样基于 UTC 进行筛选。

2. 匹配最后修改时间在2024-11-06 12:00:00 到 2024-11-10 12:00:00 之间的文件（北京时间）。

   ./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r --time-range "20241106040000-20241110040000"

   

   若您希望按北京时间筛选，需先将时间转换为 UTC 时间。

3. 匹配最后修改时间在2024-11-06 12:00:00 之前的文件（UTC时间）。

   ./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r --time-range "*-20241106120000"

4. 匹配最后修改时间在 2024-11-10 12:00:00 之后的文件（UTC时间）。

   ./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r --time-range "20241110120000-*"

根据存储类型匹配

1. 下载 samplebucket 桶的 src-prefix/ 下所有标准存储类型的文件。

   ./ks3util cp ks3://samplebucket/src-prefix/ local-dir/ -r -u --metadata-include "X-Kss-Storage-Class=STANDARD"

2. 下载 samplebucket 桶的 src-prefix/ 下所有非归档存储类型的文件。

   ./ks3util cp ks3://samplebucket/src-prefix/ local-dir/ -r -u --metadata-exclude "X-Kss-Storage-Class=ARCHIVE"

3. 解冻 samplebucket 桶的 src-prefix/ 下所有归档类型的文件。

   ./ks3util restore ks3://samplebucket/src-prefix/ -r --metadata-include "X-Kss-Storage-Class=ARCHIVE"

根据文件大小匹配

1. 上传 local_dir 中所有大于等于100MB的文件。

   ./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r -u --min-size 100MB

2. 上传 local_dir 中所有小于等于1GB的文件。

   ./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r -u --max-size 1GB

3. 下载 samplebucket 桶的 src-prefix/ 下所有大于等于100MB且小于等于1GB的文件。

   ./ks3util cp ks3://samplebucket/src-prefix/ local-dir/ -r -u --min-size 100MB --max-size 1GB