add docs for new added command

tonycai653 · tonycai653 · commit dfc8a6613c79 · 2019-06-25T10:32:27.000+08:00
diff --git a/cmd/awsfetch.go b/cmd/awsfetch.go
@@ -53,10 +53,9 @@ func (lo *awslistOptions) Run(cmd *cobra.Command, positionalArgs []string) {
 
 	svc := s3.New(s3session)
 	input := &s3.ListObjectsV2Input{
-		Bucket:    aws.String(awsBucket),
-		Prefix:    aws.String(lo.prefix),
-		Delimiter: aws.String(lo.delimiter),
-		MaxKeys:   aws.Int64(lo.maxKeys),
+		Bucket:  aws.String(awsBucket),
+		Prefix:  aws.String(lo.prefix),
+		MaxKeys: aws.Int64(lo.maxKeys),
 	}
 	if lo.ctoken != "" {
 		input.ContinuationToken = aws.String(lo.ctoken)
@@ -78,6 +77,7 @@ func (lo *awslistOptions) Run(cmd *cobra.Command, positionalArgs []string) {
 				// Message from an error.
 				fmt.Fprintln(os.Stderr, err.Error())
 			}
+			fmt.Fprintln(os.Stderr, input.ContinuationToken)
 			os.Exit(1)
 		}
 		for _, obj := range result.Contents {
@@ -166,6 +166,7 @@ func (o *awsfetchOptions) Run(cmd *cobra.Command, positionalArgs []string) {
 				fmt.Fprintln(os.Stderr, err.Error())
 			}
 			close(itemc)
+			fmt.Fprintln(os.Stderr, input.ContinuationToken)
 			os.Exit(1)
 		}
 		for _, obj := range result.Contents {
diff --git a/docs/abfetch.md b/docs/abfetch.md
@@ -0,0 +1,94 @@
+# 简介
+
+`abfetch` 使用异步抓取接口抓取网络资源到七牛存储空间。
+
+参考文档：[异步抓取 (async fetch)](https://developer.qiniu.com/kodo/api/4097/asynch-fetch)
+
+# 格式
+
+```
+qshell abfetch [-i <URLList>][-b <CallbackBody>][-T <CallbackHost>][-a <CallbackUrl>][-e <FailureList>][-t <DownloadHostHeader>][-g <StorageType>][-s <SuccessList>][-c <ThreadCount>] <Bucket>
+```
+
+# 选项
+| 选项 | 说明                                                         |
+| -i   | 要抓取的资源列表， 一行一个资源                              |
+| -b   | 回调的http Body                                              |
+| -T   | 回调时的HOST 头                                              |
+| -a   | 回调的请求地址                                               |
+| -e   | 抓取失败导出的文件列表                                       |
+| -t   | 下载资源时使用的HOST头                                       |
+| -g   | 抓取的资源存储在七牛存储空间的类型， 分为低频存储， 标准存储 |
+| -s   | 抓取成功后导出到的文件                                       |
+| -c   | 抓取指定的线程数目                                                    |
+
+详细的选项介绍，请参考：[异步抓取 (async fetch)](https://developer.qiniu.com/kodo/api/4097/asynch-fetch)
+
+
+# 参数
+<Bucket> 为七牛存储空间名
+
+
+# 例子
+
+假如我有3个资源要抓取，地址分别为：
+http://test.com/test1.txt
+http://test.com/test2.txt
+http://test.com/test3.txt
+
+需要抓取这三个资源保存在七牛存储空间"test"中
+
+第一步：
+
+在当前目录下创建名为"urls.txt"的文件， 文件内容为
+
+```
+http://test.com/test1.txt
+http://test.com/test2.txt
+http://test.com/test3.txt
+```
+每行一个地址 。
+
+
+第二步:
+
+使用如下的命令就可以抓取资源到存储"test"中
+```
+$ qshell abfetch -i urls.txt test
+```
+
+
+但是这样我们不知道哪些成功了，哪些抓取失败了，可以使用选项-e 导出失败列表到文件"failure.txt"中:
+```
+$ qshell abfetch -i urls.txt -e failure.txt test
+```
+
+
+如果要提高请求的并发量， 可以使用选项-c 指定提交的线程数, 下面的命令指定线程数为100:
+```
+$ qshell abfetch -i urls.txt -e failure.txt -c 100 test
+```
+线程数只能决定请求接口后台服务器的快慢， 提交的请求会到服务器处理队列中， 如果队列中有很多要抓取的资源，抓取速度不一定会提高，所以适当设置线程数
+
+# 文件大小
+
+异步接口暂时没办法判断是否抓取成功， 当异步接口返回的数据wait是-1时，表示抓取过这个文件，这时程序会用stat接口去存储获取文件的信息，如果可以获取到，说明抓取成功了；如果wait为-1， 重试三次stat都失败，那么认为抓取失败。
+
+获取异步接口的返回结果是通过轮训进行的， 每次轮训的时间间隔取决于文件的大小， 大的文件时间间隔长点，小的文件时间间隔短点。
+因此可以在抓取的资源文件后面附上文件大小来帮助程序估算大概的时间间隔。
+
+比如要抓取的资源地址为：
+http://test.com/test1.txt
+http://test.com/test2.txt
+http://test.com/test3.txt
+
+test1.txt 大小为400字节
+test2.txt 大小为300340字节
+test3.txt 大小为22039字节
+
+假如把这些信息保存在"fetch_input.txt"文件中, 文件内容格式为：
+http://test.com/test1.txt    400
+http://test.com/test2.txt    300340
+http://test.com/test3.txt    22039
+
+程序会根据文件大小估算异步抓取的时间，时间到后，会访问异步结果获得处理结果。如果没有指定文件大小，默认会有轮训时间。
diff --git a/docs/awsfetch.md b/docs/awsfetch.md
@@ -0,0 +1,67 @@
+# 简介
+
+`awsfetch` 迁移亚马逊存储空间的数据到七牛存储空间。 该命令需要用到亚马逊账户的AccessKeyID和SecretKey, 创建访问密钥可以参考：[创建密钥](https://docs.aws.amazon.com/zh_cn/general/latest/gr/managing-aws-access-keys.html)。
+
+该命令使用了七牛的fetch接口进行抓取， 需要可以公共可以直接访问的网络资源链接， 因此在需要亚马逊存储开启公共可访问, 公共可访问开启: [文档](https://aws.amazon.com/cn/premiumsupport/knowledge-center/read-access-objects-s3-bucket/)。
+
+因为该命令使用了七牛fetch接口，对于较大的资源(大于100M), 有抓取超时的可能性。
+
+该命令首先使用亚马逊的List Objects V2接口[文档](https://docs.aws.amazon.com/AmazonS3/latest/API/v2-RESTBucketGET.html)， 获取空间中的文件， 然后七牛的fetch接口[文档](https://developer.qiniu.com/kodo/api/1263/fetch)进行抓取。
+
+# 格式
+
+```
+qshell awsfetch [-p <Prefix>][-n <maxKeys>][-m <ContinuationToken>][-c <threadCount>][-u <QiniuUpHost>] -S <AwsSecretKey> -A <AwsID> [-s <SuccessList>][-e <FailureList>] <AwsBucket> <AwsRegion> <QiniuBucket>
+```
+
+# 帮助文档
+
+可以在命令行输入如下命令获取帮助文档：
+```
+$ qshell awsfetch -h
+```
+
+# 选项
+
+| 选项 | 说明                                          | 可选 |
+| -A   | 亚马逊账户的Access Key ID                     | N    |
+| -S   | 亚马逊账户的Secret Key                        | N    |
+| -p   | 亚马逊存储空间要抓取资源的前缀                | Y    |
+| -n   | 亚马逊接口每次返回的数据条目数量              | Y    |
+| -m   | 亚马逊接口数据每次会返回的token, 用于下次列举 | Y    |
+| -c   | 抓取的线程数, 默认为20                           | Y    |
+| -u   | 抓取的资源上传到七牛存储时的上传HOST          | Y    |
+| -s   | 抓取成功的文件导出列表                        | Y    |
+| -e   | 抓取失败的文件导出列表                        | Y    |
+
+
+# 参数
+<AwsBucket> 亚马逊存储空间名称
+<AwsRegion> 亚马逊账户所在的地区
+<QiniuBucket> 七牛存储空间名称
+
+
+# 亚马逊存储数据迁移到七牛存储
+
+使用场景：
+迁移亚马逊存储空间到七牛存储空间。
+
+假如要迁移的亚马逊账户的Access Key ID, SecretKey为：
+AWS_ACCESS_KEY_ID = "12345"
+AWS_SECRET_KEY = "6789"
+
+亚马逊存储空间名为：
+AWS_BUCKET = "aws-bucket"
+
+账户所在地区为：
+AWS_REGION = "us-west-2"
+
+七牛存储空间名为：
+QINIU_BUCKET = "qiniu-bucket"
+
+导出失败的文件列表到"failure.txt"
+
+可以使用如下命令进行迁移：
+```
+$ qshell awsfetch -A 12345 -S 6789 -e failure.txt aws-bucket us-west-2 qiniu-bucket 
+```
diff --git a/docs/awslist.md b/docs/awslist.md
@@ -0,0 +1,56 @@
+# 简介
+
+`awslist` 使用亚马逊的List Objects V2接口[文档](https://docs.aws.amazon.com/AmazonS3/latest/API/v2-RESTBucketGET.html)， 获取空间中的文件， 打印到标准输出。
+
+该命令的数据格式为：
+<文件名>\t<文件大小>\t<Etag>\t<最后修改时间>
+
+当程序列举的过程中遇到错误，比如网络断开等， 会把当前的ContinuationToken打印到标准错误输出上, 可以使用shell重定向把标准输出到一个文件， 准出错误输出到另一个文件，这样可以方便地找到continuationToken继续列举。
+
+# 格式
+
+```
+qshell awslist [-p <Prefix>][-n <maxKeys>][-m <ContinuationToken>] -S <AwsSecretKey> -A <AwsID> <AwsBucket> <AwsRegion>
+```
+
+# 帮助文档
+
+可以在命令行输入如下命令获取帮助文档：
+```
+$ qshell awslist -h
+```
+
+# 选项
+
+| 选项 | 说明                                          | 可选 |
+| -A   | 亚马逊账户的Access Key ID                     | N    |
+| -S   | 亚马逊账户的Secret Key                        | N    |
+| -p   | 亚马逊存储空间要抓取资源的前缀                | Y    |
+| -n   | 亚马逊接口每次返回的数据条目数量              | Y    |
+| -m   | 亚马逊接口数据每次会返回的token, 用于下次列举 | Y    |
+
+
+# 参数
+<AwsBucket> 亚马逊存储空间名称
+<AwsRegion> 亚马逊账户所在的地区
+
+
+# 列举
+
+使用场景：
+列举亚马逊存储空间中所有的文件
+
+假如要迁移的亚马逊账户的Access Key ID, SecretKey为：
+AWS_ACCESS_KEY_ID = "12345"
+AWS_SECRET_KEY = "6789"
+
+亚马逊存储空间名为：
+AWS_BUCKET = "aws-bucket"
+
+账户所在地区为：
+AWS_REGION = "us-west-2"
+
+可以使用如下命令进行列举：
+```
+$ qshell awsfetch -A 12345 -S 6789 aws-bucket us-west-2
+```
diff --git a/docs/listbucket2.md b/docs/listbucket2.md
@@ -15,7 +15,7 @@ Key\tSize\tHash\tPutTime\tMimeType\tFileType\tEndUser
 # 格式
 
 ```
-qshell listbucket2 [--prefix <Prefix> | --suffixes <suffixes1,suffixes2>] [--start <StartDate>] [--max-retry <RetryCount>][--end <EndDate>] <Bucket> [--readable] [ [-a] -o <ListBucketResultFile>]
+qshell listbucket2 [-m|--marker <Marker>][--prefix <Prefix> | --suffixes <suffixes1,suffixes2>] [--start <StartDate>] [--max-retry <RetryCount>][--end <EndDate>] <Bucket> [--readable] [ [-a] -o <ListBucketResultFile>]
 ```
 
 # 鉴权
@@ -36,6 +36,7 @@ qshell listbucket2 [--prefix <Prefix> | --suffixes <suffixes1,suffixes2>] [--sta
 | suffixes             | 列举整个空间文件， 然后从中筛选出文件后缀为在[suffixes1, suffixes2, ...]中的文件                               | Y        |
 | a                    | 开启选项o 的append模式， 如果本地保存文件列表的文件已经存在，如果希望像该文件添加内容，使用该选项, 必须和-o选项一起使用   | Y        |
 | readable | 开启文件大小的可读性选项， 会以合适的KB, MB, GB等显示 | Y |
+|marker| Y| marker标记列举过程中的位置， 如果列举的过程中网络断开，会返回一个marker, 可以指定该marker参数继续列举|
 
 
 # 常用使用场景介绍
@@ -77,7 +78,6 @@ qshell listbucket2 [--prefix <Prefix>] <Bucket> -o <ListBucketResultFile>
  
  注意startDate 和 endDate 是这种半开半闭区间[startDate, endDate)
 
- 
  (7) 获取后缀为mp4, html的文件
  
  ```
@@ -90,6 +90,11 @@ qshell listbucket2 [--prefix <Prefix>] <Bucket> -o <ListBucketResultFile>
  qshell listbucket2 -r <Bucket>
  ```
 
+ (9) marker的使用; 假如要列举的bucket名字为"test-marker", marker为"eyJjIjowLCJrIjoiMDkzOWM1ODU4ZmI1NGZiNzk3NTJmNjVkN2U4MWY4MmVfMTUzNTM3NzI2MDMxNV8xNTM1MzgwMjYyNDYxXzgzMjgyODAzOC0wMDAwMS5tcDQifQ=", 如果要接着这个marker位置继续列举，可以使用如下命令
+ ```
+ $ qshell listbucket2 -m eyJjIjowLCJrIjoiMDkzOWM1ODU4ZmI1NGZiNzk3NTJmNjVkN2U4MWY4MmVfMTUzNTM3NzI2MDMxNV8xNTM1MzgwMjYyNDYxXzgzMjgyODAzOC0wMDAwMS5tcDQifQ= test-marker
+ ```
+
 
 # 示例
 

Original file line number	Diff line number	Diff line change
`@@ -53,10 +53,9 @@ func (lo awslistOptions) Run(cmd cobra.Command, positionalArgs []string) {`
`53`	`53`
`54`	`54`	`svc := s3.New(s3session)`
`55`	`55`	`input := &s3.ListObjectsV2Input{`
`56`		`- Bucket: aws.String(awsBucket),`
`57`		`- Prefix: aws.String(lo.prefix),`
`58`		`- Delimiter: aws.String(lo.delimiter),`
`59`		`- MaxKeys: aws.Int64(lo.maxKeys),`
	`56`	`+ Bucket: aws.String(awsBucket),`
	`57`	`+ Prefix: aws.String(lo.prefix),`
	`58`	`+ MaxKeys: aws.Int64(lo.maxKeys),`
`60`	`59`	`}`
`61`	`60`	`if lo.ctoken != "" {`
`62`	`61`	`input.ContinuationToken = aws.String(lo.ctoken)`
`@@ -78,6 +77,7 @@ func (lo awslistOptions) Run(cmd cobra.Command, positionalArgs []string) {`
`78`	`77`	`// Message from an error.`
`79`	`78`	`fmt.Fprintln(os.Stderr, err.Error())`
`80`	`79`	`}`
	`80`	`+ fmt.Fprintln(os.Stderr, input.ContinuationToken)`
`81`	`81`	`os.Exit(1)`
`82`	`82`	`}`
`83`	`83`	`for _, obj := range result.Contents {`
`@@ -166,6 +166,7 @@ func (o awsfetchOptions) Run(cmd cobra.Command, positionalArgs []string) {`
`166`	`166`	`fmt.Fprintln(os.Stderr, err.Error())`
`167`	`167`	`}`
`168`	`168`	`close(itemc)`
	`169`	`+ fmt.Fprintln(os.Stderr, input.ContinuationToken)`
`169`	`170`	`os.Exit(1)`
`170`	`171`	`}`
`171`	`172`	`for _, obj := range result.Contents {`