开发者中心 开发者资源 开发者工具 qshell 命令行工具
qshell 命令行工具

简介

qshell 是基于七牛 API 参考手册实现的一个方便开发者测试和使用七牛 API 服务的命令行工具。

下载

该工具使用Go语言编写而成,当然为了方便不熟悉Go或者急于使用工具来解决问题的开发者,我们提供了预先编译好的各主流操作系统平台的二进制文件供大家下载使用,由于平台的多样性,我们把这些二进制打包放到一个文件里面,请大家根据下面的说明各自选择合适的版本来使用。在文档中的例子里面,为了方便,我们统一使用qshell这个命令来做介绍。

版本 支持平台 链接 更新日志
qshell v2.0.0 Linux (32, 64位,arm平台), Windows(32, 64位), Mac OSX(32, 64位) 下载 查看

因为上面发布的 zip 包里面有支持不同平台的可执行文件,请根据系统平台选择合适的可执行文件,然后其他的都可以删除,再把可执行文件重命名为 qshell。注意:Windows 系统用户不要更改扩展名。

另外,由于本工具是一个命令行工具,在 Windows 下请先打开命令行终端,然后输入工具名称执行,不要双击打开。如果您希望可以在任意目录下使用 qshell,请将 qshell 工具可执行文件所在目录添加到系统的环境变量中。关于如何将可执行文件所在目录添加到系统环境变量中的方法请参阅这里

安装

该工具由于是命令行工具,所以只需要从上面的下载链接下载zip包之后解压即可使用。其中文件名和对应系统关系如下:

文件名 描述
qshell_linux_386 Linux 32位系统
qshell_linux_amd64 Linux 64位系统
qshell_linux_arm Linux ARM CPU
qshell_windows_386.exe Windows 32位系统
qshell_windows_amd64.exe Windows 64位系统
qshell_darwin_386 Mac 32位系统,这种系统很老了
qshell_darwin_amd64 Mac 64位系统,主流的系统

Linux和Mac平台

(1)权限 如果在Linux或者Mac系统上遇到Permission Denied的错误,请使用命令chmod +x qshell来为文件添加可执行权限。这里的qshell是上面文件重命名之后的简写。

(2)任何位置运行 对于Linux或者Mac,如果希望能够在任何位置都可以执行,那么可以把qshell所在的目录加入到环境变量$PATH中去。假设qshell命令被解压到路径/home/jemy/tools目录下面,那么我们可以把如下的命令写入到你所使用的bash所对应的配置文件中,如果是/bin/bash,那么就是~/.bashrc文件,如果是/bin/zsh,那么就是~/.zshrc文件中。写入的内容为:

export PATH=$PATH:/home/jemy/tools

保存完毕之后,可以通过两种方式立即生效,其一为输入source ~/.zshrc或者source ~/.bashrc来使配置立即生效,或者完全关闭命令行,然后重新打开一个即可,接下来就可以在任何位置使用qshell命令了。

Windows平台

(1)闪退问题 本工具是一个命令行工具,在Windows下面请先打开命令行终端,然后输入工具名称执行,不要双击打开,否则会出现闪退现象。

(2)任何位置运行 如果你希望可以在任意目录下使用qshell,请将qshell工具可执行文件所在目录添加到系统的环境变量中。由于Windows系统是图形界面,所以方便一点。假设qshell.exe命令被解压到路径E:\jemy\tools目录下面,那么我们把这个目录放到系统的环境变量PATH里面。

windows-qshell-path-settings.png

使用

该工具有两类命令,其中的一类命令需要指定配置文件,所有的参数信息都写在配置文件里面,比如 qdownloadqupload 。还有一类命令的运行需要依赖七牛账号下的 AccessKeySecretKey ,以及空间所在的机房。所以这类命令运行之前,需要使用 account 命令来设置下 AccessKeySecretKey 和默认机房编号 Zone

这里需要额外指出的是,为了支持多账号的情况(这种情况很常见,有很多公司有测试账号和线上账号,它们的 AccessKeySecretKey 都不同),我们把 account 设置的参数以及其他命令过程中所产生的临时文件(比如 qupload 会保存已上传文件列表)都存放在 qshell 命令所运行的目录。举个例子,我们有两个目录,一个是测试账号的,一个是线上账号的,分别如下:

/home/jemy/tools/qshell_dev/
/home/jemy/tools/qshell_prod/

由于上面的特点,我们每次要使用相应账号运行命令的时候,都需要切换到指定的目录下,比如:

$ cd /home/jemy/tools/qshell_dev/
$ qshell fput bucket-test test1.png /home/jemy/images/test1.png

如果你想看看在命令运行的目录到底保存了哪些文件,除了阅读后面详细的文档外,也可以使用命令tree -a查看下。

.
├── .qshell
│   ├── account.json
│   └── qupload
│       └── 8bbcb28795215eff7e9362bdd7949b71
│           ├── 8bbcb28795215eff7e9362bdd7949b71.cache
│           ├── 8bbcb28795215eff7e9362bdd7949b71.count
│           └── 8bbcb28795215eff7e9362bdd7949b71.ldb
│               ├── 000001.log
│               ├── CURRENT
│               ├── LOCK
│               ├── LOG
│               └── MANIFEST-000000

命令选项

该工具还有一些有用的选项参数如下:

参数 描述
-f 设置命令行的交互模式,如果指定这个选项,那么为不交互,这个命令主要用在batch操作的命令里面,因为batch操作具有一定危险性,比如batchdelete批量删除,这个时候会要求输入一个验证码,如果遇到把qshell写到shell脚本里面,不想有验证码这一步的情况,可以指定这个选项
-d 设置是否输出DEBUG日志,如果指定这个选项,则输出DEBUG级别的日志
-h 打印命令列表帮助信息,遇到参数忘记的情况下,可以使用该命令
-v 打印工具版本,反馈问题的时候,请提前告知工具对应版本号

多机房支持

七牛目前上线了华北,华东,华南和北美机房,qshell可以同时支持这几个机房的操作,这个是通过account命令或者zone命令中指定的机房编码来支持的。另外对于quploadqdownload,可以在配置文件里面添加选项zone来指定空间所在的机房,一旦指定机房之后,工具会自动判定所需要的域名入口信息。目前机房的编码如下:

机房 zone值
华东 nb
华北 bc
华南 hn
北美 na0

比如通过:

$ qshell account ak sk nb 
指定账号默认机房为华东机房

$ qshell zone bc
同一个账号下可能有多个机房的空间,每次都用account比较麻烦,可以用zone命令来切换机房

使用方法

注意:Windows 系统用户在 开始 菜单栏选择 运行 输入 cmd 回车即可打开 DOS 命令行窗口,然后切换到 qshell.exe 的所在磁盘路径。假设您的 qshell.exe 存放在 D:\tools\qshell.exe ,那么如下几行命令可以切换到 qshell.exe 存放的目录:

> D:
> cd tools

如图:

image

调用七牛的 API 需要一对 AccessKey 和 SecretKey,AccessKey 和 SecretKey 需要在七牛开发者平台上申请。步骤如下:

  1. 开通七牛开发者帐号
  2. 登录七牛开发者平台,查看 Access Key Secret Key

首先要使用七牛的 API,必须先设置 AccessKey 和 SecretKey 。命令如下:

qshell account ELUs327kxVPJrGCXqWae9yioc0xYZyrIpbM6Wh6o LVzZY2SqOQ_I_kM1n00ygACVBArDvOWtiLkDtKi_

上面的 ELUs327kxVPJrGCXqWae9yioc0xYZyrIpbM6Wh6o 是您的 AccessKey,而 LVzZY2SqOQ_I_kM1n00ygACVBArDvOWtiLkDtKi_ 是您的 SecretKey。如果您想查看当前 AccessKey 和 SecretKey 设置,使用命令:

qshell account

上面的命令会输出当前您设置好的 AccessKey 和 SecretKey。接下来,我们就可以放心地使用七牛的 API 功能了。

命令列表

命令 描述 详细
account 设置或显示当前用户的 AccessKey 和 SecretKey 文档
dircache 输出本地指定路径下所有的文件列表 文档
listbucket 列举七牛空间里面的所有文件 文档
prefop 查询七牛数据处理的结果 文档
fput 以文件表单的方式上传一个文件 文档
rput 以分片上传的方式上传一个文件 文档
qupload 同步数据到七牛空间,带同步进度信息和数据上传完整性检查 文档
qdownload 从七牛空间同步数据到本地,只支持同步某些前缀的文件和增量同步 文档
stat 查询七牛空间中一个文件的基本信息 文档
delete 删除七牛空间中的一个文件 文档
move 移动或重命名七牛空间中的一个文件 文档
copy 复制七牛空间中的一个文件 文档
chgm 修改七牛空间中文件的 MimeType 文档
fetch 从 Internet 上抓取一个资源到七牛空间中 文档
prefetch 更新七牛空间中从源站镜像过来的文件 文档
batchdelete 批量删除七牛空间中的文件,可以直接根据 listbucket 的结果来删除 文档
batchchgm 批量修改七牛空间中文件的 MimeType 文档
batchcopy 批量复制七牛空间中的文件到另一个空间 文档
batchmove 批量移动七牛空间中的文件到另一个空间 文档
batchrename 批量重命名七牛空间中的文件 文档
checkqrsync 检查 qrsync 的同步结果,主要通过比对 dircache 和 listbucket 的结果 文档
b64encode base64 编码工具,可选是否使用 UrlSafe 方式,默认 UrlSafe 文档
b64decode base64 解码工具,可选是否使用 UrlSafe 方式,默认 UrlSafe 文档
urlencode url 编码工具 文档
urldecode url 解码工具 文档
ts2d 将 timestamp(单位秒)转为 UTC+8:00 中国日期,主要用来检查上传策略的 deadline 参数 文档
tms2d 将 timestamp(单位毫秒)转为 UTC+8:00 中国日期 文档
tns2d 将 timestamp(单位 100 纳秒)转为 UTC+8:00 中国日期 文档
d2ts 将日期转为 timestamp(单位秒) 文档
ip 根据淘宝的公开 API 查询 ip 地址的地理位置 文档
qetag 根据七牛的 qetag 算法来计算文件的 hash 文档
unzip 解压 zip 文件,支持 UTF-8 编码和 GBK 编码 文档
privateurl 生成私有空间资源的访问外链 文档
saveas 实时处理的 saveas 链接快捷生成工具 文档
reqid 七牛自定义头部 X-Reqid 解码工具 文档
m3u8delete 根据流媒体播放列表文件删除七牛空间中的流媒体切片 文档
buckets 获取当前账号下所有的空间名称 文档
domains 获取指定空间的所有关联域名 文档
qetag 根据七牛的qetag算法来计算文件的hash 文档
m3u8delete 根据流媒体播放列表文件删除七牛空间中的流媒体切片 文档
m3u8replace 修改流媒体播放列表文件中的切片引用域名 文档
cdnrefresh 批量刷新cdn的访问外链 文档
cdnprefetch 批量预取cdn的访问外链 文档
b64encode base64编码工具,可选是否使用UrlSafe方式,默认UrlSafe 文档
b64decode base64解码工具,可选是否使用UrlSafe方式,默认UrlSafe 文档
urlencode url编码工具 文档
urldecode url解码工具 文档
ts2d 将timestamp(单位秒)转为UTC+8:00中国日期,主要用来检查上传策略的deadline参数 文档
tms2d 将timestamp(单位毫秒)转为UTC+8:00中国日期 文档
tns2d 将timestamp(单位100纳秒)转为UTC+8:00中国日期 文档
d2ts 将日期转为timestamp(单位秒) 文档
ip 根据淘宝的公开API查询ip地址的地理位置 文档
unzip 解压zip文件,支持UTF-8编码和GBK编码 文档
alilistbucket 列举阿里OSS空间里面的所有文件 文档

编译

问题反馈

如果您有任何问题,请写在ISSUE列表里面,我们会尽快回复您。

提交工单