- Notifications
You must be signed in to change notification settings - Fork28
upyun/python-sdk
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
UPYUN Python SDK，集合UPYUN HTTP REST 接口，UPYUN HTTP FORM 接口 和视频处理接口。
- 不再兼容 1.x 的版本，新版接口设计和实现更加 Pythonic，且代码风格完全符合pep8 规范。
- 2.2.0 及以上版本同时兼容了最新版本的 Python 2.6 / 2.7 / 3.3 / 3.4。
- 2.3.0 及以上版本不再支持直接使用默认标准库 httplib，必须依赖 requests 这个第三方 HTTP Client 库。
- 2.5.0 及以上版本更新了 REST API，FORM API 以及预处理接口的签名算法，同时移除分块上传接口。
安装第三方依赖库requests: HTTP for Humans!
pip install requests安装 UPYUN SDK
pip install upyun运行测试用例
export UPYUN_SERVICE=<service>export UPYUN_USERNAME=<username>export UPYUN_PASSWORD=<password>make init testimportupyunup=upyun.UpYun('service','username','password',timeout=30,endpoint=upyun.ED_AUTO)
service，username，password 分别为服务名，授权操作员帐号，密码。timeout 为 HTTP 请求超时时间，默认 60 秒，可选。
由于直接在 SDK 中暴露密码可能存在安全隐患，因此对于安全性要求较高的用户，可使用如下远程签名方式：
importupyunup=upyun.UpYun('service',username='username',auth_server='http://localhost:8080')
签名服务示例代码见examples/auth_server.py
远程签名方式暂不支持缓存刷新功能
importupyunup=upyun.UpYun('service',username='username',password='password')
以及，根据国内的网络情况，UPYUN API 目前提供了电信、联通网通、移动铁通三个接入点，在初始化时可由参数endpoint 进行设置，其可选的值有：
upyun.ED_AUTO# 根据网络条件自动选择接入点，默认upyun.ED_TELECOM# 电信接入点upyun.ED_CNC# 联通网通接入点upyun.ED_CTT# 移动铁通接入点
默认设置为upyun.ED_AUTO ，但是我们推荐根据服务器网络状况，手动设置合理的接入点以获取最佳的访问速度。同时，也可通过：
up.<api>.endpoint=upyun.ED_TELECOM
在对象使用过程中更改，其中<api> 为你所要调用接口，REST 为up_rest，表单为up_form，视频处理为av。
up.put('/upyun-python-sdk/ascii.txt','abcdefghijklmnopqrstuvwxyz\n')
其中，方法up.put 默认自动创建相应目录。
headers= {'x-gmkerl-rotate':'180' }withopen('unix.png','rb')asf:res=up.put('/upyun-python-sdk/xinu.png',f,checksum=True,headers=headers)
其中，参数checksum 和headers 可选，前者默认 False，表示不进行 MD5 校验; 后者可根据需求设置自定义 HTTP Header，例如作图参数x-gmkerl-* ，具体请参考REST API 上传文件。
上传成功，如果是图片类型文件，那么res 返回的是一个包含图片长、宽、帧数和类型信息的 Python Dict 对象 ( 其他文件类型, 返回一个空的 Dict)：
{'frames': '1', 'width': '1280', 'file-type': 'PNG', 'height': '800'}上传失败，则抛出相应异常。
up.move('/upyun-python-sdk/move-from.txt','/upyun-python-sdk/move-to.txt')
第一个参数是源文件地址， 第二个参数是目的文件地址
up.copy('/upyun-python-sdk/copy-from.txt','/upyun-python-sdk/copy-to.txt')
第一个参数是源文件地址， 第二个参数是目的文件地址
withopen('unix.png','rb')asf:res=up.put('/upyun-python-sdk/xinu.png',f,checksum=True,need_resume=True)
参数need_resume 默认 False， 置为 True 后， 采用断点续传方式上传文件。
fromupyunimportFileStorefromupyunimportprint_reporterwithopen('unix.png','rb')asf:res=up.put('/upyun-python-sdk/xinu.png',f,checksum=True,need_resume=True,headers={'X-Upyun-Multi-Type':'image/png'},store=FileStore(),reporter=print_reporter)
参数store 用来保存断点信息， 默认保存断点信息在内存中。FileStore() 可以保存断点信息到文件， 注意文件夹的权限， 默认保存在~/.up-python-resume/， 提供参数directory 用于修改默认的文件夹路径。 也可以选择继承BaseStore 实现自己的断点存储。
参数reporter 用于报告上传进度, 默认忽略上传进度。print_reporter 只是print 上传进度, 有需要的请继承BaseReporter 自行处理。
可以使用头部X-Upyun-Multi-Type 来指定待上传文件的 MIME 类型，默认 application/octet-stream，建议自行设置。
并发上传是把文件按照part_size切割后，并发上传，都上传完毕后调用complete结束上传。
part_size取值1M(1024*1024)的整数倍，默认是1M。
下面的示例是并发上传一个2.5M的文件，数据内容是随机生成的。其中的upload方法可以多线程并发调用
uploader=up.init_multi_uploader(key)#初始化上传#并发上传需要数据块uploader.upload(2,os.urandom(512*1024))uploader.upload(0,os.urandom(1024*1024))uploader.upload(1,os.urandom(1024*1024))res=uploader.complete()#所有块都上传完毕后，调用结束
一次上传没有完成, 可以把uploader.upload_id的值保存下来, 下次继续上传
uploader=up.init_multi_uploader(remote_file,upload_id=uploader.upload_id)
如果有需要，可以列出来已经上传成功的parts
datas=uploader.list_uploaded_parts()
返回一个json结构的数组
[{"id":0,"suze":1048576,"etag":"cf97350abc2b45804d09a829b55eeeaf",}]若在上传过程中不需要上传了，可以调用uploader.cancel()取消上传任务。取消的任务无法再继续上传。
用户可直接上传文件到 UPYUN，而不需要通过客户服务器进行中转。
kwargs= {'allow-file-type':'jpg,jpeg,png','notify-url':'http://httpbin.org/post', }withopen('unix.png','rb')asf:res=up.put('/upyun-python-sdk/xinu.png',f,checksum=True,form=True,**kwargs)
其中，参数form 表示是否使用表单上传方式，必选。
同时表单上传可携带许多额外的可选参数，可以组合成字典作为函数可选参数传入，例如表单参数allow-file-type ，具体请参考表单 API 参数。
表单上传还支持同步通知及异步通知机制，可以通过设置return-url 和notify-url 来指定 URL。具体请参考通知规则。
上传成功，如果是图片类型文件，那么res 返回的是一个包含图片长、宽、帧数、类型信息、图片上传地址、返回状态码、返回状态信息和 signature 的 Python Dict 对象 (其他文件类型，则返回信息不包括图片长、宽和帧数参数)：
{u'code': 200, u'image-height': 410, u'url': u'/upyun-python-sdk/xinu.png', u'image-frames': 1, u'sign': u'60e63662202e50bddedd01f8ca601ba5', u'image-type': u'PNG', u'time': 1450783577, u'message': u'ok', u'image-width': 1000}res=up.get('/upyun-python-sdk/ascii.txt')
下载成功，返回文件内容; 失败则抛出相应异常。
withopen('xinu.png','wb')asf:up.get('/upyun-python-sdk/xinu.png',f)
下载成功，返回 PythonNone 对象; 失败则抛出相应异常。
up.mkdir('/upyun-python-sdk/temp/')
创建成功，返回 PythonNone 对象; 失败则抛出相应异常。
up.delete('/upyun-python-sdk/xinu.png')up.delete('/upyun-python-sdk/temp/')
删除成功，返回 PythonNone 对象; 失败则抛出相应异常。注意删除目录时，必须保证目录为空。
res=up.getlist('/upyun-python-sdk/')
获取成功，返回一个包含该目录下所有目录或文件条目信息的 Python List 对象：
[{'time': '1363247311', 'type': 'F', 'name': 'temp', 'size': '0'}, {'time': '1363247311', 'type': 'N', 'name': 'xinu.png', 'size': '477908'}]其中每个条目信息是又是一个 Python Dict 对象：
item=res[0]printitem['name']# 文件名称printitem['type']# 文件类型printitem['size']# 文件大小printitem['time']# 创建时间
获取失败，则抛出相应的异常。该方法默认获取根目录列表信息。
res=up.getlist('/upyun-python-sdk/',limit=10,order='asc',begin='xxx')
三个分页参数，默认为空，具体含义请参见分页参数
res = get_list_with_iter('/upyun-python-sdk/', limit=10, order='asc', begin='xxx'){'files': [{'name': 'xxx.m4a','type': 'N','size': '332918','time': '1449137388'}],'iter': 'xxxxx'}三个分页参数，默认为空，具体含义请参见分页参数
iter_items=up.iterlist('/upyun-python-sdk/',limit=10,order='asc',begin='xxx')# the resulting iterator objectforiteminiter_items:print(item['type'],item['name'],item['size'])
三个分页参数，默认为空，具体含义请参见分页参数
res=up.getinfo('/upyun-python-sdk/xinu.png')printres['file-type']printres['file-size']printres['file-date']
获取成功，返回一个 Python Dict 对象; 失败则抛出相应异常。
res=up.usage()
获取成功，始终返回该服务当前使用的总容量，单位 Bytes，值类型为 Python String 对象; 失败则抛出相应异常。
用于处理已经上传到对应存储服务中的视频文件，进行转码、截图等操作。
source='/service/test.mp4'tasks= [{'type':'probe', }, {'type':'hls','hls_time':'100'}]notify_url='http://httpbin.org/post'up.pretreat(tasks,source,notify_url)
tasks 为提交的任务数据，需将所有任务组成数组，若仅有一个任务，也应组成数组结构，必选。UPYUN 的视频处理服务目前支持四种类型的处理请求：
- 视频转码
- HLS 切割
- 视频截图
- 视频信息获取
具体请参考视频处理参数
notify_url 为异步回调地址，在处理完成之后将会以HTTP POST 请求进行异步通知，参考回调参数, 必选。source 为待处理源文件路径，需提供已上传文件的相对路径。
视频处理任务提交成功，则会针对提交的处理任务返回一组唯一的task_id，可以根据这个task_id 查询处理进度，如:
[ '35f0148d414a688a275bf915ba7cebb2', '98adbaa52b2f63d6d7f327a0ff223348', ...]任务提交失败则会抛出相应异常。
ids= ['35f0148d414a688a275bf915ba7cebb2','98adbaa52b2f63d6d7f327a0ff223348', ...]up.status(ids)
以视频处理接口返回的数组作为传入参数，需为 Python List 结构。
返回的数据示例如下:
{ tasks: { 35f0148d414a688a275bf915ba7cebb2: 100, 98adbaa52b2f63d6d7f327a0ff223348: null, ... }}特别的，当值为 null 时，表示没有查询到相关的任务信息。同时，由于视频处理所用时间较长，当提交任务后立刻去查询进度，也有可能会返回 null。
notify_url = 'http://httpbin.org/post' // 回调地址compress_tasks = [ { "sources": ["a/b/c/source/1.jpg","a/b/c/source/2.jpg"], "save_as": "/result/t.zip", "home_dir": "a/b/c" },]print up.put_tasks(compress_tasks, notify_url, 'compress')depress_tasks = [ { "sources": "/source/t.zip", //UPYUN 存储服务中内文件路径 "save_as": "/result/t/", //保存路径 },]print up.put_tasks(depress_tasks, notify_url, 'depress')fetch_tasks = [ { 'url': 'http://www.upyun.com/index.html', // 需要拉取文件的 URL 'random': False, // 是否追加随机数, 默认 false 'overwrite': True, // 是否覆盖，默认 true 'save_as': '/site/index.html', // 保存路径 }]print up.put_tasks(fetch_tasks, notify_url, 'spiderman')try:res=up.usage()# do something elseexceptupyun.UpYunServiceExceptionasse:print'Except an UpYunServiceException ...'print'Request Id: '+se.request_idprint'HTTP Status Code: '+str(se.status)print'Error Message: '+se.msg+'\n'exceptupyun.UpYunClientExceptionasce:print'Except an UpYunClientException ...'print'Error Message: '+ce.msg+'\n'
其中，UpYunServiceException 主要是 UPYUN 端返回的错误信息，具体错误代码请参考标准 API 错误代码表; 而UpYunClientException 则主要是一些客户端环境的异常，例如客户端网络超时，或客户端参数不完整等。
up=upyun.UpYun('service','username','password',chunksize=8192)
当通过数据流方式上传和下载文件时，chunksize 决定了每次读操作的缓存区大小，默认 8192 字节。
例如，通过如下代码可以很容易实现上传下载的进度条显示：
fromprogressbarimport*classProgressBarHandler(object):def__init__(self,totalsize,params):widgets= [params,Percentage(),' ',Bar(marker='=',left='[',right=']'),' ',ETA(),' ',FileTransferSpeed()]self.pbar=ProgressBar(widgets=widgets,maxval=totalsize).start()defupdate(self,readsofar):self.pbar.update(readsofar)deffinish(self):self.pbar.finish()withopen('unix.png','rb')asf:res=up.put('xinu.png',f,handler=ProgressBarHandler,params='Uploading ')withopen('xinu.png','wb')asf:up.get('xinu.png',f,handler=ProgressBarHandler,params='Downloading ')
withopen('unix.png','rb')asf:res=up.put('xinu.png',f,secret="abc")
其中参数secret 可指定具体密钥内容；默认None，表示不设置密钥。特别地，该功能仅对配置了缩略图版本号的图片服务有效。
详见UPYUN HTTP REST API 接口 中关于原图密钥保护的说明。
基于UPYUN 缓存刷新 API 接口 开发，方便对 CDN 服务缓存资源进行主动刷新。
特别地，云存储服务正常情况下，资源更新则不需要额外提交刷新请求，缓存系统会自动进行处理。
>>>printup.purge('/upyun-python-sdk/xinu.png')[]
>>>printup.purge(['/unix.png','/xinu.png'],domain='invalid.upyun.com')['/unix.png','/unix.png']
支持提交单个或一组 URI 到缓存刷新队列，其中domain 参数可特别指定为该服务对应的绑定域名作为本次刷新的域，默认其值为None，表示始终使用默认域名。
提交成功，返回一个 Python List 对象，包含本次提交中无效的 URI 列表；失败则抛出相应异常。
如果在表单或异步任务提交接口使用了return-url 或notify-url 等通知方法后，回调结果信息头会包含Authorization 字段，用于验证回调信息是否正确。
importupyunup=upyun.UpYun('service','username','password')headers= {'Date':'Fri, 20 Jan 2017 08:46:20 GMT','Content-MD5':'d36489794822f8d33fd28217d8a5bed4','Authorization':'UPYUN username:W738BergX15B+jso8fSPzKd0/zQ='}assertup.verify_signature(headers['Authorization'],'/api/v1/echo',headers)
创建自己的远程签名服务以提供签名功能。实现 API 如下：
URL：任意合法 URL
HTTP 方法：POST
文档格式：JSON
请求参数：
| 参数名称 | 必选 | 类型 |
|---|---|---|
| username | true | string |
| method | true | string |
| uri | true | string |
| date | true | stirng |
| policy | false | string |
| content_md5 | false | string |
返回结果:UPYUN: username:signature
参数说明及签名算法见签名算法
About
UPYUN Python SDK
Resources
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Packages0
Uh oh!
There was an error while loading.Please reload this page.
Contributors14
Uh oh!
There was an error while loading.Please reload this page.