文档首页

全部产品

对象存储（COS）

租户端存储对象存储（COS）工具指南

COSCMD工具

最近更新时间: 2024-06-12 15:06:00

功能说明

使用 COSCMD 工具，用户可通过简单的命令行指令实现对对象（Object）的批量上传、下载、删除等操作。

注意：

使用该工具上传同名文件，会覆盖较旧的同名文件，不支持校对是否存在同名文件的功能。

使用环境

系统环境

支持 Windows、Linux 和 macOS 系统。

说明：

请保证本地字符格式为 UTF-8，否则操作中文件会出现异常。

请确保本机时间已经与国际标准时间校准，如误差过大，将导致无法正常使用。

软件依赖

Python 2.7/3.5/3.6。
最新版本的 pip。

安装及配置

环境安装与配置详细操作请参见官方文档 Python 安装和使用。
pip 环境安装与配置详细操作请参见官网 pip 安装说明。

下载与安装

通过 pip 命令直接安装

执行 pip 命令进行安装：

pip install coscmd

安装成功之后，用户可以通过coscmd -v或者coscmd --version命令查看当前的版本信息。

源码安装（不推荐）

源码地址：https://github.com/tencentyun/coscmd.git。

在 shell 中执行以下三步即可完成安装：

# 通过 git 命令下载源码
git clone https://github.com/tencentyun/coscmd.git

# 进入源代码的目录
cd coscmd

# 执行安装程序
python setup.py install

安装成功之后，用户可以通过coscmd -v或者coscmd --version命令查看当前的版本信息。

注意：

Python 版本为2.6时，pip 安装依赖库时容易失败，推荐使用该方法安装。

离线安装

需要一台有外网的机器，下载软件包，随后传到需要运行的机器上进行安装。

注意：

请确保两台机器的 Python 版本保持一致，否则会出现安装失败的情况。

# 在有外网的机器下运行如下命令
mkdir coscmd-packages
pip download coscmd -d coscmd-packages
tar -czvf coscmd-packages.tar.gz coscmd-packages

# 将安装包拷贝到没有外网的机器后运行如下命令
tar -xzvf coscmd-packages.tar.gz
pip install coscmd --no-index -f coscmd-packages

安装成功之后，用户可以通过coscmd -v或者coscmd --version命令查看当前的版本信息。

使用方法

查看 help

用户可通过-h或--help命令来查看工具的 help 信息。

coscmd -h  //查看当前版本信息

help 信息如下所示：

usage: coscmd [-h] [-d] [-b BUCKET] [-r REGION] [-c CONFIG_PATH] [-l LOG_PATH]
              [-v]

              {info,restore,createbucket,signurl,listparts,mget,list,upload,deletebucket,abort,getbucketversioning,putbucketacl,getobjectacl,download,putobjectacl,copy,config,putbucketversioning,getbucketacl,delete}
              ...

an easy-to-use but powerful command-line tool. try 'coscmd -h' to get more
informations. try 'coscmd sub-command -h' to learn all command usage, likes
'coscmd upload -h'

positional arguments:
  {info,restore,createbucket,signurl,listparts,mget,list,upload,deletebucket,abort,getbucketversioning,putbucketacl,getobjectacl,download,putobjectacl,copy,config,putbucketversioning,getbucketacl,delete}
    config              Config your information at first
    upload              Upload file or directory to COS
    download            Download file from COS to local
    delete              Delete file or files on COS
    abort               Aborts upload parts on COS
    copy                Copy file from COS to COS
    list                List files on COS
    listparts           List upload parts
    info                Get the information of file on COS
    mget                Download file from COS to local
    restore             Restore
    signurl             Get download url
    createbucket        Create bucket
    deletebucket        Delete bucket
    putobjectacl        Set object acl
    getobjectacl        Get object acl
    putbucketacl        Set bucket acl
    getbucketacl        Get bucket acl
    putbucketversioning
                        Set the versioning state
    getbucketversioning
                        Get the versioning state
    probe               Connection test

optional arguments:
  -h, --help            show this help message and exit
  -d, --debug           Debug mode
  -b BUCKET, --bucket BUCKET
                        Specify bucket
  -r REGION, --region REGION
                        Specify region
  -c CONFIG_PATH, --config_path CONFIG_PATH
                        Specify config_path
  -l LOG_PATH, --log_path LOG_PATH
                        Specify log_path
  -v, --version         show program's version number and exit

除此之外，用户还可以在每个命令后（不加参数）输入 -h 查看该命令的具体用法，例如：

coscmd upload -h  //查看 upload 命令使用方法

配置参数

COSCMD 工具在使用前需要进行参数配置，用户可以通过如下命令来配置：

coscmd config [OPTION]...<FILE>...
        [-h] --help
        [-a] <SECRET_ID>                 // 该参数配置 Secret ID
        [-s] <SECRET_KEY>                // 该参数配置 Secret Key
        [-t] <TOKEN>
        [-b] <BucketName-APPID>          // 该参数配置要访问的 Bucket
        [-e] <ENDPOINT> | [-r] <REGION>  // -r, -e 二选一，专有云只需通过 -e 配置访问节点
        [-m] <MAX_THREAD>
        [-p] <PART_SIZE>
        [--do-not-use-ssl]               // 该参数表示不使用 HTTPS 协议，即使用 HTTP 协议
        [--anonymous]

参数配置说明如下：

选项	参数说明	是否必选	有效值
-a	密钥 ID	是	字符串
-s	密钥 Key	是	字符串
-b	指定的存储桶名称	是	字符串
-e	设置请求的 ENDPOINT，请参考 2.1.1 节的介绍	是	字符串
-m	多线程操作的最大线程数（默认为5，范围为1 - 30）	否	数字
--do-not-use-ssl	使用 HTTP 协议，而不使用 HTTPS	否	字符串

通常情况下，如您没有特殊的需求，可参照如下操作配置，将相关信息替换为您自己的，即可：

coscmd config -a AChT4ThiXAbpBDEFGhT4ThiXAbp**** -s WE54wreefvds3462refgwewe**** -b examplebucket-1250000000 -e cos.somewhere.example.com --do-not-use-ssl

说明：

生成的配置最终保存在 ~/.cos.conf 文件（在 Windows 环境下，该文件是位于【我的文档】下的一个隐藏文件），该文件初始时不存在，可以通过 coscmd config 命令生成，用户也可以手动创建。配置完成之后的.cos.conf文件内容示例如下所示：

[common] secret_id = AKIDAtIM6U8rrVnQkgNXEEHyOR8TT7P***** secret_key = tRZNpv0C5coeAKXH1SXrqTkgGyM***** bucket = examplebucket-1255000000 endpoint = cos.chongqing.cospub.example.com max_thread = 5 part_size = 1 schema = http verify = md5 anonymous = False

可以在配置文件中修改 schema 项来选择 http/https，默认为 https。

可以在 anonymous 项中选择 True/False，来使用匿名模式，即签名保持为空。

指定 Bucket 和 Endpoint 的命令

通过 -b <BucketName-APPID> 可以指定特定的 Bucket，通过 -e <endpoint> 可以指定特定的 endpoint。存储桶的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式。

#命令格式
coscmd -b <BucketName-APPID> -e <endpoint> <action> ...

#操作示例-创建bucket
coscmd -b examplebucket-1250000000 -e cos.somewhere.example.com createbucket

#操作示例-上传文件
coscmd -b examplebucket-1250000000 -e cos.somewhere.example.com upload exampleobject exampleobject

创建存储桶

可以配合 -b <BucketName-APPID> 指定 Bucket 和 -e <endpoint> 指定 Endpoint 使用。

#命令格式
coscmd -b <BucketName-APPID> createbucket

#操作示例
coscmd createbucket
coscmd -b examplebucket-1250000000 -e cos.somewhere.example.com createbucket

删除存储桶

可以配合 -b <BucketName-APPID> 指定 Bucket 和 -e <endpoint> 指定 Endpoint 使用。

#命令格式
coscmd -b <BucketName-APPID> deletebucket

#操作示例
coscmd deletebucket
coscmd -b examplebucket-1250000000 -e cos.somewhere.example.com deletebucket
coscmd -b examplebucket-1250000000 -e cos.somewhere.example.com deletebucket -f

使用 -f 参数则会强制删除该存储桶，包括所有文件、开启版本控制之后历史文件夹、上传产生的碎片。

上传文件或文件夹

上传文件命令如下：

#命令格式
coscmd upload <localpath> <cospath>

#操作示例
#将本地的 /data/exampleobject 文件上传到 cos 的 data/exampleobject 路径下
coscmd upload /data/exampleobject data/exampleobject 
coscmd upload /data/exampleobject data/

#指定头部上传文件
#指定对象类型，上传一个归档的文件
coscmd upload /data/exampleobject data/exampleobject -H "{'x-cos-storage-class':'Archive'}"

#设置 meta 元属性
coscmd upload /data/exampleobject data/exampleobject -H "{'x-cos-meta-example':'example'}"

上传文件夹命令如下：

#命令格式
coscmd upload -r <localpath> <cospath>

#操作示例
coscmd upload -r /data/examplefolder data/examplefolder
coscmd upload -r /data/examplefolder data/examplefolder

#cos上的存储路径为 examplefolder2/examplefolder
coscmd upload -r /data/examplefolder examplefolder2/

#上传到 bucket 根目录
coscmd upload -r /data/examplefolder/ /

#同步上传，跳过md5相同的文件
coscmd upload -rs /data/examplefolder data/examplefolder

#忽略 .txt 和 .doc 的后缀文件
coscmd upload -rs /data/examplefolder data/examplefolder --ignore *.txt,*.doc

请将 "<>" 中的参数替换为您需要上传的本地文件路径（localpath），以及 COS 上存储的路径（cospath）。

注意：

上传文件时需要将 COS 上的路径包括文件（文件夹）的名字补全（参考例子）。

COSCMD 支持大文件断点上传功能；当分片上传大文件失败时，重新上传该文件只会上传失败的分块，而不会从头开始（请保证重新上传的文件的目录以及内容和上传的目录保持一致）。

COSCMD 分块上传时会对每一块进行 MD5 校验。

COSCMD 上传默认会携带 x-cos-meta-md5 的头部，值为该文件的 md5 值。

使用 -s 参数可以使用同步上传，跳过上传 md5 一致的文件（COS 上的原文件必须是由 1.8.3.2 之后的 COSCMD 上传的，默认带有 x-cos-meta-md5 的 header）。

使用 -H 参数设置 HTTP header 时，请务必保证格式为 JSON，示例：coscmd upload -H "{'x-cos-storage-class&':'Archive&','Content-Language':'zh-CN'}" <localpath> <cospath>

在上传文件夹时，使用--ignore参数可以忽略某一类文件，支持 shell 通配规则，支持多条规则，用逗号,分隔。当忽略一类后缀时，必须最后要输入, 或者加入""。

目前只支持上传最大40TB的单一文件。

下载文件或文件夹

下载文件命令如下：

#命令格式
coscmd download <cospath> <localpath>

#操作示例
coscmd download data/exampleobject /data/exampleobject
coscmd download data/exampleobject /data/

下载文件夹命令如下：

#命令格式
coscmd download -r <cospath> <localpath>

#操作示例
coscmd download -r data/examplefolder/ /data/examplefolder
coscmd download -r data/examplefolder/ /data/

#覆盖下载当前bucket根目录下所有的文件
coscmd download -rf / /data/examplefolder

#同步下载当前 bucket 根目录下所有的文件，跳过 md5校验相同的文件
coscmd download -rs / /data/examplefolder

#忽略 .txt 和 .doc 的后缀文件
coscmd download -rs / /data/examplefolder --ignore *.txt,*.doc

请将 "<>" 中的参数替换为您需要下载的 COS 上文件的路径（cospath），以及本地存储路径（localpath）。

注意：

老版本的 mget 接口已经废除，download 接口使用分块下载，请使用 download 接口。

若本地存在同名文件，则会下载失败，需要使用-f参数覆盖本地文件。

使用 -s 或者 --sync 参数，可以在下载文件夹时跳过本地已存在的相同文件（前提是下载的文件是通过 COSCMD 的 upload 接口上传的，文件携带有 x-cos-meta-md5 头部）。

在下载文件夹时，使用--ignore参数可以忽略某一类文件，支持 shell 通配规则，支持多条规则，用逗号,分隔。当忽略一类后缀时，必须最后要输入,或者加入""。

删除文件或文件夹

删除文件命令如下：

#命令格式
coscmd delete <cospath>

#操作示例
coscmd delete data/exampleobject

删除文件夹命令如下：

#命令格式
coscmd delete -r <cospath>

#操作示例
coscmd delete -r /data/examplefolder/
coscmd delete -r /

请将"<>"中的参数替换为您需要删除的 COS 上文件的路径（cospath），工具会提示用户是否确认进行删除操作。

注意：

批量删除需要输y入确定，使用-f参数则可以跳过确认直接删除。

查询分块上传文件碎片

命令如下：

#命令格式
coscmd listparts <cospath>

#操作示例
coscmd listparts examplefolder/

清除分块上传文件碎片

命令如下：

#命令格式
coscmd abort

#操作示例
coscmd abort

复制文件或文件夹

复制文件命令如下：

#命令格式
coscmd copy <sourcepath> <cospath> 

#操作示例
#复制 examplebucket2-1250000000 存储桶下的 data/exampleobject 对象到 examplebucket1-1250000000 存储桶的 data/examplefolder/exampleobject
coscmd -b examplebucket1-1250000000 -r ap-guangzhou copy examplebucket2-1250000000.ap-beijing.myqcloud.com/data/exampleobject data/examplefolder/exampleobject

#修改存储类型，将文件类型改为低频
coscmd -b examplebucket1-1250000000 -r ap-guangzhou copy examplebucket2-1250000000.ap-beijing.myqcloud.com/data/exampleobject data/examplefolder/exampleobject -H "{'x-cos-storage-class':'STANDARD_IA'}"

#修改存储类型，将文件类型改为归档
coscmd -b examplebucket1-1250000000 -r ap-guangzhou copy examplebucket2-1250000000.ap-beijing.myqcloud.com/data/exampleobject data/examplefolder/exampleobject -H "{'x-cos-storage-class':'Archive'}"

复制文件夹命令如下：

#命令格式
coscmd copy -r <sourcepath> <cospath>

#操作示例
#复制 examplebucket2-1250000000 存储桶下的 examplefolder 目录到 examplebucket1-1250000000 存储桶的 examplefolder 目录
coscmd -b examplebucket1-1250000000 -r ap-guangzhou copy -r examplebucket2-1250000000.cos.ap-guangzhou.myqcloud.com/examplefolder/ examplefolder
coscmd -b examplebucket1-1250000000 -r ap-guangzhou copy -r examplebucket2-1250000000.cos.ap-guangzhou.myqcloud.com/examplefolder/ examplefolder/

请将"<>"中的参数替换为您需要复制的 COS 上文件的路径（sourcepath），和您需要复制到 COS 上文件的路径（cospath）。

说明：

sourcepath 的格式为：<BucketName-APPID>.cos.<region>.myqcloud.com/<cospath>。

使用 -d 参数可以设置 x-cos-metadata-directive 参数，可选值为 Copy 和 Replaced，默认为 Copy。

使用 -H 参数设置 HTTP header 时，请务必保证格式为 JSON，示例：coscmd copy -H -d Replaced "{'x-cos-storage-class':'Archive','Content-Language':'zh-CN'}" <localpath> <cospath>

查询文件列表

查询命令如下：

#命令格式
coscmd list <cospath>

#操作示例
#递归查询该存储桶下所有的文件列表
coscmd list -ar

#递归查询 examplefolder 前缀的所有文件列表
coscmd list examplefolder/  -ar

请将"<>"中的参数替换为您需要查询文件列表的 COS 上文件的路径（cospath）。

使用-a查询全部文件。
使用-r递归查询，并且会在末尾返回列出文件的数量和大小之和。
使用-n num设置查询数量的最大值。

<cospath>为空默认查询当前存储桶根目录。

显示文件信息

命令如下：

#命令格式
coscmd info <cospath> 

#操作示例
coscmd info exampleobject

请将"<>"中的参数替换为您需要显示的 COS 上文件的路径（cospath）。

获取带签名的下载 URL

命令如下：

#命令格式
coscmd signurl <cospath>

#操作示例
coscmd signurl exampleobject
coscmd signurl exampleobject -t 100

请将 "<>" 中的参数替换为您需要获取下载 URL 的 COS 上文件的路径（cospath）。使用-t time设置查询签名的有效时间（单位为秒）。

开启/暂停版本控制

命令如下：

#命令格式
coscmd putbucketversioning <status>

#开启版本控制
coscmd putbucketversioning Enabled

#暂停版本控制
coscmd putbucketversioning Suspended

请将 "<>" 中的参数替换为您需要版本控制状态（status）。

注意：

一旦您对存储桶启用了版本控制，它将无法返回到未启用版本控制状态（初始状态）。但是，您可以对该存储桶暂停版本控制，这样后续上传的对象将不会产生多个版本。

Debug 模式执行命令

在各命令前加上-d或者-debug，在命令执行的过程中，会显示详细的操作信息。示例如下：

#显示 upload 的详细操作信息，命令格式：
coscmd -d upload <localpath> <cospath>

#操作示例
coscmd -d upload exampleobject exampleobject

常见问题

COSCMD 工具是否支持正则表达式？

不支持。

使用 COSCMD 工具，成功创建含有大写字符的存储桶，进行其他操作时使用大写字符报错？

COSCMD 工具会将大写字符自动转换为小写字符，存储桶名称只支持小写字母、数字、中划线及其组合，最多支持50个字符。

使用 COSCMD 工具下载根目录文件，是否支持排除某个目录？

支持。可使用 coscmd download --ignore /folder/* 方式过滤。当忽略某一类后缀时，必须最后要输入, 或者加入""。