易用性接口

优质
小牛编辑
138浏览
2023-12-01

迭代器

class oss2.BucketIterator(service, prefix='', marker='', max_keys=100, max_retries=None)[源代码]

遍历用户Bucket的迭代器。

每次迭代返回的是 SimplifiedBucketInfo 对象。

参数:
  • serviceService 对象。
  • prefix – 只列举匹配该前缀的Bucket。
  • marker – 分页符。只列举Bucket名字典序在此之后的Bucket。
  • max_keys – 每次调用 list_buckets 时的max_keys参数。注意迭代器返回的数目可能会大于该值。
class oss2.ObjectIterator(bucket, prefix='', delimiter='', marker='', max_keys=100, max_retries=None)[源代码]

遍历Bucket里文件的迭代器。

每次迭代返回的是 SimplifiedObjectInfo 对象。当 SimplifiedObjectInfo.is_prefix() 返回True时,表明是公共前缀(目录)。

参数:
  • bucketBucket 对象。
  • prefix – 只列举匹配该前缀的文件。
  • delimiter – 目录分隔符。
  • marker – 分页符。
  • max_keys – 每次调用 list_objects 时的max_keys参数。注意迭代器返回的数目可能会大于该值。
class oss2.MultipartUploadIterator(bucket, prefix='', delimiter='', key_marker='', upload_id_marker='', max_uploads=1000, max_retries=None)[源代码]

遍历Bucket里未完成的分片上传。

每次返回 MultipartUploadInfo 对象。当 MultipartUploadInfo.is_prefix() 返回True时,表明是公共前缀(目录)。

参数:
  • bucketBucket 对象。
  • prefix – 仅列举匹配该前缀的文件的分片上传。
  • delimiter – 目录分隔符。
  • key_marker – 分页符。
  • upload_id_marker – 文件名分页符。
  • max_uploads – 每次调用 list_multipart_uploads 时的max_uploads参数。注意迭代器返回的数目可能会大于该值。
class oss2.ObjectUploadIterator(bucket, key, max_uploads=1000, max_retries=None)[源代码]

遍历一个Object所有未完成的分片上传。

每次返回 MultipartUploadInfo 对象。当 MultipartUploadInfo.is_prefix() 返回True时,表明是公共前缀(目录)。

参数:
  • bucketBucket 对象。
  • key – 文件名
  • max_uploads – 每次调用 list_multipart_uploads 时的max_uploads参数。注意迭代器返回的数目可能会大于该值。
class oss2.PartIterator(bucket, key, upload_id, marker='0', max_parts=1000, max_retries=None)[源代码]

遍历一个分片上传会话中已经上传的分片。

每次返回 PartInfo 对象。

参数:
  • bucketBucket 对象。
  • key – 文件名
  • upload_id – 分片上传ID
  • marker – 分页符。
  • max_parts – 每次调用 list_parts 时的max_parts参数。注意迭代器返回的数目可能会大于该值。

断点续传(上传、下载)

oss2.resumable_upload(bucket, key, filename, store=None, headers=None, multipart_threshold=None, part_size=None, progress_callback=None, num_threads=None)[源代码]

断点上传本地文件。采用分片上传方式上传本地文件。

缺省的并发数是 oss2.defaults.multipart_num_threads ,并且在本地磁盘保存已经上传的分片信息。如果因为某种原因上传被中断,下次上传同样的文件,即源文件和目标文件路径都一样,就只会上传缺失的分片。缺省条件下,该函数会在用户 HOME 目录下保存断点续传的信息。当待上传的本地文件没有发生变化,且目标文件名没有变化时,会根据本地保存的信息,从断点开始上传。

注解

  1. 如果使用CryptoBucket,函数会退化为普通上传。
参数:
  • bucketBucket 对象。
  • key – 文件名
  • filename – 待上传本地文件名。
  • store – 用来保存断点信息的持久存储,参见 ResumableStore 的接口。如不指定,则使用 ResumableStore
  • headers – 传给 put_objectinit_multipart_upload 的HTTP头部。
  • multipart_threshold – 文件长度大于该值时,则用分片上传。
  • part_size – 指定分片上传的每个分片的大小。如不指定,则自动计算。
  • progress_callback – 上传进度回调函数。参见 上传下载进度
  • num_threads – 并发上传的线程数,如不指定则使用 oss2.defaults.multipart_num_threads
oss2.resumable_download(bucket, key, filename, multiget_threshold=None, part_size=None, progress_callback=None, num_threads=None, store=None)[源代码]

断点下载。

实现的方法是 :
  1. 在本地创建一个临时文件,文件名由原始文件名加上一个随机的后缀组成。
  2. 通过指定请求的 Range 头按照范围并发读取OSS文件,并写入到临时文件里对应的位置。
  3. 全部完成之后,把临时文件重命名为目标文件 (即 filename

在上述过程中,断点信息,即已经完成的范围,会保存在磁盘上。

因为某种原因下载中断,后续如果下载同样的文件,也就是源文件和目标文件一样,就会先读取断点信息,然后只下载缺失的部分。

缺省设置下,断点信息保存在 HOME 目录的一个子目录下。可以通过 store 参数更改保存位置。

注解

  1. 对同样的源文件、目标文件,避免多个程序(线程)同时调用该函数。因为断点信息会在磁盘上互相覆盖,或临时文件名会冲突。
  2. 避免使用太小的范围(分片),即 part_size 不宜过小,建议大于或等于 oss2.defaults.multiget_part_size
  3. 如果目标文件已经存在,那么该函数会覆盖此文件。
  4. 如果使用CryptoBucket,函数会退化为普通下载。
参数:
  • bucketBucket 对象。
  • key (str) – 待下载的远程文件名。
  • filename (str) – 本地的目标文件名。
  • multiget_threshold (int) – 文件长度大于该值时,则使用断点下载。
  • part_size (int) – 指定期望的分片大小,即每个请求获得的字节数,实际的分片大小可能有所不同。
  • progress_callback – 上传进度回调函数。参见 上传下载进度
  • num_threads – 并发下载的线程数,如不指定则使用 oss2.defaults.multiget_num_threads
  • store (ResumableDownloadStore) – 用来保存断点信息的持久存储,可以指定断点信息所在的目录。
异常:

如果OSS文件不存在,则抛出 NotFound ;也有可能抛出其他因下载文件而产生的异常。

FileObject适配器

class oss2.SizedFileAdapter(file_object, size)[源代码]

通过这个适配器(Adapter),可以把原先的 file_object 的长度限制到等于 size