下载对象（cp）--对象存储-火山引擎

文档中心

立即注册

导航

对象存储

下载对象（cp）

最近更新时间：2024.08.16 15:40:52首次发布时间：2022.11.03 10:30:29

您可以使用 cp 命令下载存储桶中的对象。

命令语法

Linux/macOS

Windows

下载单个对象

./tosutil cp tos://bucket/key file_url|folder_url [-dryRun] [-tempFileDir=xxx] [-u] [-vchecksum] [-p=1] [-threshold=104857600] [-ps=auto] [-cpd=xxx] [-versionId=xxx] [-fr] [-o=xxx] [-e=xxx] [-re=xxx] [-i=xxx] [-k=xxx] [-t=xxx] [-conf=xxx]

批量下载对象

./tosutil cp tos://bucket[/prefix] folder_url -r [-dryRun] [-tempFileDir=xxx] [-u] [-vchecksum] [-flat] [-j=1] [-p=1] [-threshold=104857600] [-nfj=1] [-ps=auto] [-cpd=xxx] [-include=*.xxx] [-exclude=*.xxx] [-timeRange=time1-time2] [-dmf] [-o=xxx] [-e=xxx] [-re=xxx] [-i=xxx] [-k=xxx] [-t=xxx] [-conf=xxx]

下载单个对象

tosutil cp tos://bucket/key file_url|folder_url [-dryRun] [-tempFileDir=xxx] [-u] [-vchecksum] [-p=1] [-threshold=104857600] [-ps=auto] [-cpd=xxx] [-versionId=xxx] [-fr] [-o=xxx] [-e=xxx] [-re=xxx] [-i=xxx] [-k=xxx] [-t=xxx] [-conf=xxx]

批量下载对象

tosutil cp tos://bucket[/prefix] folder_url -r [-dryRun] [-tempFileDir=xxx] [-u] [-vchecksum] [-flat] [-j=1] [-p=1] [-threshold=104857600] [-nfj=1] [-ps=auto] [-cpd=xxx] [-include=*.xxx] [-exclude=*.xxx] [-timeRange=time1-time2] [-dmf] [-o=xxx] [-e=xxx] [-re=xxx] [-i=xxx] [-k=xxx] [-t=xxx] [-conf=xxx]

性能优化建议

tosutil 支持通过 -j 及 -p 参数调整并发数。当您批量上传大文件时，实际并发数为 -j 乘以 -p 参数。调整建议如下：

资源不充足场景
当网络、内存等资源不充足的场景下，建议您不要设置过高的并发数，避免因资源占满导致的性能下降或失败等问题。您可以根据实际资源情况，先设置一个较低的并发数，然后逐渐增大参数，直至调整至一个较优的设置。
提升整体执行的 QPS 和带宽
- 上传、下载、拷贝小文件：需要设置较高的并发数提升 QPS。
- 上传、下载、拷贝大文件：避免并发数过高导致带宽抢占造成性能衰减。
  您可以通过 -nfj 参数和 -j 参数分别控制非分片任务和分片任务的并发数。例如设置 -j=100，-nfj=80，表示总并发数为 100，当执行非分片任务（一般是小文件）时，最大的并发数为 80；当执行分片任务（一般是大文件）时，最大的并发数为 20。
公网运行场景
由于公网网络不稳定以及客户端带宽较低等因素，容易导致上传缓慢且失败等问题，您可以参考以下建议调整参数：
- 调大配置文件中的 maxRetryCount 参数，通过不断重试错误解决公网网络不稳定的问题。
- 如果客户端带宽有限，您需要合理减少 -j 和 -p 参数，避免因并发过高导致客户端超带宽，进而出现断流失败等情况。
- 合理调整 -ps 参数，降低分片大小，有利于提高单个分片上传/下载/复制的成功率。

注意

在海量小文件场景中，如果您设置了较高的 -j，导致 TPS 超过 1000，您需要同步上调 maxConnections 参数，更多信息，请参见配置文件说明。

参数说明

通用可选参数的说明，请参见通用可选参数。

参数名	参数类型	描述
file_url	String	需要下载的对象的路径。
folder_url	String	下载到本地的文件夹路径。
bucket	String	桶名。
key	String	对象名。
prefix	String	批量操作时的对象名前缀。
-r	Bool	执行批量上传、下载或复制操作。
-dryRun	Bool	测试模式运行，不执行实际的上传、下载或复制操作。
-tempFileDir	String	分片下载时保存临时文件的文件夹，默认为配置文件中的 `defaultTempFileDir`。说明如果该值为空，且配置文件中的 `defaultTempFileDir` 也为空，则分片下载时生成的临时文件会保存在待下载文件的同目录下并以 `.tos.temp` 结尾。由于下载时生成的临时文件会保存在该目录，请确保运行 tosutil 的用户对该路径有写权限。该路径的可用空间需要大于待下载对象的大小。
-recover	String	待恢复上传、下载或复制对象任务的结果清单文件任务 ID。
-u	Bool	增量上传、下载或复制对象，设置该参数后，会比较源端和目标端的数据，建议您在以下场景使用该参数：目标端不存在。目标端与源端的文件大小不一致。目标端的最后修改时间早于源端端的最后修改时间时执行对应的操作。
-vchecksum	Bool	上传或下载对象时通过 CRC64 算法验证数据一致性。
-flat	Bool	上传、下载或复制对象时不包含相对父目录。
-j	Integer	批量任务的最大并发数，`-j=1` 表示批量任务的最大并发数为 1。默认为配置文件中的 `defaultJobs`，默认值为 3。
-p	Integer	每个分片任务的最大并发数，`-p=1` 表示分片任务的最大并发数为 1 。默认为配置文件中的 `defaultParallels`，默认值为 1。
-threshold	Integer	开启分片任务的阈值，单位：字节，默认为配置文件中的 `defaultBigfileThreshold`。说明支持带容量单位配置，例如，配置 1MB 代表 1048576 字节。
-nfj	Integer	批量任务的处理普通文件或对象（非分片任务）的最大并发数。当设置该参数后，`-j` 参数设置的并发数会分为两部分，普通文件的并发数为 `nfj`，分片任务的并发数为 `j-nfj`。仅在批量操作时生效。
-ps	Integer/String	每个分片任务的段大小，单位：字节，默认为配置文件中的 `defaultPartSize`。说明支持带容量单位配置，例如，配置 1MB 代表 1048576 字节。
-cpd	String	生成断点记录文件的文件夹，默认为配置文件中的 `defaultCheckpointDir`。
-versionId	String	下载或复制单个对象的版本号。
-include	String	上传、下载或复制时对包含文件的名称匹配模式，支持以下字符： `?` ：匹配单个任意字符。 `` ：匹配多个任意字符。 `#` ：作为分隔符。例如 `-include=.png#*.txt` 表示匹配所有以 `.png` 和 `.txt` 结尾的文件。说明为了避免因操作系统转义特殊符号的导致的解析失败等问题，建议您使用引号设置名称匹配模式。名称匹配模式只在上传文件夹或文件列表时生效。名称匹配模式在文件全路径生效（包含文件名和文件目录）。
-exclude	String	上传、下载或复制时对不包含文件的名称匹配模式，支持以下字符： `?` ：匹配单个任意字符。 `` ：匹配多个任意字符。 `#` ：作为分隔符。例如 `-exclude=.png#*.txt` 表示匹配所有以 `.png` 和 `.txt` 结尾的文件。说明为了避免因操作系统转义特殊符号导致的解析失败等问题，建议您使用引号设置名称匹配模式。名称匹配模式只在上传文件夹或文件列表时生效。名称匹配模式在文件全路径生效（包含文件名和文件目录）。
-timeRange	String	上传、下载或复制时文件最后修改时间的时间段匹配模式，格式为：`YYYYMMDDHHmmSS-YYYYMMDDHHmmSS`。
-dmf	Bool	设置名称匹配模式 `-include/-exclude` 和时间段匹配模式 `-timeRange` 对文件夹不生效。
-marker	String	批量下载时指定对象的开始位置。
-fr	Bool	操作单个对象时生成结果清单文件。
-o	String	生成结果清单文件的文件夹，默认为配置文件中的 `defaultOutputDir`。

使用示例

下载单个对象

以下命令用于将 bucketname 存储桶内的 object1.png 对象，下载至 /Users/Downloads/TOS/tosutil 文件夹。

命令

./tosutil cp tos://bucketname/object1.png /Users/Downloads/TOS/tosutil

Start at 2022-10-27 10:56:20.611282 +0000 UTC
 
 
Parallel:      1                   Jobs:          5                   
Threshold:     100.00MB            PartSize:      auto                
VerifyChecksum: false                         
CheckpointDir: /.tosutil_checkpoint
TempFileDir:               
 
[-------------------------------------------] 100.00% ?/s 55.98KB/55.98KB 106ms
 
Download successfully, 55.98KB, n/a, tos://bucketname/object1.png --> /Downloads/TOS/tosutil/object1.png, cost [106], status [200], request id [5c81485a63d4b1d7635a63d4-ac17b21f-1oo0Ye-GO-cb-tos-bj]

批量下载对象

以下命令用于将 bucketname 存储桶内的前缀为 object 的对象，下载至 /Users/Downloads/TOS/tosutil 文件夹。

命令

./tosutil cp tos://bucketname/object /Users/Downloads/TOS/tosutil -r

Start at 2022-10-27 10:56:35.434563 +0000 UTC
 
 
Parallel:      1                   Jobs:          5                   
Threshold:     100.00MB            PartSize:      auto                
VerifyChecksum: false                         
CheckpointDir: /Users/.tosutil_checkpoint
OutputDir: /Users/.tosutil_output
TempFileDir:               
 
[----------------------] 100.00% tps:51.09 3.02MB/s 4/4 238.21KB/238.21KB 278ms
Succeed count is:   4         Failed count is:    0         
Succeed bytes is:   238.21KB  
Metrics [max cost:216 ms, min cost:163 ms, average cost:191.50 ms, average tps:14.23]
 
Task id is: 0653482e-55e6-11ed-afb8-aa665a3c7f26

说明

更多下载场景的示例命令，请参见下载示例。