金山云-文档中心-KS3 Util命令行工具

根据操作系统及架构下载对应版本，假设下载的文件为D:\Downloads\ks3util.exe。
打开cmd，执行以下命令切换到目标文件夹。
```
cd D:\Donwloads\
```
运行以下命令，验证是否已成功安装ks3util。
```
.\ks3util.exe
```
如果终端输出ks3util所有支持的命令，表明已经成功安装ks3util。
运行以下命令，生成ks3util配置文件。
```
.\ks3util.exe config
```
根据提示输入相应信息即可，当执行ks3util其他命令时就可以使用-c选项指定该配置文件。

在Linux、macOS上安装

根据操作系统及架构下载对应版本，假设下载的文件为~/Downloads/ks3util。
运行以下命令修改文件执行权限。
```
cd ~/Downloads/
chmod 755 ks3util
```
运行以下命令，验证是否已成功安装ks3util。
```
./ks3util
```
如果终端输出ks3util所有支持的命令，表明已经成功安装ks3util。
运行以下命令，生成ks3util配置文件。
```
./ks3util config
```
根据提示输入相应信息即可，当使用ks3util其他命令时就可以使用-c选项指定该配置文件。

常用选项

通用选项

以下为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（该选项值会覆盖配置文件中的相应设置）。
-r, --recursive	递归进行操作。对于支持该选项的命令，当指定该选项时，命令会对指定目录下所有符合条件的文件进行操作，否则只对指定的单个文件进行操作。
-f, --force	强制操作，不进行询问提示。
--retry-times	当错误发生时的重试次数，默认值：10，取值范围：1-500。
--loglevel	日志级别，默认为空，表示不输出日志文件。可选值有：error \| info \| debug。 error：输出错误信息日志 info：输出提示信息日志 debug：输出详细信息日志（包括HTTP请求和响应信息）
--read-timeout	表示客户端读超时的时间，单位为秒，缺省值为1200。
--connect-timeout	表示客户端连接超时的时间，单位为秒，缺省值为120。
--include	包含对象匹配模式，如：*.jpg。
--exclude	不包含对象匹配模式，如：*.txt。
-j, --jobs	多文件操作时的并发任务数，默认值：3，取值范围：1-10000。
--parallel	单文件内部操作的并发任务数，取值范围：1-10000，默认将由ks3util根据操作类型和文件大小自行决定。
-L, --language	设置ks3util工具的语言。取值如下：EN：英文；CH（默认值）：中文。设置为CH时，请确保系统编码方式为UTF-8。
--object-file	需对其进行操作的文件列表，每个objectKey为一行（不包含ks3://bucket/ 部分）。

--include和--exclude

--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的文件。

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

常用命令

本文档的例子如无特别说明，均假设在Linux系统，下载的KS3Util工具的文件名为ks3util。

help（帮助信息）

help命令用来获取命令的帮助信息，当不清楚某个命令的用法时，建议使用help命令获取该命令的帮助信息。

命令格式

./ks3util help [command]

使用示例

获取ks3util支持的所有命令
```
./ks3util help
```
查看所有选项信息
```
./ks3util help -h
```
查看某个命令的帮助信息，如：cp命令
```
./ks3util help cp
```

config（创建配置文件）

config命令用于创建配置文件，存储KS3访问信息，在使用其他命令时添加-c选项，ks3util将通过指定的配置来访问KS3。

命令格式

该命令有交互式和非交互式两种用法。交互式用法为用户根据提示输入相应信息，命令结束时生成配置文件。非交互式则需要通过选项来指定需要的配置项。相比非交互式用法，交互式用法具有更高的安全性。

如果使用命令时输入了除-L，--languange和-c，--config-file以外的任意选项，则进入非交互式模式，所有的配置项需通过选项来指定。

./ks3util config 
[-e, --endpoint <value>] 
[-i, --access-key-id <value>] 
[-k, --access-key-secret <value>] 
[-L, --language <value>] 
[--output-dir <value>] 
[-c, --config-file <value>]

各选项说明如下：

选项	说明
-e, --endpoint	ks3util工具的基本endpoint配置（该选项值会覆盖配置文件中的相应设置），注意其必须为一个二级域名，如：ks3-cn-beijing.ksyuncs.com。
-i, --access-key-id	访问ks3使用的AccessKeyID（该选项值会覆盖配置文件中的相应设置）。
-k, --access-key-secret	访问ks3使用的AccessKeySecret（该选项值会覆盖配置文件中的相应设置）。
-L, --language	指定语言。CH（默认值）：中文。EN：英文。设置为CH时，请确保系统编码方式为UTF-8。
--output-dir	指定输出文件所在的目录，输出文件目前包含：cp命令批量拷贝文件出错时所产生的report文件。默认值为：当前目录下的ks3util_output目录。
-c, --config-file	ks3util工具的配置文件路径，ks3util启动时从配置文件读取配置，在config命令中，ks3util将配置写入该文件。

使用示例

交互式用法

./ks3util config
该命令将创建一个配置文件，在其中存储配置信息。

请输入配置文件名，文件名可以带路径(默认为：/home/user/.ks3utilconfig，回车将使用默认配置文件。如果用户设置为其它文件，在使用命令时需要将--config-file选项设置为该文件）：my_ks3util.conf
对于下述配置，回车将跳过相关配置项的设置，配置项的具体含义，请使用"help config"命令查看。
请输入语言(CH/EN，默认为：CH，该配置项将在此次config命令成功结束后生效)：CH
请输入endpoint：ks3-cn-beijing.ksyuncs.com
请输入accessKeyID：my-access-key-id
请输入accessKeySecret：my-access-key-secret

非交互式用法

./ks3util config -e ks3-cn-beijing.ksyuncs.com -i my-access-key-id -k my-access-key-secret -L CH -c my_ks3util.conf

编辑配置文件
对于已经生成的配置文件，也可以通过直接修改配置文件来修改KS3访问信息。ks3util工具的配置文件格式如下：

[Credentials]
    language = CH
    endpoint = ks3-cn-beijing.ksyuncs.com
    accessKeyID = your_key_id
    accessKeySecret = your_key_secret
    outputDir = your_output_dir

ls（列举资源）

可以使用ls命令列举当前账号下的存储空间（Bucket）、对象（Object）和碎片（Part）信息。

列举Bucket

命令格式

./ks3util ls [-s, --short-format] [--limited-num <value>]

各选项说明如下：

选项	说明
-s, --short-format	显示精简格式，如果未指定该选项，默认显示长格式。
--limited-num	返回结果的最大个数。

使用示例

列举所有Bucket

./ks3util ls

以下输出结果表明已成功列举当前账号下所有Bucket，包括Bucket名称、创建时间、所在地域、存储类型、数量等信息。

CreationTime                                              Region               StorageClass           BucketName
2021-12-02 17:03:21.811 +0800 CST        Region1             NORMAL               Bucket1
2022-08-15 16:02:43.007 +0800 CST        Region2             NORMAL               Bucket2
Bucket Number is: 2

0.112480(s) elapsed

以精简模式列举所有Bucket
```
./ks3util ls -s
```
以下输出结果表明已成功列举出所有Bucket，仅包含Bucket名称及Bucket数量。
```
ks3://sampleBucket1
ks3://sampleBucket2
ks3://sampleBucket3
Bucket Number is: 3

0.083726(s) elapsed
```

列举Object

命令格式

./ks3util ls ks3://bucketname[/prefix] 
[-s, --short-format] 
[-d, --directory] 
[--limited-num <value>] 
[--marker <value>] 
[--include <value>] 
[--exclude <value>]

参数及选项说明如下：

配置项	说明
bucketname	目标桶名称。
prefix	目标Object前缀，当列举目标Bucket中指定前缀的Object时添加此项。
-s, --short-format	显示精简格式，如果未指定该选项，默认显示长格式。
-d, --directory	返回当前目录下的文件和子目录，而非递归显示所有子目录下的所有Object。
--limited-num	返回结果的最大个数。
--marker	列举名称字母排序在marker之后的Object。
--include	包含对象匹配模式，如：*.jpg。
--exclude	不包含对象匹配模式，如：*.txt。

使用示例

列举sampleBucket中的所有文件
```
./ks3util ls ks3://sampleBucket
```
列举sampleBucket中前缀为abc的所有文件
```
./ks3util ls ks3://sampleBucket/abc
```
列举sampleBucket中所有后缀名为.jpg的文件
```
./ks3util ls ks3://sampleBucket --include *.jpg
```

仅列举sampleBucket根目录下所有Object和子目录

./ks3util ls ks3://sampleBucket -d

以下输出结果表明已成功列举出所有Object，包括每个Object的最后修改时间、大小、存储类型、ETag、名称，以及列举出的所有Object的总数量和总大小。

LastModifiedTime                                           Size(B)          StorageClass         ETAG       ObjectName
2023-07-03 10:14:19.678 +0800 CST             210643          STANDARD         ***            ks3://sampleBucket/prefix/
2023-07-03 10:14:53.066 +0800 CST             210644          STANDARD         ***            ks3://sampleBucket/prefix/sampleObject1
2023-07-03 10:14:53.512 +0800 CST             210644          STANDARD         ***            ks3://sampleBucket/prefix/sampleObject2
Object Number is: 3
Object Size is: 421288

0.139489(s) elapsed

注：创建的每个目录也会算为1个Object的数量。

列举未完成分块上传的Object信息

命令格式

./ks3util ls ks3://bucketname[/prefix] -m 
[-s, --short-format] 
[-d, --directory] 
[--limited-num <value>] 
[--marker <value>] 
[--include <value>] 
[--exclude <value>]

参数及选项说明如下：

配置项	说明
bucketname	目标桶名称。
prefix	列举指定前缀下的未完成分块上传的Object信息。
-m, --multipart	列举未完成分块上传的Object信息。
-s, --short-format	显示精简格式，如果未指定该选项，默认显示长格式。
-d, --directory	返回当前目录下的文件和子目录，而非递归显示所有子目录下的所有Part。
--limited-num	返回结果的最大个数。
--marker	列举名称字母排序在marker之后的Part。
--include	包含对象匹配模式，如：*.jpg。
--exclude	不包含对象匹配模式，如：*.txt。

使用示例

列举sampleBucket中所有未完成分块上传的Object信息
```
./ks3util ls ks3://sampleBucket -m
```
列举sampleBucket中前缀为abc的所有未完成分块上传的Object信息
```
./ks3util ls ks3://sampleBucket/abc -m
```
列举sampleBucket中后缀为.jpg的所有未完成分块上传的Object信息
```
./ks3util ls ks3://sampleBucket -m --include *.jpg
```

listpart（列举碎片）

listpart命令用于列举未完成分块上传的Object包含的碎片（Part）信息。

命令格式

./ks3util listpart ks3://bucketname/objectname uploadId

参数说明如下：

参数	说明
bucketname	目标Bucket名称。
objectname	未完成分块上传操作的Object名称。
uploadId	初始化Multipart Upload事件时返回的KS3服务器创建的全局唯一的Upload ID，用于标识本次Multipart Upload事件。您可以通过Upload ID进行Multipart Upload的中止或查询等操作。

使用示例

以下示例用于列举目标存储空间examplebucket下未完成分块上传的文件exampleobject.txt包含的碎片信息
```
./ks3util listpart ks3://examplebucket/exampleobject 655d52aa954e4ea1b7556fad6247****
```

以下返回结果表明已成功获取exampleobject文件的碎片数量、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

cp（上传、下载、复制文件）

cp命令用于上传、下载、复制文件。

上传文件

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

参数及选项说明如下：

配置项	说明
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，取值格式如`["TagA=A&TagB=B..."]`，注意：需要使用双引号。
--include	包含对象匹配模式，如：*.jpg。
--exclude	不包含对象匹配模式，如：*.txt。
-j, --jobs	多文件操作时的并发任务数，默认值：3，取值范围：1-10000。
--parallel	单文件内部操作的并发任务数，取值范围：1-10000，默认将由ks3util根据操作类型和文件大小自行决定。
--checkpoint-dir	checkpoint目录的路径(默认值为:.ks3util_checkpoint)，断点续传时，操作失败ks3util会自动创建该目录，并在该目录下记录checkpoint信息，操作成功会删除该目录。如果指定了该选项，请确保所指定的目录可以被删除。

使用示例

上传单个文件
上传文件时，如果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
```
注：如果需要保留文件夹名，则指定路径需以文件夹名结尾。

仅上传当前目录下的文件，忽略子目录下的文件

./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"

上传符合条件的文件
批量上传时，如果指定--include和--exclude选项，ks3util会上传符合指定条件的文件。--include和--exclude的说明请参见通用选项。
```
./ks3util cp local_dir ks3://samplebucket/dest_prefix/ -r --include *.mp4
```

下载文件

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

参数及选项说明如下：

配置项	说明
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	表示仅操作当前目录下的文件，忽略子目录。
--include	包含对象匹配模式，如：*.jpg。
--exclude	不包含对象匹配模式，如：*.txt。
-j, --jobs	多文件操作时的并发任务数，默认值：3，取值范围：1-10000。
--parallel	单文件内部操作的并发任务数，取值范围：1-10000，默认将由ks3util根据操作类型和文件大小自行决定。
--checkpoint-dir	checkpoint目录的路径(默认值为:.ks3util_checkpoint)，断点续传时，操作失败ks3util会自动创建该目录，并在该目录下记录checkpoint信息，操作成功会删除该目录。如果指定了该选项，请确保所指定的目录可以被删除。

使用示例

下载单个文件
没有指定文件名，则使用原文件名保存到本地。
```
./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选项选择符合条件的文件下载。–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，取值格式如`["TagA=A&TagB=B..."]`，注意：需要使用双引号。
--include	包含对象匹配模式，如：*.jpg。
--exclude	不包含对象匹配模式，如：*.txt。
-j, --jobs	多文件操作时的并发任务数，默认值：3，取值范围：1-10000。
--parallel	单文件内部操作的并发任务数，取值范围：1-10000，默认将由ks3util根据操作类型和文件大小自行决定。
--checkpoint-dir	checkpoint目录的路径(默认值为:.ks3util_checkpoint)，断点续传时，操作失败ks3util会自动创建该目录，并在该目录下记录checkpoint信息，操作成功会删除该目录。如果指定了该选项，请确保所指定的目录可以被删除。

使用示例

复制单个文件

如果没有指定目标文件名，则使用原文件名保存。

./ks3util cp ks3://samplebucket/src-prefix/sample.txt ks3://samplebucket/dst-prefix/

如果指定了目标文件名，则使用指定的文件名保存。

./ks3util 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 ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r -u
```
仅复制当前目录下的文件，忽略子目录。
```
./ks3util ks3://samplebucket/src-prefix/ ks3://samplebucket/dst-prefix/ -r --only-current-dir
```
按条件复制
使用--include和--exclude选项复制符合匹配规则的文件，--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

rm（删除）

rm用于删除存储在KS3的文件，删除桶，删除碎片。

注意：删除后无法恢复，请谨慎操作！

命令格式

./ks3util rm ks3://bucketname[/prefix]
[-r, --recursive] 
[-f, --force] 
[-b, --bucket]
[-m, --multipart]
[-a, --all-type]
[--include <value>]
[--exclude <value>]

参数及选项说明如下：

配置项	说明
bucketname	操作的桶名。
prefix	操作的对象的前缀。
-r, --recursive	删除Bucket下所有符合prefix条件的Object。如果不指定该选项，则只删除指定Object。
-f, --force	强制操作，不进行询问提示。
-b, --bucket	对Bucket进行操作，该选项用于确认操作作用于Bucket。
-m, --multipart	指定操作的对象为Bucket中未完成的Multipart事件，而非默认情况下的Object。
-a, --all-type	指定操作的对象为Bucket中符合prefix条件的Object和未完成的Multipart事件。
--include	包含对象匹配模式，如：*.jpg。
--exclude	不包含对象匹配模式，如：*.txt。

删除文件

删除单个文件

./ks3util rm ks3://samplebucket/src-prefix/sample.txt

批量删除文件
删除指定前缀的文件。
```
./ks3util rm ks3://samplebucket/src-prefix/ -r
```
按匹配条件删除，--include和--exclude选择的用法参见通用选项。
```
./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/ 部分）。

删除碎片

删除单文件碎片
删除单个文件未完成的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，--include和--exclude选择的用法参见通用选项。
```
./ks3util rm ks3://samplebucket/src-prefix/ -m -r --include *screenshot* --exclude *important*
```
删除匹配条件的文件、以及未完成的Multipart事件产生的Part，--include和--exclude选择的用法参见通用选项。
```
./ks3util rm ks3://samplebucket/src-prefix/ -a -r --include *screenshot* --exclude *important*
```

删除桶

删除空桶
删除桶前请确保桶内文件和未完成的Multipart事件产生的Part、自定义域名、空间策略、区域复制等已删除。
```
./ks3util rm ks3://samplebucket -b
```
删除所有文件然后删除桶
```
./ks3util rm ks3://samplebucket -b -r
```

set-acl（设置或修改ACL）

set-acl命令用于设置Bucket或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。

使用示例

给Bucket设置acl

./ks3util set-acl ks3://samplebucket private -b

给单个文件设置acl

./ks3util set-acl ks3://samplebucket/src-prefix/sample.txt private

批量设置acl
批量给指定前缀的文件设置acl。
```
./ks3util set-acl ks3://samplebucket/src-prefix/ private -r
```
批量给符合匹配规则的文件设置acl，--include和--exclude的用法参见通用选项。
```
./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/ 部分）。

set-meta（管理文件元信息）

文件元信息是对文件（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，--include和--exclude的用法参见通用选项。
```
./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，--include和--exclude的用法参见通用选项。
```
./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，--include和--exclude的用法参见通用选项。
```
./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/ 部分）。

stat（查看Bucket或Object信息）

stat命令用于查看指定存储空间（Bucket）或者对象（Object）的相关信息。例如，可以通过该命令查看Bucket的存储类型、Object元信息等。

命令格式

./ks3util stat ks3://bucketname[/objectname]

参数及选项说明如下：

配置项	说明
bucketname	目标Bucket名称。
objectname	目标Object名称。

使用示例

查看Bucket的信息
```
./ks3util stat ks3://samplebucket
```

查看Object的信息

./ks3util stat ks3://samplebucket/objectname

mb（创建Bucket）

存储空间（Bucket）是用于存储对象（Object）的容器。在上传任意类型的Object前，需要先创建Bucket。mb命令用于创建Bucket。创建的Bucket的地域为配置文件或选项中指定的Endpoint所在的地域。

命令格式

./ks3util mb ks3://bucketname [--acl <value>] [--bucket-type <value>]

参数及选项说明如下：

配置项	说明
bucketname	目标Bucket名称。
--acl	Bucket的读写权限，取值：private（默认），public-read，public-read-write。
--bucket-type	Bucket的存储类型，取值：NORMAL（默认），ARCHIVE。

使用示例

仅创建Bucket
```
./ks3util mb ks3://samplebucket
```

创建Bucket并指定读写权限、存储类型

./ks3util mb ks3://samplebucket --acl public-read --bucket-type ARCHIVE

mkdir（创建目录）

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/目录也会被自动移除。

restore（解冻）

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

批量给符合匹配规则的文件解冻，--include和--exclude的用法参见通用选项。

./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/ 部分）。

cat（输出到标准输出流）

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（流式上传）

rcat命令用于流式上传文件，需与管道配合使用，如果ks3上已存在同名文件，则会覆盖。

命令格式

./ks3util rcat ks3://bucketname/objectKey 
[-f, --force]
[--acl <acl>] 
[--meta <meta>] 
[--tagging <tagging>] 
[-j, --jobs <job-num>] 
[--part-size <part-size>]

参数及选项说明如下：

配置项	说明
bucketname	操作的桶名。
objectKey	操作的对象名。
--acl	acl信息的配置。
--meta	设置Object的meta为`header:value#header:value`，如：Cache-Control:no-cache#Content-Encoding:gzip。
--tagging	设置Object的tagging，取值格式如`"TagA=A&TagB=B"`，注意：需要使用双引号。
--storage-class	对象的存储类型，取值：STANDARD，STANDARD_IA，ARCHIVE。
-j, --jobs	多文件操作时的并发任务数，默认值：3，取值范围：1-10000。
--part-size	分片大小，单位为Byte，默认情况下ks3util根据文件大小自行计算合适的分片大小值。如果有特殊需求或者需要性能调优，可以设置该值，取值范围：1-5368709120(Byte)。

使用示例

流式上传文件

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

sync（同步目录）

该命令用于将本地文件目录或者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]

参数及选项说明如下：

配置项	说明
local_dir	本地目录。
bucketname	操作的桶名。
prefix	操作的对象前缀。
-f, --force	强制操作，不进行询问提示。
-u, --update	更新操作，只有当目标文件不存在，或源文件的最后修改时间晚于目标文件时，ks3util才会执行上传操作。
--delete	表示需要删除或者移走目的端存在而源端不存在的Object或者文件。
--backup-dir	用于备份目的端文件的目录，不能是目的端目录的子目录，如果输入了–delete，该选项必须输入。

使用示例

从本地目录同步到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

set-storage-class（设置存储类型）

该命令用于设置指定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/ 部分）。

set-tag（设置标签）

该命令可设置、更新、删除指定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
```
- 设置匹配条件的文件的标签，--include和--exclude的用法参见通用选项。
```
./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 
```
- 更新匹配条件的文件的标签，--include和--exclude的用法参见通用选项。
```
./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 "belongs=kevin&test-file=true"
```
- 删除指定前缀的所有文件的标签
```
ks3util set-tag ks3://samplebucket/test-files/ "belongs=kevin&test-file=true" -r --delete
```
- 删除匹配条件的文件的标签，--include和--exclude的用法参见通用选项。
```
./ks3util set-tag ks3://samplebucket/test-files/ "belongs=kevin&test-file=true" -r --include *.log --exclude tom-* --delete
```
- 删除指定列表文件的标签
```
./ks3util set-tag ks3://samplebucket/ "belongs=kevin&test-file=true" --object-file object_keys_file --delete
```
  注：object_keys_file为本地.txt文件的路径，文件内填写指定Object列表，每个objectKey为一行（不包含ks3://bucket/ 部分）。

sign (生成上传或者下载链接）

sign命令用于该命令签名用户指定的cloud_url，生成经过签名的url可供第三方用户访问Object。

命令格式

./ks3util sign ks3://bucketname[/prefix]
[-r, --recursive]
[-f, --force]
[--include <value>]
[--exclude <value>]
[--timeout <value>]
[--sign-method <value>]

参数及选项说明如下：

配置项	说明
bucketname	操作的桶名。
prefix	操作的对象的前缀。
-r, --recursive	递归进行操作。对于支持该选项的命令，当指定该选项时，命令会对目录下所有符合条件的文件进行操作，否则只对指定的单个文件进行操作。
-f, --force	强制操作，不进行询问提示。
--include	包含对象匹配模式，如：*.jpg。
--exclude	不包含对象匹配模式，如：*.txt。
--timeout	外链过期时间，默认值：10(单位秒) 。
--sign-method	生成下载链接或者上传链接，默认值：get，可选值为 get 、put。

生成下载链接，单个签名默认 ‘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

批量给符合匹配规则的文件签名，--include和--exclude的用法参见通用选项。
```
./ks3util sign ks3://samplebucket/src-prefix -r --include *.txt
```

lifecycle（生命周期）

lifecycle命令用于添加或修改Lifecycle规则、获取Lifecycle规则、删除Lifecycle规则。
配置Lifecycle规则后，KS3会定期将对象（Object）转储为低频、归档存储类型，或将过期的Object和碎片删除，从而节省存储费用。以下介绍如何通过lifecycle命令添加、修改、查询、删除Lifecycle规则配置。

添加或修改Lifecycle规则

添加或修改Lifecycle规则步骤如下所示：

1. 创建本地文件，并根据使用场景在该文件中写入Lifecycle规则。

2. KS3Util先从本地文件中读取Lifecycle配置，然后根据读取到Lifecycle配置为指定Bucket添加Lifecycle规则。

命令格式

./ks3util lifecycle --method put ks3://bucketname local_xml_file

参数说明如下：

参数	说明
bucketname	配置Lifecycle规则的Bucket名称。
local_xml_file	配置Lifecycle规则的本地文件名称，例如`localfile.txt`。

使用示例

a. 在本地创建名为`localfile.txt`的文件，并根据使用场景写入不同的Lifecycle规则。

常见的Lifecycle规则如下：

示例一

指定Lifecycle规则应用于目标存储空间examplebucket，指示与前缀test/匹配的Object距其最后修改时间超过30天后转换为ARCHIVE存储类型。

<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
  <Rule>
    <ID>test-rule1</ID>
    <Filter>
      <Prefix>test/</Prefix>
    </Filter>
    <Status>Enabled</Status>
    <Transition>
      <Days>30</Days>
      <StorageClass>ARCHIVE</StorageClass>
    </Transition>
  </Rule>
</LifecycleConfiguration>

示例二

指定Lifecycle规则应用于目标存储空间examplebucket，指示与前缀test/匹配的Object最后更新 365 天后，文件删除。

<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
  <Rule>
    <ID>test-rule2</ID>
    <Filter>
      <Prefix>test/</Prefix>
    </Filter>
    <Status>Enabled</Status>
    <Expiration>
      <Days>365</Days>
    </Expiration>
  </Rule>
</LifecycleConfiguration>

示例三

指定Lifecycle规则应用于目标存储空间examplebucket，指示与前缀test/匹配的Object在分块上传任务初始化10天后，删除未完成的分块上传任务。

<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
  <Rule>
    <ID>test-rule3</ID>
    <Filter>
      <Prefix>test/</Prefix>
    </Filter>
    <Status>Enabled</Status>
    <AbortIncompleteMultipartUpload>
      <DaysAfterInitiation>10</DaysAfterInitiation>
    </AbortIncompleteMultipartUpload>
  </Rule>
</LifecycleConfiguration>

b. 添加Lifecycle规则。

为examplebucket添加Lifecycle规则。

./ks3util lifecycle --method put ks3://examplebucket localfile.txt

以下输出结果表明已成功添加Lifecycle规则。

0.299514(s) elapsed

获取Lifecycle规则

命令格式

./ks3util lifecycle --method get ks3://bucketname [local_xml_file]

参数说明如下：

参数	说明
bucketname	获取Lifecycle规则配置的目标Bucket名称。
local_xml_file	用于存放Lifecycle规则配置的本地文件名称，例如`localfile.txt`。如果未指定此参数，则Lifecycle规则配置将直接输出到屏幕。

使用示例

获取examplebucket的Lifecycle规则。

./ks3util lifecycle --method get ks3://examplebucket localfile.txt

以下输出结果表明已成功获取Lifecycle规则配置，并将其写入本地localfile.txt文件。

0.299514(s) elapsed

删除Lifecycle规则

命令格式

./ks3util lifecycle --method delete ks3://bucketname

参数说明如下：

参数	说明
bucketname	删除Lifecycle规则配置的目标Bucket名称。

使用示例

删除examplebucket的Lifecycle规则。

./ks3util lifecycle --method delete ks3://examplebucket

以下输出结果表明已成功删除examplebucket的Lifecycle规则配置。

0.299514(s) elapsed

bucket-policy（空间策略）

Bucket Policy是基于资源的授权策略，Bucket拥有者可以通过Bucket Policy授权其他用户访问KS3指定资源。bucket-policy命令用于添加、修改、查询、删除Bucket授权策略。有关空间策略规则的更多详情请参见文档：空间策略（Bucket Policy）。

添加或修改Bucket Policy配置

如果Bucket此前未添加过Bucket Policy配置，则使用该命令将为Bucket添加Bucket Policy配置。如果Bucket已存在Bucket Policy配置，则使用该命令将直接覆盖已有的Bucket Policy配置。

添加或修改Bucket Policy配置步骤如下：

1. 创建本地文件，并在文件中添加Bucket Policy规则。

2. KS3Util先从本地文件中读取Bucket Policy配置，然后将读取到的Bucket Policy配置添加到指定的Bucket。

命令格式

./ks3util bucket-policy --method put ks3://bucketname local_json_file

参数说明如下：

参数	说明
bucketname	添加或修改Bucket Policy的目标存储空间名称。
local_json_file	配置Bucket Policy的本地JSON文件名称，例如`localfile.txt`。

使用示例

a. 在本地创建名为`localfile.txt`的文件，并根据使用场景写入不同的Bucket Policy规则。

常见的Bucket Policy配置规则如下：

示例一

授予主账号为10000123456的用户拥有examplebucket桶下全部资源的只读权限。

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ks3:ListBucket",
        "ks3:ListBucketMultipartUploads",
        "ks3:GetObject",
        "ks3:GetObjectAcl",
        "ks3:ListMultipartUploadParts"
      ],
      "Principal": {
        "KSC": [
          "krn:ksc:iam::20000123456:root"
        ]
      },
      "Resource": [
        "krn:ksc:ks3:::examplebucket",
        "krn:ksc:ks3:::examplebucket/*"
      ]
    }
  ]
}

示例二

授予主账号为10000123456下的子账号test-child1拥有examplebucket桶下data目录中资源的读写权限。

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ks3:ListBucket",
        "ks3:ListBucketMultipartUploads",
        "ks3:GetObject",
        "ks3:PutObject",
        "ks3:DeleteObject",
        "ks3:AbortMultipartUpload",
        "ks3:ListMultipartUploadParts",
        "ks3:PostObjectRestore",
        "ks3:GetObjectAcl",
        "ks3:PutObjectAcl"
      ],
      "Principal": {
        "KSC": [
          "krn:ksc:iam::10000123456:user/test-child1"
        ]
      },
      "Resource": [
        "krn:ksc:ks3:::examplebucket",
        "krn:ksc:ks3:::examplebucket/data/*"
      ]
    }
  ]
}

示例三

授予指定IP下的用户拥有examplebucket桶的全部权限。

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ks3:*"
      ],
      "Principal": {
        "KSC": [
          "*"
        ]
      },
      "Resource": [
        "krn:ksc:ks3:::examplebucket",
        "krn:ksc:ks3:::examplebucket/*"
      ],
      "Condition": {
        "IpAddress": {
          "ksc:SourceIp": [
            "54.240.143.1"
          ]
        }
      }
    }
  ]
}

b. 添加Bucket Policy规则。

为examplebucket桶添加Bucket Policy规则。

./ks3util bucket-policy --method put ks3://examplebucket localfile.txt

以下输出结果表明已成功添加Bucket Policy规则。
```
0.204926(s) elapsed
```

获取Bucket Policy配置

命令格式

./ks3util bucket-policy --method get ks3://bucketname [local_json_file]

参数说明如下：

参数	说明
bucketname	添加或修改Bucket Policy的目标存储空间名称。
local_json_file	用于存放Bucket Policy配置的本地文件名称，例如`localfile.txt`。如果未指定此参数，则Bucket Policy配置将直接输出到屏幕。

使用示例

获取目标存储空间examplebucket的Bucket Policy配置，并将配置结果写入本地文件localfile.txt。
```
./ks3util bucket-policy --method get ks3://examplebucket localfile.txt
```
以下输出结果表明已成功获取Bucket Policy配置。
```
0.188731(s) elapsed
```

删除Bucket Policy配置

命令格式

./ks3util bucket-policy --method delete ks3://bucketname

参数说明如下：

参数	说明
bucketname	删除Bucket Policy规则配置的目标Bucket名称。

使用示例

删除examplebucket的Bucket Policy配置。

./ks3util bucket-policy --method delete ks3://examplebucket

以下输出结果表明已删除examplebucket的Bucket Policy配置。
```
0.156663(s) elapsed
```

logging（日志转存）

访问对象存储KS3的过程中会产生大量的访问日志，您可以通过日志转存功能将这些日志按照固定命名规则，以小时为单位生成日志文件写入您指定的Bucket。您可以通过logging命令开启、查询、关闭Bucket的日志转存配置。

开启日志转存

如果Bucket此前未开启过日志转存，则使用该命令将为Bucket开启日志转存。如果Bucket此前已开启日志转存，则使用该命令将直接覆盖已有的日志转存配置。

开启或修改日志转存配置的命令格式及示例如下：

命令格式

./ks3util logging --method put ks3://bucketname ks3://targetbucket/[prefix]

参数说明如下：

参数	说明
bucketname	生成日志的源Bucket名称。
targetbucket	存储日志文件的目标Bucket名称。
prefix	日志文件存储的目录。如果指定此项，则日志文件将保存在目标Bucket的指定目录下。如果不指定此项，则日志文件将保存在目标Bucket的根目录下。

生成日志的源Bucket和存储日志的目标Bucket可以相同也可以不同，但是必须位于同一账号下的相同地域。

使用示例

将源存储空间srcbucket产生的日志文件保存至目标存储空间destbucket的根目录下。

./ks3util logging --method put ks3://srcbucket ks3://destbucket

将源存储空间srcbucket产生的日志文件保存至目标存储空间destbucket的根目录下的子目录destdir下。

./ks3util logging --method put ks3://srcbucket ks3://destbucket/destdir

以下输出结果表明已为srcbucket开启日志转存。

0.016021(s) elapsed

查看日志转存配置

命令格式

./ks3util logging --method get ks3://bucketname [local_xml_file]

参数说明如下：

参数	说明
bucketname	待获取日志转存配置的Bucket名称。
local_xml_file	存放日志转存配置的本地文件名称，例如`localfile.txt`。如果未指定此参数，则日志转存配置将直接输出到屏幕。

使用示例

获取存储空间examplebucket的日志转存配置，并将配置结果写入本地文件localfile.txt。

./ks3util logging --method get ks3://examplebucket localfile.txt

以下输出结果表明已成功获取日志转存配置。

0.299514(s) elapsed

关闭日志转存

在您关闭日志转存功能前，KS3的日志文件会一直生成。请结合Lifecycle规则及时清理不再需要的日志文件，以减少您的存储费用。

命令格式

./ks3util logging --method delete ks3://bucketname

参数说明如下：

参数	说明
bucketname	要关闭日志转存功能的Bucket名称。

使用示例

关闭存储空间examplebucket的日志转存功能。

./ks3util logging --method delete ks3://examplebucket

以下输出结果表明已成功关闭examplebucket的日志转存功能。

0.299514(s) elapsed

cors（跨域资源共享）

跨域资源共享CORS（Cross-Origin Resource Sharing）简称跨域访问，是HTML5提供的标准跨域解决方案，允许Web应用服务器进行跨域访问控制，确保跨域数据传输的安全性。本文介绍如何通过cors命令添加、修改、查询、删除存储空间（Bucket）的CORS配置。

添加或修改CORS配置

如果Bucket此前未添加过CORS配置，则使用该命令将为Bucket添加CORS配置。如果Bucket此前已添加CORS配置，则使用该命令将直接覆盖已有的CORS配置。

添加或修改CORS配置步骤如下：

1. 创建本地文件，并在文件中添加CORS规则。

2. KS3Util先从本地文件中读取CORS配置，然后将读取到CORS配置添加到指定的Bucket。

添加或修改CORS配置的命令格式及示例如下：

命令格式

./ks3util cors --method put ks3://bucketname local_xml_file

参数说明如下：

参数	说明
bucketname	待添加或修改CORS配置的Bucket名称。
local_xml_file	配置CORS规则的本地文件名称，例如`localfile.txt`。

使用示例

a. 在本地创建名为`localfile.txt`文件，并根据使用场景配置CORS规则。

如下示例表示在CORS规则中指定允许的跨域请求来源为www.ksyun.com、允许的跨域请求方法为PUT以及浏览器对特定资源的预取（OPTIONS）请求返回结果的缓存时间为10000秒。

<?xml version="1.0" encoding="UTF-8"?>
   <CORSConfiguration>
     <CORSRule>
         <AllowedOrigin>http://www.ksyun.com</AllowedOrigin>
         <AllowedMethod>PUT</AllowedMethod>
         <AllowedHeader>*</AllowedHeader>
         <MaxAgeSeconds>10000</MaxAgeSeconds>
     </CORSRule>
 </CORSConfiguration>

b. 添加CORS规则。

为examplebucket添加CORS规则。

./ks3util cors --method put ks3://examplebucket localfile.txt

以下输出结果表明已成功添加CORS规则。

0.299514(s) elapsed

获取CORS配置

命令格式

./ks3util cors --method get ks3://bucketname [local_xml_file]

参数说明如下：

参数	说明
bucketname	获取CORS配置的目标Bucket名称。
local_xml_file	用于存放CORS配置的本地文件名称，例如`localfile.txt`。如果未指定此参数，则CORS配置将直接输出到屏幕。

使用示例

获取目标存储空间examplebucket的CORS配置，并将配置结果写入本地文件localfile.txt。

./ks3util cors --method get ks3://examplebucket localfile.txt

以下输出结果表明已成功获取日志转存配置。

0.299514(s) elapsed

删除CORS配置

命令格式

./ks3util cors --method delete ks3://bucketname

参数说明如下：

参数	说明
bucketname	要删除CORS配置的Bucket名称。

使用示例

删除examplebucket的CORS配置。

./ks3util cors --method delete ks3://examplebucket

以下输出结果表明已删除examplebucket的CORS配置。

0.299514(s) elapsed

hash（计算CRC64或MD5）

hash命令用于计算本地文件的CRC64或MD5值。

命令格式

./ks3util hash localfile [--type <value>]

参数及选项说明如下：

配置项	说明
localfile	本地文件的完整路径。
--type	数据完整性校验算法类型，可选值有crc64\|md5。 crc64（默认）：计算本地文件的CRC64值。 md5：计算本地文件的MD5值。取值为MD5时，会同时输出文件的MD5以及Content-MD5值。Content-MD5值是在计算MD5值获得128比特位数字的基础上，对该数字进行base64编码。关于Content-MD5的更多信息，请参见RFC1864。

配置项

说明

localfile

本地文件的完整路径。

--type

数据完整性校验算法类型，可选值有crc64|md5。

crc64（默认）：计算本地文件的CRC64值。
md5：计算本地文件的MD5值。取值为MD5时，会同时输出文件的MD5以及Content-MD5值。Content-MD5值是在计算MD5值获得128比特位数字的基础上，对该数字进行base64编码。关于Content-MD5的更多信息，请参见RFC1864。

注意事项：

您可以通过stat命令中返回的Content-Md5和X-Kss-Checksum-Crc64ecma分别获取KS3内文件的Content-MD5和CRC64值。
在KS3支持CRC64校验之前上传至Bucket内的文件，不支持通过stat命令查看文件的CRC64值。
对于通过分块上传或追加上传方式上传的文件，不支持通过stat命令查看文件的Content-MD5值。

使用示例

计算本地文件localfile.txt的CRC64值

./ks3util hash localfile.txt --type crc64

计算本地文件localfile.txt的MD5值

./ks3util hash localfile.txt --type md5

update（更新版本）

update命令用于ks3util更新版本。该命令会联网检查是否有新版本，如果有新版本，则询问是否进行更新；如果指定了–force选项，则不询问。

命令格式

./ks3util update [-f, --force]

选项说明如下：

选项	说明
-f, --force	强制操作，不进行询问提示。

使用示例

./ks3util update
当前版本为：1.0.0，最新版本为：2.0.0
确定更新版本(y or N)? y
更新成功!

常见问题

1. 上传、下载速度没有达到预期

当ks3util自行设置的默认并发数达不到用户的性能要求时，可以自行调整这两个选项来升降性能。默认情况下，ks3util会根据文件大小来计算parallel个数。当批量上传大文件时，实际的并发数为jobs个数乘以parallel个数。
当服务器在网络、内存、CPU等资源不是特别大的情况下，建议将并发数调整到100以下。如果网络、内存、CPU等资源没有占满，可以适当增加并发数。
由于线程间资源切换及抢夺等原因，如果并发数过大，ks3util上传性能可能会下降。此外，并发数过大还可能产生EOF错误。所以请根据实际的机器情况调整-j, --jobs和--parallel选项的数值。如果要进行压测，可在一开始时调低这两项数值，然后逐渐调大直至找到符合预期值。

2. 使用ls命令查看Bucket内已无文件，但删除Bucket时报错

原因分析：Bucket上仍关联其他资源。

解决方案：首先使用ls命令查看是否仍有未完成的Multipart事件产生的Part，命令：ls ks3://bucketname -m，如果有则需要删除，命令：rm ks3://bucketname -m -r；登录对象存储控制台，查看该Bucket是否存在自定义域名、空间策略、区域复制等配置，如果有则需要删除；然后重试删除桶。

3. 使用cp复制桶之间的数据时，需要注意的事项

原因分析：copy接口不能复制增量的meta。

解决方案：需要在复制完成后再次调用set-meta or set-acl命令进行修改设置。

文档导读

上一篇：KS3工具概览

下一篇：KS3 Finder图形化界面工具

纯净模式常规模式

纯净模式

点击可全屏预览文档内容