• 热门
  • 基础
  • 数据库
  • 安全
  • 大数据
  • 人工智能
  • 混合云
  • 开发与运维
  • 企业应用

应用服务

行业引擎

全部文档
当前文档

暂无内容

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

文档中心

对象操作

最近更新时间:2024-12-13 18:50:37

概述

本文以 Linux系统为例,介绍使用 KS3Util工具的对象操作的命令和相关示例。

上传文件(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>]
[--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,取值格式如["TagA=A&TagB=B..."],注意:需要使用双引号。

--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参数进行上传前的软链接循环嵌套检测。

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

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,取值格式如["TagA=A&TagB=B..."],注意:需要使用双引号。

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

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。

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)

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)

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)

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)

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,取值格式如["TagA=A&TagB=B..."],注意:需要使用双引号。

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

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

设置ACL规则(set-acl)

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

管理文件元信息(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

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

同步目录(sync)

该命令用于将本地文件目录或者ks3 prefix从源端同步到目的端。

不支持本地目录之间的同步。

该命令和cp命令类似:支持从本地文件系统上传文件到ks3,从ks3下载Object到本地文件系统,在ks3上进行Object拷贝;用于源端和目的端数据同步。

sync命令和cp命令不同之处如下:

  1. 当输入--delete选项时,该命令会自动删除目的端存在而源端不存在的Object或者移走本地文件。如果目的端是ks3,则会删除多余的Object;如果目的端是本地文件,则会移走本地多余的文件。

    警告:在没有完全搞清楚sync命令的行为之前,请慎用--delete

  2. sync强制是以recursive方式遍历文件或者Object的,所以不用输入-r --recursive。

  3. 当源端是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命令用于解冻归档存储类型的文件。有关解冻规则的更多详情请参见文档: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/ 部分)。

设置文件存储类型(set-stroage-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/ 部分)。

查看文件信息(stat)

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

对象标签(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
    • 设置匹配条件的文件的标签

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

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>]
[--disable-crc64]
参数说明

参数

说明

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

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

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

纯净模式常规模式

纯净模式

点击可全屏预览文档内容
文档反馈

聆听反馈