Package: dawn-sdk
Document for dawn's SDKThis 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下载在使用之前引入包可以引入如下包fromdawn_sdkimportauth//认证相关类接口fromdawn_sdkimportbucket//bucket类接口fromdawn_sdk.xml_bodyimportPartInfo//分段上传返回的分段信息类...//其他导入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.返回值，无。使用示例：fromdawn_sdkimportauthfromdawn_sdkimportbucketaccess_key="<you access key>"defsign_url(self,key,expires,method='GET',headers=None,params=None)secret_key="<you secret key>"defsign_url(self,key,expires,method='GET',headers=None,params=None)//初始化认证ath=auth.Authorize(access_kdefsign_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//初始化bucketbkt=bucket.Bucket(ath,endpoint,bucket_name,is_cname，connect_timeout=conn_timeout)2. 上传对象，从缓冲区上传原型defput_object(self,key,data,headers=None,progress_callback=None,upload_speed_limited=None)参数和返回值key: 需要上传的对象名data: 需要上传对象的数据，数据的长度必须小于5GBheader: 用户自定义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)//成功则不抛出异常。exceptBaseError,err://处理失败3. 上传对象，从文件上传原型defput_object_from_file(self,key,filename,headers=None,progress_callback=None,upload_speed_limited=None)参数和返回值key: 需要上传的对象名filename: 需要上传的文件路径，文件大小必须小于5GBheader: 用户自定义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)//成功则不抛出异常。exceptBaseError,err://处理失败4. 分段上传接口分段上传是一组接口协同工作初始化接口原型definit_multipart_upload(self,key,headers=None)接口说明key: 对象名称headers: 自定义HTTP头，通常不用指定。返回值： 如果成功，则返回InitMultipartUpload对象，该对象包含了upload的id，作为后续的多次上传的参数使用；如果失败，则抛出异常。使用示例: 见后面的统一示例上传接口原型defupload_part(self,key,upload_id,part_number,data,progress_callback=None,upload_speed_limited=None,headers=None)接口说明key: 对象名称quxiaoupload_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: 总字quxiaoupload_speed_quxiao速度限制，单位为字节每秒。不指定该参数时，即不限速。header: 用户quxiao通常不需要自定义头，返回值： 如果成功，则返回PutObject对象，该对象包含了该分段的ETAG，和part_number构成一个上传信息，所有的上传信息构成上传数组，作为后续完成上传的参数使用；如果失败，则抛出异常。使用示例: 见后面的统一示例完成上传接口原型defcomplete_multipart_upload(self,key,upload_id,parts,headers=None)接口说明key: 对象名称upload_id: 调用初始化接口的返回值。parts: 分段上传的数组，数组元素为单词的上传信息，包含part_number和上传成功返回的ETAG。header: 用户自定义HTTP头，通常不需要自定义头，返回值： 如果成功，则返回PutObject对象；如果失败，则抛出异常。说明分段上传接口调用后，对象存储即开始计费，当调用完成或者取消接口时，分段对象才得以消除。所以请务必调用完成或者取消接口。使用示例: 见后面的统一示例取消上传接口原型defabort_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)withopen(file,'rb')asf://分片大小slice=(1024*1024)*5//分段数times=flen//slice//最后一段的大小left=flen%sliceuid=None//分段初始化try:result=bkt.init_multipart_upload(obj)uid=result.upload_idexceptBaseError,err://处理错误parts=[]number=1whileTrue:iftimes==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)exceptBaseError,err://处理错误或者调用取消接口取消bkt.abort_multipart_upload(obj,uid)exit(-1)number+=1times-=1ifleft>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)exceptBaseError,err://处理错误或者重试多次直到成功。生成对象web访问url接口原型defsign_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]当对象较多时，一次查询无法完成，可以像使用迭代器一样，迭代剩余的查询结果。-接口描述和定义```pythondeflist_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-1object-11object-2object-21object-22object-3object-31object-32查询所有对象(无任何参数选项)objects=bkt.list_objects()//将返回所有对象查询，每次最多返回3个对象结果。//2.maxkeysoption.objects=bkt.list_objects(max_keys=3)//将返回前三个对象，返回的对象是按照对象名进行字典序排列的。查询，带特定前缀的对象//3.prefixoption.objects=bkt.list_objects(prefix="object-2")//将返回以object-2开头的对象，包含object-2查询，从特定标记开始之后的对象//4.markeroption.objects=bkt.list_objects(marker="object-22")//将返回以object-22为标记，之后的对象，注意，之后指的是按照字典序排序之后。查询，多次查询，每次返回最多3个；并迭代查询，直到查询结束。//Case5:Listobjectwithpaging.eachpagehas3objectsmark=''whileTrue:objs=bkt.list_objects(max_keys=3,marker=mark)//收集对象......//下次的查询需要设置当前查询的返回值NextMarker为marker参数，并作为下次迭代的开始。mark=objs.next_markerif!objs.is_continus:break查询，从特定标记开始之后的对象，并且每次最多返回3个对象； 并迭代查询，直到查询结束。//Case6:Listobjectwithpaging,markerandmaxkeys;return3itemseachtime.mark="object-22"whileTrue:objs=bkt.list_objects(max_keys=3,marker=mark)//收集对象......//下次的查询需要设置当前查询的返回值NextMarker为marker参数，并作为下次迭代的开始。mark=objs.next_markerif!obj.is_continous:break查询，特定前缀的对象，并且每次最多返回3个对象； 并迭代查询，直到查询结束。//Case7:Listobjectwithpaging,withprefixandmaxkeys;return2itemseachtime.pre="object-2"mark=""whileTrue:objs=bkt.list_objects(prefix=pre,marker=mark,max_keys=3)//收集对象......//下次的查询，需要设置marker为当前查询的返回值NextMarker，并作为下次迭代的开始。mark=objs.next_markerif!objs.is_continous:break接口使用示例-2调用步骤：准备bucket//Bucket实例已经构造，如上的构造函数示例，bkt=bucket.Bucket(...);...查询对象(文件夹下面的对象)
假定bucket内的对象如下：movie/readme.txtmovie/readme.mdmovie/love/001.mp4movie/love/002.rmvbmovie/war/001.avimovie/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/