# 下载对象-批量下载(Python SDK) #### 功能说明 批量下载指定的对象。 #### 接口约束 - 您必须是桶拥有者或拥有下载对象的权限，才能下载对象。建议使用IAM或桶策略进行授权，如果使用IAM则需授予obs:object:GetObject权限，如果使用桶策略则需授予GetObject权限。相关授权方式介绍可参见[OBS权限控制概述](https://support.huaweicloud.com/perms-cfg-obs/obs_40_0001.html)，配置方式详见[使用IAM自定义策略](https://support.huaweicloud.com/usermanual-obs/obs_03_0121.html)、[配置对象策略](https://support.huaweicloud.com/usermanual-obs/obs_03_0075.html)。 - OBS支持的Region与Endpoint的对应关系，详细信息请参见[地区与终端节点](https://developer.huaweicloud.com/endpoint?OBS)。 - 对于存储类别为归档存储或深度归档存储的对象，需要确认对象的状态为"已恢复"才能对其进行下载。 #### 方法定义 ``` ObsClient.downloadFiles(bucketName, prefix, downloadFolder, taskNum, taskQueueSize, headers, imageProcess, interval, taskCallback, progressCallback, threshold, partSize, subTaskNum, enableCheckpoint, checkpointFile, extensionHeaders) ``` #### 请求参数 表1请求参数列表 | **参数名称** | **参数类型** | **是否必选** | **描述** | |:---|:---|:---|:---| | bucketName | str | 必选 | **参数解释** **：** 桶名。 **约束限制：** - 桶的名字需全局唯一，不能与已有的任何桶名称重复，包括其他用户创建的桶。 - 桶命名规则如下： - 3～63个字符，数字或字母开头，支持小写字母、数字、"-"、"."。 - 禁止使用IP地址。 - 禁止以"-"或"."开头及结尾。 - 禁止两个"."相邻（如："my..bucket"）。 - 禁止"."和"-"相邻（如："my-.bucket"和"my.-bucket"）。 - 同一用户在同一个区域多次创建同名桶不会报错，创建的桶属性以第一次请求为准。 **默认取值：** 无 | | prefix | str | 必选 | **参数解释** **：** 批量下载对象前缀。 例如，假设您下载以下对象：logs/day1、logs/day2、logs/day3和ExampleObject.jpg。如果您将logs/指定为前缀，将下载以字符串"logs/"开头的三个对象。如果您指定空的前缀且请求中没有其他过滤条件，将返回桶中的所有对象。 **取值范围：** 长度大于0且不超过1024的字符串。 **默认取值：** 无 | | downloadFolder | str | 必选 | **参数解释** **：** 批量下载对象的本地文件夹全路径。 **默认取值：** 无 | | taskNum | int | 可选 | **参数解释：** 下载时的最大并发数。 **取值范围：** 1\~10000 **默认取值：** 8 | | taskQueueSize | int | 可选 | **参数解释：** 批量下载时的任务队列大小 **取值范围：** **默认取值：** 20000 | | headers | [GetObjectHeader] | 可选 | **参数解释：** 下载对象的头域，用于获取对象的基本信息，包括存储类别、冗余策略等。 **取值范围：** 参考[GetObjectHeader]。 **默认取值：** 无 | | imageProcess | str | 可选 | **参数解释：** 图片处理参数，描述针对对象的图片处理命令或处理样式。例如如果想表示对图片依次进行缩放、旋转，取值：image/resize,m_fixed,w_100,h_100/rotate,90。 **取值范围：** 命令方式：image/命令参数 样式方式：style/样式名称 详细参数说明参见[处理图片](https://support.huaweicloud.com/usermanual-obs/obs_01_0224.html)。 **默认取值：** 如果不输入处理命令，将返回原图。 | | interval | int | 可选 | **参数解释：** 字节间隔。 **取值范围：** **默认取值：** 102400 | | taskCallback | callable | 可选 | **参数解释：** 任务回调函数。 **默认取值：** 无 | | progressCallback | callable | 可选 | **参数解释：** 获取下载进度的回调函数。 **默认取值：** 无 说明： 该回调函数依次包含三个参数：已下载的字节数、总字节数、已使用的时间（单位：秒），示例代码参考[下载对象-获取下载进度](https://support.huaweicloud.com/sdk-python-devg-obs/obs_22_0913.html)。 | | threshold | int | 可选 | **参数解释：** 批量下载阈值。 **默认取值：** 5 \* 1024 \* 1024 \* 1024。 | | partSize | int | 可选 | **参数解释：** 分段大小。 **取值范围：** 取值范围是100KB\~5GB，单位字节。 **默认取值：** 5MB。 | | subTaskNum | int | 可选 | **参数解释：** 批量下载时断点续传的并发任务数。 **取值范围：** 1\~10000。 **默认取值：** 1，即不设置则默认串行下载。 | | enableCheckpoint | bool | 可选 | **参数解释：** 是否开启断点续传模式。 **取值范围：** True：开启断点续传模式。 False：关闭断点续传模式。 **默认取值：** False：关闭断点续传模式。 | | checkpointFile | str | 可选 | **参数解释：** 记录下载进度的文件，只在断点续传模式下有效。 **默认取值：** 当该值为空时，默认与下载对象的本地文件路径同目录。 | | extensionHeaders | dict | 可选 | **参数解释：** 接口的拓展头域。 **取值范围：** 参考[自定义头域](https://support.huaweicloud.com/sdk-python-devg-obs/obs_22_1305.html)。 **默认取值：** 无 | 表2GetObjectHeader | **参数名称** | **参数类型** | **是否必选** | **描述** | |:---|:---|:---|:---| | range | str | 可选 | **参数解释：** 指定下载的范围。 **取值范围：** 取值区间：\[0，对象长度-1\]，格式：x-y。 **约束限制：** 如果range的最大长度超出对象长度-1，仍旧取对象长度-1。 **默认取值：** 无 | | if_match | str | 可选 | **参数解释：** 指定一个预设的Etag值，如果下载对象的ETag值与该参数值相同，则返回对象内容，否则返回错误。 **取值范围：** 长度为32的字符串。 **默认取值：** 无 | | if_none_match | str | 可选 | **参数解释：** 指定一个预设的Etag值，如果下载对象的ETag值与该参数值不相同，则返回对象内容，否则返回错误。 **取值范围：** 长度为32的字符串。 **默认取值：** 无 | | if_modified_since | str 或 [DateTime] | 可选 | **参数解释：** 如果对象在指定的时间后有修改，则返回对象内容，否则返回错误。 **约束限制：** 可以使用[DateTime]生成日期； 代码示例：DateTime(year=2023, month=9, day=12)。 **默认取值：** 无 | | if_unmodified_since | str 或 [DateTime] | 可选 | **参数解释：** 如果对象在指定的时间后没有修改，则返回对象内容，否则返回错误。 **约束限制：** 可以使用[DateTime]生成日期； 代码示例：DateTime(year=2023, month=9, day=12)。 **默认取值：** 无 | | origin | str | 可选 | **参数解释：** 预请求指定的跨域请求Origin（通常为域名）。 **约束限制：** 每个匹配规则允许使用最多一个"\*"通配符。 **默认取值：** 无 | | requestHeaders | str | 可选 | **参数解释：** 跨域请求可以使用的HTTP头域。只有匹配上允许的头域中的配置，才被视为是合法的CORS请求。 **约束限制：** 每个头域可填写一个"\*"通配符，不支持\&、:、\<、空格以及中文字符。 **默认取值：** 无 | | sseHeader | [SseCHeader] | 可选 | **参数解释：** 服务端解密头信息，详见[SseCHeader]。 **约束限制：** 如果客户端的对象上传时，使用了客户提供的加密密钥进行服务端加密，当下载对象时，同样也必须在消息中提供密钥 **默认取值：** 无 | 表3DateTime | **参数名称** | **参数类型** | **描述** | |:---|:---|:---| | year | int | **参数解释：** UTC时间中的年。 **默认取值：** 无 | | month | int | **参数解释：** UTC时间中的月。 **默认取值：** 无 | | day | int | **参数解释：** UTC时间中的日。 **默认取值：** 无 | | hour | int | **参数解释：** UTC时间中的小时。 **约束限制：** 24小时制。 **默认取值：** 0 | | min | int | **参数解释：** UTC时间中的分钟。 **默认取值：** 0 | | sec | int | **参数解释：** UTC时间中的秒数。 **默认取值：** 0 | 表4SseCHeader | **参数名称** | **参数类型** | **是否必选** | **描述** | |:---|:---|:---|:---| | encryption | str | 必选 | **参数解释：** 以SSE-C方式加密对象。 **取值范围：** AES256，即高级加密标准（Advanced Encryption Standard，AES）。 **默认取值：** 无 | | key | str | 必选 | **参数解释：** SSE-C方式下加密的密钥，与加密方式对应，如encryption='AES256'，密钥就是由AES256加密算法得到的密钥。 **取值范围：** 长度为32字符串。 **默认取值：** 无 | #### 返回结果 表5返回结果 | **类型** | **说明** | |:---|:---| | [GetResult] | **参数解释：** 批量下载接口结果对象。 **取值范围：** 不涉及 | 表6GetResult | **参数名称** | **参数类型** | **描述** | |:---|:---|:---| | total_tasks | int | **参数解释：** 任务总数。 **取值范围：** 不涉及 | | successful_tasks | int | **参数解释：** 成功任务数。 **取值范围：** 不涉及 | | failed_tasks | int | **参数解释：** 失败任务数。 **取值范围：** 不涉及 | #### 代码样例 ``` try: resp = obs_client.downloadFiles(bucket_name='bucketname', prefix='object_key', downloadFolder='localFolder') result = "DownloadFiles summary : total_task:%d, success:%d ,failure:%d" % (resp.total_tasks, resp.successful_tasks, resp.failed_tasks) print(result) except Exception: import traceback print(traceback.format_exc()) ``` #### 相关链接 - 关于下载对象的API说明，请参见[获取对象内容](https://support.huaweicloud.com/api-obs/obs_04_0083.html)。 - 更多关于下载对象的示例代码，请参见[Github示例](https://github.com/huaweicloud/huaweicloud-sdk-python-obs/blob/master/examples/object_operations_sample.py)。 - 下载对象过程中返回的错误码含义、问题原因及处理措施可参考[OBS错误码](https://support.huaweicloud.com/api-obs/obs_04_0115.html#section1)。 - 下载对象常见问题请参见[下载对象失败](https://support.huaweicloud.com/obs_faq/obs_faq_0135.html)。