下载对象

使用场景

您可以根据需要将存储在OBS中的对象下载到本地。

OBS支持批量下载对象，详情请参见OBS批量下载文件操作指导。

约束与限制

对于存储类别为归档存储或深度归档存储的对象，需要确认对象的状态为“已恢复”才能对其进行下载。
基于安全合规要求，自2023年12月30日后创建的桶，都禁止使用桶默认域名通过公网访问后缀为.apk或者.ipa的对象。通过自定义域名访问后缀为.apk或者.ipa的对象不受影响，按照工信部要求，您的自定义域名使用前须完成ICP备案。

使用方式

OBS支持通过管理控制台、API、SDK、OBS Browser+、obsutil方式下载对象。

使用OBS控制台

在OBS管理控制台左侧导航栏选择“桶列表”。
在桶列表中，单击待操作的桶，进入“对象”页面。
下载对象。
- 下载单个对象
  单击待下载对象右侧的“下载”，将对象下载至浏览器默认保存路径下。
  或单击待下载对象右侧的“更多>下载为”，在“下载为”对话框，右键单击对象名称上的下载链接，选择“链接另存为...”，将对象下载至指定路径下。
- 批量下载多个对象
  选中多个对象，单击对象列表上方的“更多>下载”。

使用API

下载对象

使用SDK

使用图形化工具OBS Browser+

登录OBS Browser+。
选中待配置的桶，选中需要下载的文件或文件夹后，单击“下载”。
OBS支持批量下载多个文件和文件夹，单击选中待下载的文件或文件夹即可。
- 对于存储类别为归档存储的桶中的文件，需要确认对象的状态为“已恢复”才能对其进行下载。请参见恢复对象查看如何恢复文件。
- 批量下载仅支持下载当前已经列举出来的文件或文件夹，可以通过下拉触底更新已列举出的文件或文件夹数量，每次触底更新100个。
在对话框中选择存放文件或文件夹的路径后，单击“选择文件夹”。

使用命令行工具obsutil

命令结构：

Windows操作系统

下载单个对象

obsutil cp obs://bucket/key file_or_folder_url [-tempFileDir=xxx] [-dryRun] [-u] [-vlength] [-vmd5] [-p=1] [-threshold=52428800] [-versionId=xxx] [-ps=auto] [-cpd=xxx][-fr] [-o=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

批量下载对象

obsutil cp obs://bucket[/key] folder_url -r [-tempFileDir=xxx] [-dryRun] [-f] [-flat] [-u] [-vlength] [-vmd5] [-j=1] [-p=1] [-threshold=52428800] [-ps=auto] [-include=*.xxx] [-exclude=*.xxx] [-timeRange=time1-time2] [-mf] [-o=xxx] [-cpd=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

macOS/Linux操作系统

下载单个对象

./obsutil cp obs://bucket/key file_or_folder_url [-tempFileDir=xxx] [-dryRun] [-u] [-vlength] [-vmd5] [-p=1] [-threshold=52428800] [-versionId=xxx] [-ps=auto] [-cpd=xxx] [-fr] [-o=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

批量下载对象

./obsutil cp obs://bucket[/key] folder_url -r [-tempFileDir=xxx] [-dryRun] [-f] [-flat] [-u] [-vlength] [-vmd5] [-j=1] [-p=1] [-threshold=52428800] [-ps=auto] [-include=*.xxx] [-exclude=*.xxx] [-timeRange=time1-time2] [-mf] [-o=xxx] [-cpd=xxx] [-config=xxx] [-e=xxx] [-i=xxx] [-k=xxx] [-t=xxx]

运行示例：

以Windows操作系统为例，运行obsutil cp obs://bucket-test/keyd:\temp\test.txt，下载单个对象。

obsutil cp obs://bucket-test/key d:\temp\test.txt
Start at 2024-09-30 08:39:34.180766 +0000 UTC

Parallel:      5                   Jobs:          5
Threshold:     50.00MB             PartSize:      auto
VerifyLength:  false               VerifyMd5:     false
CheckpointDir: xxxx
TempFileDir: xxxx

[==========================================] 100.00% 4.86 KB/s 8.46MB/8.46MB 0s
Download successfully, 8.46MB, obs://bucket-test/key --> d:\temp\test.txt, cost [41], status [200], request id [000001924215BEC84019EDF4044A5451]

以Windows操作系统为例，运行obsutil cp obs://bucket-test/temp d:\ -f -r，批量下载对象。

obsutil cp obs://bucket-test/temp d:\ -f -r
Start at 2024-09-30 08:41:56.0306522 +0000 UTC

Parallel:      5                   Jobs:          5
Threshold:     50.00MB             PartSize:      auto
VerifyLength:  false               VerifyMd5:     false
CheckpointDir: xxxx

Task id: 3066a4b0-4d21-4929-bb84-4829c32cbd0f
OutputDir: xxxx
TempFileDir: xxxx

[======================================================] 100.00% tps:17.86 155.59 KB/s 7.20MB/7.20MB 0s
Succeed count:   6         Failed count:    0
Succeed bytes:      70B
Metrics [max cost:153 ms, min cost:129 ms, average cost:92.00 ms, average tps:70, transferred size: 7.20MB]

Task id: 3066a4b0-4d21-4929-bb84-4829c32cbd0f

更多运行示例，请参见常见示例。

参数说明：

参数	约束	描述
file_or_folder_url	下载对象时必选	本地文件/文件夹路径。
folder_url	批量下载时必选	本地文件夹路径。
bucket	必选	桶名。
key	下载对象时必选批量下载时可选	待下载的对象名，或批量下载的对象名前缀。下载对象时，该值不能为空，最终保存在本地的位置及命名规则如下：如果file_or_folder_url不存在，则工具会判断其是否以“/”或“\”结尾，如果是，则会以该路径创建文件夹，将对象下载到该新建的文件夹下；如果file_or_folder_url不存在，且不以“/”或“\”结尾，则以该值作为文件名，将对象下载到本地；如果file_or_folder_url为已存在的文件，则以该值作为文件名，将对象覆盖下载到本地；如果file_or_folder_url为已存在的文件夹，则以对象名为文件名，将对象覆盖下载到file_or_folder_url指定的文件夹下。批量下载时，最终保存在本地的位置规则如下：如果该值为空，则将整个桶的内容下载到folder_url指定的文件夹下；如果该值不为空，则将桶内以该值作为对象名前缀的内容下载到folder_url指定的文件夹下。说明：批量下载且该值不为空时，如果未设置flat选项，则下载的本地文件会包含上一级父对象名前缀；如果设置了flat选项，则下载的本地文件不包含上一级父对象名前缀。请参考下载示例理解该参数的使用方式。
fr	附加参数，下载对象时可选	下载对象时生成结果清单文件。
flat	附加参数，批量下载时可选	批量下载时，不包含上一级父对象名前缀。
tempFileDir	附加参数，可选	分段下载时保存临时文件的文件夹，默认为配置文件中的defaultTempFileDir。说明：如果该值为空，且配置文件中的defaultTempFileDir也为空，则分段下载时生成的临时文件会保存在待下载文件的同目录下并以.obs.temp结尾。由于分段下载时生成的临时文件会保存在该目录，请确保运行obsutil的用户对该路径有写权限。该路径的可用空间需要大于待下载对象的大小。
dryRun	附加参数，可选	测试模式运行，不执行实际的下载操作。
u	附加参数，可选	增量下载操作，设置该参数后，下载每个对象时会对比本地对应路径的文件，仅在文件不存在，或者文件大小与对象大小不一致，或者文件的最后修改时间早于对象的最后修改时间时进行下载。
vlength	附加参数，可选	下载完成后，验证本地文件大小是否与桶中对象的大小一致。
vmd5	附加参数，可选	下载完成后，验证本地文件的MD5值是否与桶中对象的MD5值一致。说明：桶中对象必须包含元数据x-obs-meta-md5chksum，否则会忽略MD5值校验。注意：如果您的业务涉及加密场景，请勿使用该参数。
p	附加参数，可选	每个分段下载任务的最大并发数，默认为配置文件中的defaultParallels。
threshold	附加参数，可选	开启分段下载任务的阈值，单位：字节，默认为配置文件中的defaultBigfileThreshold。说明：如果待下载的对象小于该阈值，则使用直接下载模式；否则使用分段下载模式。直接下载模式不会产生断点记录文件，不支持断点续传。支持带容量单位配置，例如，配置1MB代表1048576字节。
versionId	附加参数，下载对象时可选	下载单个对象时可指定的对象版本号。
ps	附加参数，可选	每个分段下载任务的段大小，单位：字节，默认为配置文件中的defaultPartSize。说明：支持带容量单位配置，例如，配置1MB代表1048576字节。支持配置为auto，此时obsutil会根据源对象大小自动设置每个分段任务的段大小。
fs	附加参数，可选	是否使用并行文件系统的列举方式，如果桶是并行文件系统，推荐加上该参数。注意：该列举方式会因为目录结构，耗时会差别很大。该参数开启后，会忽略marker和limit值，统计桶或者并行文件系统或者指定目录的大小。 Util 5.5.12版本及以上支持该参数。
cpd	附加参数，可选	生成断点记录文件的文件夹，默认为运行obsutil命令的用户目录的子文件夹.obsutil_checkpoint。说明：每个分段下载任务会产生唯一对应的断点记录文件并保存至该文件夹的down子文件夹下，分段任务执行成功后，对应的断点记录文件会被自动删除；分段任务执行失败或被中断后，下次执行该分段任务时会尝试通过对应的断点记录文件恢复任务。
r	附加参数，批量下载时必选	按指定的对象名前缀批量下载对象。
f	附加参数，批量下载时可选	强制操作，不进行询问提示。
j	附加参数，批量下载时可选	批量下载时的最大并发数，默认为配置文件中的defaultJobs。说明：工具会保证该值至少为1。
exclude	附加参数，批量下载时可选	不包含源对象的匹配模式，如：.txt。说明：支持“”匹配多个任意字符和“?”匹配单个任意字符，例如abc.txt代表匹配以abc开头以.txt结尾的任意文件。您可以使用“\”代表匹配“”字符本身，使用“\?”代表匹配“?”字符本身。如果待下载的对象名匹配该参数，则跳过该对象的复制。须知：建议使用引号传递该匹配模式（macOS/Linux操作系统使用单引号，Windows操作系统使用双引号）防止特殊符号被操作系统转义，导致不可预期的结果。该匹配模式作用于对象全路径（含从根路径开始的对象前缀和对象名，例如，桶内对象路径为obs://bucket/src1/src2/test.txt，则对象的全路径为src1/src2/test.txt）。该匹配模式仅适用于对象名非“/”结尾的对象。支持指定多个exclude参数，如-exclude=.xxx -exclude=*.xxx
include	附加参数，批量下载时可选	include参数规定了下载对象的对象名格式，满足该格式的对象才会被下载。例如“.jpg”规定只有对象名后缀为“.jpg”的对象会被下载。说明：支持“”匹配多个任意字符和“?”匹配单个任意字符。您可以使用“\”代表匹配“”字符本身，使用“\?”代表匹配“?”字符本身。首先执行exclude的匹配规则，如果待下载的对象名不匹配exclude，则判断待下载的对象名是否匹配该参数，如果匹配则下载该对象，否则跳过该文件的下载。须知：建议使用引号传递该匹配模式（macOS/Linux操作系统使用单引号，Windows操作系统使用双引号）防止特殊符号被操作系统转义，导致不可预期的结果。该匹配模式作用于对象全路径（含从根路径开始的对象前缀和对象名，例如，桶内对象路径为obs://bucket/src1/src2/test.txt，则对象的全路径为src1/src2/test.txt）。该匹配模式仅适用于对象名非“/”结尾的对象。支持指定多个include参数，如-include=.xxx -include=.xxx
timeRange	附加参数，批量下载时可选	下载对象时的时间段匹配模式，仅下载最后修改时间在该时间段内的对象。该匹配模式优先级低于对象名匹配模式：exclude和include，优先执行对象名匹配模式后才会执行该匹配模式。说明：使用“time1-time2”，代表匹配的时间段，其中time1必须小于等于time2，格式为yyyyMMddHHmmss。时间格式支持自动补全，例如yyyyMMdd等价于yyyyMMdd000000，yyyyMM等价于yyyyMM01000000。使用“-time2”，代表匹配最后修改时间在time2之前的所有文件，使用“time1-”，代表匹配最后修改时间time1之后的所有文件。须知：该匹配模式表示的时间是UTC时间。该匹配模式仅适用于对象名非“/”结尾的对象。
mf	附加参数，可选	设置名称匹配模式（include、exclude）和时间匹配模式（timeRange）对对象名以“/”结尾的对象也生效。
o	附加参数，可选	生成结果清单文件的文件夹，命令执行完成后，会在该文件夹下生成结果清单文件（可能包含成功结果、失败结果和警告结果三个文件），默认为运行obsutil命令的用户目录的子文件夹.obsutil_output。说明：结果清单文件命名规则：cp_{succeed \| failed \| warning}_report_时间_TaskId.txt。单个结果清单文件默认情况下最大为30MB且最大可保留的文件个数为1024，可在配置文件中通过recordMaxLogSize和recordBackups分别配置。当涉及多文件/文件夹时，如需确认失败任务的具体错误信息，可参考结果清单文件夹下的失败结果清单文件“cp_failed_report_时间_TaskId.txt”和日志路径下的日志文件。
bucket-cname	附加参数，可选	指定桶绑定的自定义域名说明： Util 5.7.9版本及以上支持该参数。
config	附加参数，可选	运行当前命令时的自定义配置文件。可支持的配置参数请参考配置参数说明。
e	附加参数，可选	指定终端节点。
i	附加参数，可选	指定用户的AK。
k	附加参数，可选	指定用户的SK。
t	附加参数，可选	指定用户的securitytoken。

响应结果：

字段名	描述
Parallel	请求中的-p参数。
Jobs	请求中的-j参数。
Threshold	请求中的-threshold参数。
PartSize	请求中的-ps参数。
Exclude	请求中的-exclude参数。
Include	请求中的-include参数。
TimeRange	请求中的-timeRange参数。
VerifyLength	请求中的-vlength参数。
VerifyMd5	请求中的-vmd5参数。
CheckpointDir	请求中的-cpd参数。
OutputDir	请求中的-o参数。
ArcDir	请求中的-arcDir参数。
Succeed count	成功的任务数。
Failed count	失败的任务数。
Skip count	增量上传/下载/复制、同步上传/下载/复制跳过的任务数。说明：跳过的任务数也会记录到成功的任务数中。
Warning count	执行完成但包含警告的任务数。说明：产生警告的任务可能是失败的也可能是成功的，需要根据成功或失败的结果清单进一步判断。产生警告的任务数与成功/失败任务数是相互独立的，总任务数仍是成功的任务数+失败的任务数。
Succeed bytes	上传/下载成功的字节数。
max cost	所有任务中的最长耗时，单位：毫秒。
min cost	所有任务中的最短耗时，单位：毫秒。
average cost	平均耗时，单位：毫秒。
average tps	平均每秒的任务完成个数。
Task id	每次运行的唯一标识号，用于查找批量任务生成的结果清单文件。