API文档

基础类

class oss2.Auth(access_key_id, access_key_secret)[源代码]

签名版本1，用于保存用户AccessKeyId、AccessKeySecret，以及计算签名的对象。

class oss2.AnonymousAuth[源代码]

用于匿名访问。

注解

匿名用户只能读取public-read的Bucket，或只能读取、写入public-read-write的Bucket。不能进行Service、Bucket相关的操作，也不能罗列文件等。

class oss2.StsAuth(access_key_id, access_key_secret, security_token, auth_version='v1')[源代码]

用于STS临时凭证访问。可以通过官方STS客户端获得临时密钥（AccessKeyId、AccessKeySecret）以及临时安全令牌（SecurityToken）

注解

临时凭证会在一段时间后过期，在此之前需要重新获取临时凭证，并更新 Bucket 的 auth 成员变量为新的 StsAuth 实例。

参数:
  • access_key_id (str) – 临时AccessKeyId
  • access_key_secret (str) – 临时AccessKeySecret
  • security_token (str) – 临时安全令牌(SecurityToken)
  • auth_version (str) – 需要生成auth的版本，默认为AUTH_VERSION_1(v1)
class oss2.Bucket(auth, endpoint, bucket_name, is_cname=False, session=None, connect_timeout=None, app_name='', enable_crc=True)[源代码]

用于Bucket和Object操作的类，诸如创建、删除Bucket，上传、下载Object等。

用法（假设Bucket属于杭州区域）:
>>> import oss2
>>> auth = oss2.Auth('your-access-key-id', 'your-access-key-secret')
>>> bucket = oss2.Bucket(auth, 'http://oss-cn-hangzhou.aliyuncs.com', 'your-bucket')
>>> bucket.put_object('readme.txt', 'content of the object')
<oss2.models.PutObjectResult object at 0x029B9930>
参数:
  • auth (oss2.Auth) – 包含了用户认证信息的Auth对象
  • endpoint (str) – 访问域名或者CNAME
  • bucket_name (str) – Bucket名
  • is_cname (bool) – 如果endpoint是CNAME则设为True；反之，则为False。
  • session (oss2.Session) – 会话。如果是None表示新开会话，非None则复用传入的会话。
  • connect_timeout (float) – 连接超时时间，以秒为单位。
  • app_name (str) – 应用名。该参数不为空，则在User Agent中加入其值。注意到，最终这个字符串是要作为HTTP Header的值传输的，所以必须要遵循HTTP标准。
class oss2.Service(auth, endpoint, session=None, connect_timeout=None, app_name='')[源代码]

用于Service操作的类，如罗列用户所有的Bucket。

用法:
>>> import oss2
>>> auth = oss2.Auth('your-access-key-id', 'your-access-key-secret')
>>> service = oss2.Service(auth, 'oss-cn-hangzhou.aliyuncs.com')
>>> service.list_buckets()
<oss2.models.ListBucketsResult object at 0x0299FAB0>
参数:
  • auth (oss2.Auth) – 包含了用户认证信息的Auth对象。
  • endpoint (str) – 访问域名，如杭州区域的域名为 ‘oss-cn-hangzhou.aliyuncs.com’ 。
  • session (oss2.Session) – 会话。如果是None表示新开会话，非None则复用传入的会话。
  • connect_timeout (float) – 连接超时时间，以秒为单位。
  • app_name (str) – 应用名。该参数不为空，则在User Agent中加入其值。注意到，最终这个字符串是要作为HTTP Header的值传输的，所以必须要遵循HTTP标准。
class oss2.Session[源代码]

属于同一个Session的请求共享一组连接池，如有可能也会重用HTTP连接。

输入、输出和异常说明

文件上传方法中的data参数

诸如 put_object 这样的上传接口都会有 data 参数用于接收用户数据。 data 可以是下述类型：
  • unicode类型（对于Python3则是str类型）：内部会自动转换为UTF-8的bytes。
  • bytes类型：不做任何转换。
  • file-like object：对于可以seek和tell的file object，从当前位置读取直到结束。其他类型，请确保当前位置是文件开始。
  • 可迭代类型：对于无法探知长度的数据，要求一定是可迭代的。此时会通过Chunked Encoding传输。

Bucket配置修改方法中的input参数。

诸如 put_bucket_cors 这样的Bucket配置修改接口都会有 input 参数接收用户提供的配置数据。他可以是如下类型：
  • Bucket配置信息相关的类，如 BucketCors 。
  • unicode类型（对于Python3则是str类型）
  • 经过UTF-8编码的bytes类型
  • file-like object
  • 可迭代类型，会通过Chunked Encoding传输。

也就是说 input 参数可以比 data 参数多接受第一种类型的输入。

返回值

Service 和 Bucket 类的大多数方法都是返回 RequestResult 及其子类。 RequestResult 包含了HTTP响应的状态码、头部以及OSS Request ID，而它的子类则包含用户真正想要的结果。例如，ListBucketsResult.buckets 就是返回的Bucket信息列表；GetObjectResult 则是一个file-like object，可以调用 read() 来获取响应的HTTP包体。

加密接口 CryptoBucket ：

CryptoBucket仅提供上传下载加密数据的接口，诸如 get_object、 put_object，返回值与Bucket相应接口一致。

异常

一般来说Python SDK可能会抛出三种类型的异常，这些异常都继承于 OssError ：
  • ClientError ：由于用户参数错误而引发的异常；
  • ServerError 及其子类：OSS服务器返回非成功的状态码，如4xx或5xx。
  • RequestError ：底层requests库抛出的异常，如DNS解析错误，超时等。”

当然，Bucket.put_object_from_file 和 Bucket.get_object_to_file 这类函数还会抛出文件相关的异常。

指定下载范围

诸如 get_object 以及 upload_part_copy 这样的函数，可以接受 byte_range 参数，表明读取数据的范围。该参数是一个二元tuple：(start, last)。这些接口会把它转换为Range头部的值，如：

  • byte_range 为 (0, 99) 转换为 ‘bytes=0-99’，表示读取前100个字节
  • byte_range 为 (None, 99) 转换为 ‘bytes=-99’，表示读取最后99个字节
  • byte_range 为 (100, None) 转换为 ‘bytes=100-‘，表示读取第101个字节到文件结尾的部分（包含第101个字节）

分页罗列

罗列各种资源的接口，如 list_buckets 、 list_objects 都支持分页查询。通过设定分页标记（如：marker 、 key_marker ）的方式可以指定查询某一页。首次调用将分页标记设为空（缺省值，可以不设），后续的调用使用返回值中的 next_marker 、 next_key_marker 等。每次调用后检查返回值中的 is_truncated ，其值为 False 说明已经到了最后一页。

上传下载进度

上传下载接口，诸如 get_object 、 put_object 、resumable_upload，都支持进度回调函数，可以用它实现进度条等功能。

progress_callback 的函数原型如下
>>> def progress_callback(bytes_consumed, total_bytes):
>>>     '''progress callback
>>> 
>>>     :param int bytes_consumed: Consumed bytes. For upload it's uploaded bytes. for download it is download bytes.
>>>     :param int total_bytes: Total bytes.
>>>     '''
其中 total_bytes 对于上传和下载有不同的含义：
  • 上传：当输入是bytes或可以seek/tell的文件对象，那么它的值就是总的字节数；否则，其值为None
  • 下载：当返回的HTTP相应中有Content-Length头部，那么它的值就是Content-Length的值；否则，其值为None

Unix Time

OSS Python SDK会把从服务器获得时间戳都转换为自1970年1月1日UTC零点以来的秒数，即Unix Time。参见 Unix Time https://en.wikipedia.org/wiki/Unix_time

OSS中常用的时间格式有：
  • HTTP Date格式，形如 Sat, 05 Dec 2015 11:04:39 GMT 这样的GMT时间。用在If-Modified-Since、Last-Modified这些HTTP请求、响应头里。
  • ISO8601格式，形如 2015-12-05T00:00:00.000Z。用在生命周期管理配置、列举Bucket结果中的创建时间、列举文件结果中的最后修改时间等处。
http_date 函数把Unix Time转换为HTTP Date；而 http_to_unixtime 则做相反的转换。如:
>>> import oss2, time
>>> unix_time = int(time.time())             # Current time in UNIX Time, Value is 1449313829
>>> date_str = oss2.http_date(unix_time)     # The date_str will be 'Sat, 05 Dec 2015 11:10:29 GMT'
>>> oss2.http_to_unixtime(date_str)          # The result is 1449313829

注解

生成HTTP协议所需的日期（即HTTP Date）时，请使用 http_date ， 不要使用 strftime 这样的函数。因为后者是和locale相关的。比如， strftime 结果中可能会出现中文，而这样的格式，OSS服务器是不能识别的。

iso8601_to_unixtime 把ISO8601格式转换为Unix Time；date_to_iso8601 和 iso8601_to_date 则在ISO8601格式的字符串和datetime.date之间相互转换。如:
>>> import oss2
>>> d = oss2.iso8601_to_date('2015-12-05T00:00:00.000Z')  # Get datetime.date(2015, 12, 5)
>>> date_str = oss2.date_to_iso8601(d)                    # Get '2015-12-05T00:00:00.000Z'
>>> oss2.iso8601_to_unixtime(date_str)                    # Get 1449273600