全部文档
当前文档

暂无内容

如果没有找到您期望的内容,请尝试其他搜索词

文档中心

通用选项&过滤规则

最近更新时间:2025-02-25 15:35:11

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

通用选项

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

选项参数

说明

-c, --config-file

ks3util工具的配置文件路径,ks3util启动时从配置文件读取配置,在config命令中,ks3util将配置写入该文件。

-e, --endpoint

设置Bucket所在地域的域名信息(该选项值会覆盖配置文件中的相应设置),支持HTTP和HTTPS访问。填写内容示例:ks3-cn-beijing.ksyuncs.comhttps://ks3-cn-beijing.ksyuncs.com

-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。

  • off:关闭日志

  • error:输出错误信息日志

  • warn:输出警告信息日志

  • info:输出提示信息日志

  • debug:输出详细信息日志(包括HTTP请求和响应信息)

--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

指定代理服务器。配置值可以为以下几种:

  • 直接配置:可以直接指定代理服务器的详细信息,例如:

    • http://proxy.example.com:8080

    • https://proxy.example.com:8443

  • env:表示使用环境变量 HTTP_PROXYHTTPS_PROXY 来获取代理服务器信息。用户需要在操作系统中配置这两个环境变量,例如:

    • HTTP_PROXY=http://proxy.example.com:8080

    • HTTPS_PROXY=https://proxy.example.com:8443

配置这些环境变量后,将代理服务器选项的值设置为 env,系统将自动使用这些环境变量中的代理设置。

过滤规则

用户可以使用--include--exclude参数,根据文件的名称过滤文件。从2.7.0版本开始,支持根据文件路径过滤文件。为避免特殊字符的影响,建议将过滤规则使用双引号""包含。

从2.7.0版本开始,KS3Util修改了过滤规则的匹配流程,多个规则填写的顺序不会影响匹配结果,具体细节请参照以下文档。

2.7.0以下版本(不推荐)

匹配模式
  • *:匹配所有字符。例如:"*.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及其以上版本(推荐)

匹配模式

2.7.0及以上版本支持两种匹配模式:默认模式正则模式。命令中不添加额外参数时,遵循默认模式匹配,--include--exclude填写的值需要符合默认模式的规则;当添加--enable-regex参数后,将使用正则模式匹配,此时--include--exclude中需要填写标准的正则表达式。

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

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

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

  4. 若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-*"

纯净模式常规模式

纯净模式

点击可全屏预览文档内容