Document for dawn's SDK

This is the SDK for dawn, which is OSS system. Dawn is honorly presented by TAL's ocean team.

OSS-SDK python 使用说明

描述

• 本文档适用于OSS-SDK python语言版本的开发指南。
• 主要提供如下功能
  • 1.上传单个文件
  • 2.生成对象web访问url，该url带过期时间
  • 3.大文件分段上传
  • 4.查询租户下面的bucket列表
  • 5.查询bucket下面的对象列表

使用前准备

• 使用OSS-SDK前需要先下载，可以采用下面的方式下载：
  • pip install dawn-sdk // python2下载
  • pip3 install dawn-sdk // python3下载
• 在使用之前引入包
  • 可以引入如下包

  from dawn_sdk import auth //认证相关类接口
  from dawn_sdk import bucket //bucket类接口
  from dawn_sdk.xml_body import PartInfo //分段上传返回的分段信息类
  ... //其他导入
  

Bucket类接口

• bucket操作相关接口

1. 构造函数

• 原型

def __init__(self, auth, endpoint, bucket, session=None, connect_timeout=None)

• 参数和返回值：
  • auth: 认证实例对象，即auth.Authorize类的实例对象，用于认证。
  • endpoint: 端点，OSS服务端点，具体值请咨询服务提供者。
  • bucket: bucket名称。
  • session: 会话，通常用于复用之前使用的会话，可以不进行设置，默认不复用之前的会话。
  • connect_timeout: 连接超时，单位为秒，可以不设定该参数，将使用默认超时: 30s.
  • 返回值，无。
• 使用示例：

from dawn_sdk import auth
from dawn_sdk import bucket

access_key="<you access key>"def sign_url(self, key, expires, method='GET', headers=None, params=None)
secret_key="<you secret key>"def sign_url(self, key, expires, method='GET', headers=None, params=None)

//初始化认证
ath = auth.Authorize(access_kdef sign_url(self, key, expires, method='GET', headers=None, params=None)

endpoint="<you OSS endpoint>"
bucket_name="<you bucket name>"
is_cname="<is CNAME or not>" //需要咨询服务提供商
conn_timeout=60 //设置连接超时为60s

//初始化bucket
bkt = bucket.Bucket(ath, endpoint, bucket_name, is_cname， connect_timeout=conn_timeout)

2. 上传对象，从缓冲区上传

• 原型

def put_object(self, key, data, headers=None, progress_callback=None, upload_speed_limited=None)

• 参数和返回值
  • key: 需要上传的对象名
  • data: 需要上传对象的数据，数据的长度必须小于5GB
  • header: 用户自定义HTTP头，通常不需要自定义头，
  • progress_callback: 上传进度回调，原型为： def progress_func(chunk_size, size)
    • chunk_size: 已经传输的字节数
    • size: 总字节数。
  • upload_speed_limited: 上传速度限制，单位为字节每秒。不指定该参数时，即不限速。
  • 返回值: 上传成功则返回PutObject对象，否则抛出异常，可以查看异常的详细信息。
• 使用示例:

//Bucket实例已经构造，如上的构造函数示例，
//bkt = bucket.Bucket(...);

//对象名
obj="<you object name>"
data="<object content...>"
//progress_func为上传进度回调，该参数可选，可以不指定。
progress_func=...
//limit为上传速度限制，该参数可选，可以不指定。
limit=...
try:
  result = bkt.put_object(obj, data, progress_callback=progress_func, upload_speed_limited=limit)
  //成功则不抛出异常。
except BaseError, err:
  //处理失败

3. 上传对象，从文件上传

• 原型

def put_object_from_file(self, key, filename, headers=None, progress_callback=None, upload_speed_limited=None)

• 参数和返回值
  • key: 需要上传的对象名
  • filename: 需要上传的文件路径，文件大小必须小于5GB
  • header: 用户自定义HTTP头，通常不需要自定义头，
  • progress_callback: 上传进度回调，原型为： def progress_func(chunk_size, size)
    • chunk_size: 已经传输的字节数
    • size: 总字节数。
  • upload_speed_limited: 上传速度限制，单位为字节每秒。不指定该参数时，即不限速。
  • 返回值: 上传成功则返回PutObject对象，否则抛出异常，可以查看异常的详细信息。
• 使用示例:

//Bucket实例已经构造，如上的构造函数示例，
//bkt = bucket.Bucket(...);

//对象名
obj="<you object name>"
file="<you upload file path>"
//progress_func为上传进度回调，该参数可选，可以不指定。
//upload_speed_limit为上传速度限制，该参数可选，可以不指定。
try:
  result = bkt.put_object_from_file(obj, file, progress_callback=progress_func, upload_speed_limited=limit)
  //成功则不抛出异常。
except BaseError, err:
  //处理失败

4. 分段上传接口

• 分段上传是一组接口协同工作
• 初始化接口
  • 原型

  def init_multipart_upload(self, key, headers=None)
  

  • 接口说明
    • key: 对象名称
    • headers: 自定义HTTP头，通常不用指定。
    • 返回值： 如果成功，则返回InitMultipartUpload对象，该对象包含了upload的id，作为后续的多次上传的参数使用；如果失败，则抛出异常。
  • 使用示例: 见后面的统一示例
• 上传接口
  • 原型

  def upload_part(self, key, upload_id, part_number, data, progress_callback=None, upload_speed_limited=None, headers=None)
  

  • 接口说明
    • key: 对象名称quxiao
    • upload_id: 调quxiao的返回值。
    • part_number: quxiao范围为[1, 10000]
    • data: 上传的quxiao是缓冲区数据，也可以是LimitedReader对象: LimitedReader是一个受限制的读取器，可以指定读取的长度，而不是整个文件长度。每次上传的数据最大5GB，除了最后一个分段数据没有最小限制外，其他分段都必须大于等于5MB。
    • progress_callquxiao度回调，原型为： def progress_func(chunk_size, size)
      • chunk_size:quxiao节数
      • size: 总字quxiao
    • upload_speed_quxiao速度限制，单位为字节每秒。不指定该参数时，即不限速。
    • header: 用户quxiao通常不需要自定义头，
    • 返回值： 如果成功，则返回PutObject对象，该对象包含了该分段的ETAG，和part_number构成一个上传信息，所有的上传信息构成上传数组，作为后续完成上传的参数使用；如果失败，则抛出异常。
  • 使用示例: 见后面的统一示例
• 完成上传接口
  • 原型

  def complete_multipart_upload(self, key, upload_id, parts, headers=None)
  

  • 接口说明
    • key: 对象名称
    • upload_id: 调用初始化接口的返回值。
    • parts: 分段上传的数组，数组元素为单词的上传信息，包含part_number和上传成功返回的ETAG。
    • header: 用户自定义HTTP头，通常不需要自定义头，
    • 返回值： 如果成功，则返回PutObject对象；如果失败，则抛出异常。
    • 说明 分段上传接口调用后，对象存储即开始计费，当调用完成或者取消接口时，分段对象才得以消除。所以请务必调用完成或者取消接口。
  • 使用示例: 见后面的统一示例
• 取消上传接口
  • 原型

  def abort_multipart_upload(self, key, upload_id)
  

  • 接口说明
    • key: 对象名称
    • upload_id: 调用始化接口的返回值。
    • 返回值: 成功返回Result对象；如果失败，则抛出异常。
    • 说明 分段上传接口调用后，对象存储即开始计费，当调用完成或者取消接口时，分段对象才得以消除。所以请务必调用完成或者取消接口。
  • 使用示例: 见后面的统一示例
• 统一示例:

  //Bucket实例已经构造，如上的构造函数示例，
  //bkt = bucket.Bucket(...);
  
  //progress_func为上传进度回调，该参数可选，可以不指定。
  progress_func=...
  //limit为上传速度限制，该参数可选，可以不指定。
  limit=...
  
  //对象名
  obj="<you object name>"
  file="<you upload file>"
  
  flen = os.path.getsize(file)
  with open(file, 'rb') as f:
    //分片大小
    slice = (1024 * 1024) * 5
  
    //分段数
    times = flen // slice
    //最后一段的大小
    left = flen % slice
  
  
    uid = None
    //分段初始化
    try: 
      result = bkt.init_multipart_upload(obj)
      uid = result.upload_id
    except BaseError, err:
      //处理错误
  
    parts = []
    number = 1
    while True:
      if times == 0:
        break
      //使用限制读取器： 限制读取器持有支持read的接口的对象。每次最多读取`slice`个字节数据。     
      reader = LimitedReader(f, slice)
  
      try:
        out = bkt.upload_part(obj, uid, number, reader, progress_callback=progress_func, upload_speed_limited=limit)
        part = PartInfo(number, out.etag)
        parts.append(part)
      except BaseError, err:
        //处理错误或者调用取消接口取消
        bkt.abort_multipart_upload(obj, uid)
        exit(-1)
  
      number += 1
      times -= 1
  
    if left > 0:
      reader = LimitedReader(f, left)
  
      out = bkt.upload_part(obj, uid, number, reader, progress_callback=progress_func, upload_speed_limited=limit)
      part = PartInfo(number, out.etag)
      parts.append(part)
    try:
      result = bkt.complete_multipart_upload(obj, uid, parts)
    except BaseError, err:
      //处理错误或者重试多次直到成功。
  

生成对象web访问url接口

• 原型

def sign_url(self, key, expires, method='GET', headers=None, params=None)

• 接口说明
  • key: 对象名称
  • expires: 过期时间，从当前时间开始的秒数。
  • method: 使用url时的HTTP方法，默认为GET。
  • headers: 自定义HTTP头，通常不用指定。
  • params: 自定义HTTP参数，通常不用指定。
  • 返回值： 返回对象的web访问url字符串
• 使用示例

//Bucket实例已经构造，如上的构造函数示例，
//bkt = bucket.Bucket(...);

obj="<you object name>"
expires=3600 // 3600秒 == 1小时

url = bkt.sign_url()
### 查看bucket下面的对象
- 描述，使用场景
- [x] 查询bucket下面的对象
- [x] 通过设定查询的前缀来查询特定前缀的对象，通常可用于将对象名设置为带目录结构的形式，指定前缀查询，将返回目录下面的文件/文件夹。
- [x] 当对象较多时，一次查询无法完成，可以像使用迭代器一样，迭代剩余的查询结果。

- 接口描述和定义
```python
def list_objects(self, prefix='', delimiter='', marker='', max_keys=100)

- 参数
  - [x] prefix
    - 查询对象时，满足指定的前缀的对象将返回。
  - [x] delimiter 
    - 查询时的分隔符，和prefix结合使用
  - [x] marker
    - 查询时，从`标记`处开始，返回之后的对象， **注意，之后指的是对象名按照字典序排序之后。**
  - [x] max_keys
    - 查询时，每次最多返回多少个对象，当还有剩余对象的时候，可以继续查询。默认为100
- 返回值ListObjects定义
```python
class ListObjects(Result):
def __init__(self, resp):
    super(ListObjects, self).__init__(resp)

    self.is_continous = False //知识是否所有的对象返回了。
    self.next_marker = '' //当查询大于max_keys时，下次调用，需要使用该值作为下次调用的标记，以此来保证下次调用的正确性。
    self.objects = []     //对象列表，类型如下SimplifiedBucketInfo
    self.prefixes = []    //目录列表

class SimplifiedBucketInfo(object):
def __init__(self, name, creation_date):
    #: Bucket名
    self.name = name

    #: Bucket的创建时间，类型为int。参考 :ref:`unix_time`。
    self.creation_date = creation_date
```

• 接口使用示例-1 调用步骤：
• 准备bucket

//Bucket实例已经构造，如上的构造函数示例，
bkt = bucket.Bucket(...);
...

• 查询对象 假定bucket内的对象如下：
  • object-1
  • object-11
  • object-2
  • object-21
  • object-22
  • object-3
  • object-31
  • object-32
• 查询所有对象(无任何参数选项)

objects = bkt.list_objects()

//将返回所有对象

• 查询，每次最多返回3个对象结果。

// 2. max keys option.
objects = bkt.list_objects(max_keys = 3)
//将返回前三个对象，返回的对象是按照对象名进行字典序排列的。

• 查询，带特定前缀的对象

// 3. prefix option.
objects = bkt.list_objects(prefix = "object-2")
//将返回以object-2开头的对象，包含object-2

• 查询，从特定标记开始之后的对象

// 4. marker option.
objects = bkt.list_objects(marker = "object-22")
//将返回以object-22为标记，之后的对象，注意，之后指的是按照字典序排序之后。

• 查询，多次查询，每次返回最多3个；并迭代查询，直到查询结束。

// Case 5: List object with paging. each page has 3 objects
mark = ''
while True:
  objs = bkt.list_objects(max_keys = 3, marker = mark)

  //收集对象
  ......

  //下次的查询需要设置当前查询的返回值NextMarker为marker参数，并作为下次迭代的开始。
  mark = objs.next_marker
  if !objs.is_continus:
    break

• 查询，从特定标记开始之后的对象，并且每次最多返回3个对象； 并迭代查询，直到查询结束。

// Case 6: List object with paging , marker and max keys; return 3 items each time.
mark = "object-22"
while True:
  objs = bkt.list_objects(max_keys = 3, marker = mark)

  //收集对象
  ......

  //下次的查询需要设置当前查询的返回值NextMarker为marker参数，并作为下次迭代的开始。
  mark = objs.next_marker
  if !obj.is_continous:
    break

• 查询，特定前缀的对象，并且每次最多返回3个对象； 并迭代查询，直到查询结束。

// Case 7: List object with paging , with prefix and max keys; return 2 items each time.
pre = "object-2"
mark = ""
while True:
  objs = bkt.list_objects(prefix = pre, marker = mark, max_keys = 3)

  //收集对象
  ......

  //下次的查询， 需要设置marker为当前查询的返回值NextMarker，并作为下次迭代的开始。
  mark = objs.next_marker
  if !objs.is_continous:
    break

• 接口使用示例-2 调用步骤：
  • 准备bucket

  //Bucket实例已经构造，如上的构造函数示例，
  bkt = bucket.Bucket(...);
  ...
  

  • 查询对象(文件夹下面的对象) 假定bucket内的对象如下：
    • movie/readme.txt
    • movie/readme.md
    • movie/love/001.mp4
    • movie/love/002.rmvb
    • movie/war/001.avi
    • movie/war/002.rm
  • 查询，特定目录下面的文件/文件夹

  objs = bkt.list_objects(prefix = "movie/", delimiter = "/")
  //返回以`movie/`开头， 并且以`/`分割的对象或对象前缀
  // 返回对象(文件) objs.objects
  //  1. movie/readme.txt
  //  2. movie/readme.md
  // 返回对象前缀(文件夹) objs.prefixes
  //  1. movie/love/
  //  2. movie/war/