API
-
class baidupcs.PCS(access_token, api_template='https://pcs.baidu.com/rest/2.0/pcs/{0}')
百度个人云存储(PCS)Python SDK.
所有 api 方法的返回值均为 requests.Response 对象:
>>> pcs = PCS('access_token')
>>> response = pcs.info()
>>> response
<Response [200]>
>>> response.ok # 状态码是否是 200
True
>>> response.status_code # 状态码
200
>>> response.content # 原始内容(二进制,json 字符串)
'{"quota":6442450944,"used":5138887,"request_id":1216061570}'
>>>
>>> response.json() # 将 json 字符串转换为 python dict
{u'used': 5138887, u'quota': 6442450944L, u'request_id': 1216061570}
关于各 api 方法的更多示例请参考 测试用例 。
关于各 api 方法的 response.json() 字典值的含义请查看 百度 PCS 文档 。
基本功能
空间配额信息
-
PCS.info(**kwargs)
获取当前用户空间配额信息.
上传单个文件
-
PCS.upload(remote_path, file_content, ondup=None, **kwargs)
上传单个文件(<2G).
百度PCS服务目前支持最大2G的单个文件上传。
如需支持超大文件(>2G)的断点续传,请参考下面的“分片文件上传”方法。
Parameters: |
|
Returns: | Response 对象
|
分片上传—文件分片及上传
-
PCS.upload_tmpfile(file_content, **kwargs)
分片上传—文件分片及上传.
百度 PCS 服务支持每次直接上传最大2G的单个文件。
如需支持上传超大文件(>2G),则可以通过组合调用分片文件上传的
upload_tmpfile 方法和 upload_superfile 方法实现:
- 首先,将超大文件分割为2G以内的单文件,并调用 upload_tmpfile
将分片文件依次上传;
- 其次,调用 upload_superfile ,完成分片文件的重组。
除此之外,如果应用中需要支持断点续传的功能,
也可以通过分片上传文件并调用 upload_superfile 接口的方式实现。
Parameters: | file_content – 上传文件的内容 |
Returns: | Response 对象 |
分片上传—合并分片文件
-
PCS.upload_superfile(remote_path, block_list, ondup=None, **kwargs)
分片上传—合并分片文件.
与分片文件上传的 upload_tmpfile 方法配合使用,
可实现超大文件(>2G)上传,同时也可用于断点续传的场景。
Parameters: |
|
Returns: | Response 对象
|
下载单个文件
-
PCS.download(remote_path, **kwargs)
下载单个文件。
download 接口支持HTTP协议标准range定义,通过指定range的取值可以实现
断点下载功能。 例如:如果在request消息中指定“Range: bytes=0-99”,
那么响应消息中会返回该文件的前100个字节的内容;
继续指定“Range: bytes=100-199”,
那么响应消息中会返回该文件的第二个100字节内容:
>>> headers = {'Range': 'bytes=0-99'}
>>> pcs.download('/apps/test_sdk/test.txt', headers=headers)
Parameters: | remote_path – 网盘中文件的路径(包含文件名)。
必须以 /apps/ 开头。
Warning
- 路径长度限制为1000;
- 径中不能包含以下字符:\\ ? | " > < : *;
- 文件名或路径名开头结尾不能是 .
或空白字符,空白字符包括:
\r, \n, \t, 空格, \0, \x0B 。
|
Returns: | Response 对象 |
创建目录
-
PCS.mkdir(remote_path, **kwargs)
为当前用户创建一个目录.
Parameters: | remote_path – 网盘中目录的路径,必须以 /apps/ 开头。
Warning
- 路径长度限制为1000;
- 径中不能包含以下字符:\\ ? | " > < : *;
- 文件名或路径名开头结尾不能是 .
或空白字符,空白字符包括:
\r, \n, \t, 空格, \0, \x0B 。
|
Returns: | Response 对象 |
获取单个文件/目录的元信息
-
PCS.meta(remote_path, **kwargs)
获取单个文件或目录的元信息.
Parameters: | remote_path – 网盘中文件/目录的路径,必须以 /apps/ 开头。
Warning
- 路径长度限制为1000;
- 径中不能包含以下字符:\\ ? | " > < : *;
- 文件名或路径名开头结尾不能是 .
或空白字符,空白字符包括:
\r, \n, \t, 空格, \0, \x0B 。
|
Returns: | Response 对象 |
批量获取文件/目录的元信息
-
PCS.multi_meta(path_list, **kwargs)
批量获取文件或目录的元信息.
Parameters: | path_list (list) – 网盘中文件/目录的路径列表,路径必须以 /apps/ 开头。
Warning
- 路径长度限制为1000;
- 径中不能包含以下字符:\\ ? | " > < : *;
- 文件名或路径名开头结尾不能是 .
或空白字符,空白字符包括:
\r, \n, \t, 空格, \0, \x0B 。
|
Returns: | Response 对象 |
获取目录下的文件列表
-
PCS.list_files(remote_path, by=None, order=None, limit=None, **kwargs)
获取目录下的文件列表.
Parameters: |
|
Returns: | Response 对象
|
移动单个文件/目录
-
PCS.move(from_path, to_path, **kwargs)
移动单个文件或目录.
Parameters: |
- from_path –
源文件/目录在网盘中的路径(包括文件名)。
Warning
- 路径长度限制为1000;
- 径中不能包含以下字符:\\ ? | " > < : *;
- 文件名或路径名开头结尾不能是 .
或空白字符,空白字符包括:
\r, \n, \t, 空格, \0, \x0B 。
- to_path –
目标文件/目录在网盘中的路径(包括文件名)。
Warning
- 路径长度限制为1000;
- 径中不能包含以下字符:\\ ? | " > < : *;
- 文件名或路径名开头结尾不能是 .
或空白字符,空白字符包括:
\r, \n, \t, 空格, \0, \x0B 。
|
Returns: | Response 对象
|
批量移动单个文件/目录
-
PCS.multi_move(path_list, **kwargs)
批量移动文件或目录.
Parameters: | path_list (list) – 源文件地址和目标文件地址对列表:
>>> path_list = [
... ('/apps/test_sdk/test.txt', # 源文件
... '/apps/test_sdk/testmkdir/b.txt' # 目标文件
... ),
... ('/apps/test_sdk/test.txt', # 源文件
... '/apps/test_sdk/testmkdir/b.txt' # 目标文件
... ),
... ]
Warning
- 路径长度限制为1000;
- 径中不能包含以下字符:\\ ? | " > < : *;
- 文件名或路径名开头结尾不能是 .
或空白字符,空白字符包括:
\r, \n, \t, 空格, \0, \x0B 。
|
Returns: | Response 对象 |
拷贝单个文件/目录
-
PCS.copy(from_path, to_path, **kwargs)
拷贝文件或目录.
Parameters: |
- from_path –
源文件/目录在网盘中的路径(包括文件名)。
Warning
- 路径长度限制为1000;
- 径中不能包含以下字符:\\ ? | " > < : *;
- 文件名或路径名开头结尾不能是 .
或空白字符,空白字符包括:
\r, \n, \t, 空格, \0, \x0B 。
- to_path –
目标文件/目录在网盘中的路径(包括文件名)。
Warning
- 路径长度限制为1000;
- 径中不能包含以下字符:\\ ? | " > < : *;
- 文件名或路径名开头结尾不能是 .
或空白字符,空白字符包括:
\r, \n, \t, 空格, \0, \x0B 。
|
Returns: | Response 对象
|
Warning
move 操作后,源文件被移动至目标地址;
copy 操作则会保留原文件。
批量拷贝文件/目录
-
PCS.multi_copy(path_list, **kwargs)
批量拷贝文件或目录.
Parameters: | path_list (list) – 源文件地址和目标文件地址对的列表:
>>> path_list = [
... ('/apps/test_sdk/test.txt', # 源文件
... '/apps/test_sdk/testmkdir/b.txt' # 目标文件
... ),
... ('/apps/test_sdk/test.txt', # 源文件
... '/apps/test_sdk/testmkdir/b.txt' # 目标文件
... ),
... ]
Warning
- 路径长度限制为1000;
- 径中不能包含以下字符:\\ ? | " > < : *;
- 文件名或路径名开头结尾不能是 .
或空白字符,空白字符包括:
\r, \n, \t, 空格, \0, \x0B 。
|
Returns: | Response 对象 |
删除单个文件/目录
-
PCS.delete(remote_path, **kwargs)
删除单个文件或目录.
Warning
- 文件/目录删除后默认临时存放在回收站内,删除文件或目录的临时存放
不占用用户的空间配额;
- 存放有效期为10天,10天内可还原回原路径下,10天后则永久删除。
Parameters: | remote_path (str) – 网盘中文件/目录的路径,路径必须以 /apps/ 开头。
Warning
- 路径长度限制为1000;
- 径中不能包含以下字符:\\ ? | " > < : *;
- 文件名或路径名开头结尾不能是 .
或空白字符,空白字符包括:
\r, \n, \t, 空格, \0, \x0B 。
|
Returns: | Response 对象 |
批量删除文件/目录
-
PCS.multi_delete(path_list, **kwargs)
批量删除文件或目录.
Warning
- 文件/目录删除后默认临时存放在回收站内,删除文件或目录的临时存放
不占用用户的空间配额;
- 存放有效期为10天,10天内可还原回原路径下,10天后则永久删除。
Parameters: | path_list (list) – 网盘中文件/目录的路径列表,路径必须以 /apps/ 开头。
Warning
- 路径长度限制为1000;
- 径中不能包含以下字符:\\ ? | " > < : *;
- 文件名或路径名开头结尾不能是 .
或空白字符,空白字符包括:
\r, \n, \t, 空格, \0, \x0B 。
|
Returns: | Response 对象 |
搜索
-
PCS.search(remote_path, keyword, recurrent='0', **kwargs)
按文件名搜索文件(不支持查找目录).
Parameters: |
|
Returns: | Response 对象
|
高级功能
缩略图
-
PCS.thumbnail(remote_path, height, width, quality=100, **kwargs)
获取指定图片文件的缩略图.
Parameters: |
- remote_path –
源图片的路径,路径必须以 /apps/ 开头。
Warning
- 路径长度限制为1000;
- 径中不能包含以下字符:\\ ? | " > < : *;
- 文件名或路径名开头结尾不能是 .
或空白字符,空白字符包括:
\r, \n, \t, 空格, \0, \x0B 。
- height (int) – 指定缩略图的高度,取值范围为(0,1600]。
- width (int) – 指定缩略图的宽度,取值范围为(0,1600]。
- quality (int) – 缩略图的质量,默认为100,取值范围(0,100]。
|
Returns: | Response 对象
|
Warning
有以下限制条件:
- 原图大小(0, 10M];
- 原图类型: jpg、jpeg、bmp、gif、png;
- 目标图类型:和原图的类型有关;例如:原图是gif图片,
则缩略后也为gif图片。
增量更新查询
-
PCS.diff(cursor='null', **kwargs)
文件增量更新操作查询接口.
本接口有数秒延迟,但保证返回结果为最终一致.
Parameters: | cursor (str) – 用于标记更新断点。
- 首次调用cursor=null;
- 非首次调用,使用最后一次调用diff接口的返回结果
中的cursor。
|
Returns: | Response 对象 |
视频转码
-
PCS.video_convert(remote_path, video_type, **kwargs)
对视频文件进行转码,实现实时观看视频功能.
可下载支持 HLS/M3U8 的 媒体云播放器 SDK 配合使用.
Parameters: |
|
Returns: | Response 对象
|
Warning
目前这个接口支持的源文件格式如下:
格式名称 |
扩展名 |
备注 |
Apple HTTP Live Streaming |
m3u8/m3u |
iOS支持的视频格式 |
ASF |
asf |
视频格式 |
AVI |
avi |
视频格式 |
Flash Video (FLV) |
flv |
Macromedia Flash视频格式 |
GIF Animation |
gif |
视频格式 |
Matroska |
mkv |
Matroska/WebM视频格式 |
MOV/QuickTime/MP4 |
mov/mp4/m4a/
3gp/3g2/mj2 |
支持3GP、3GP2、PSP、iPod
之类视频格式 |
MPEG-PS (program stream) |
mpeg |
也就是VOB文件/SVCD/DVD格式 |
MPEG-TS (transport stream) |
ts |
即DVB传输流 |
RealMedia |
rm/rmvb |
Real视频格式 |
WebM |
webm |
Html视频格式 |
获取流式文件列表
-
PCS.list_streams(file_type, start=0, limit=100, filter_path=None, **kwargs)
以视频、音频、图片及文档四种类型的视图获取所创建应用程序下的
文件列表.
Parameters: |
- file_type – 类型分为video、audio、image及doc四种。
- start – 返回条目控制起始值,缺省值为0。
- limit – 返回条目控制长度,缺省为1000,可配置。
- filter_path –
需要过滤的前缀路径,如:/apps/album
Warning
- 路径长度限制为1000;
- 径中不能包含以下字符:\\ ? | " > < : *;
- 文件名或路径名开头结尾不能是 .
或空白字符,空白字符包括:
\r, \n, \t, 空格, \0, \x0B 。
|
Returns: | Response 对象
|
下载流式文件
-
PCS.download_stream(remote_path, **kwargs)
为当前用户下载一个流式文件.其参数和返回结果与下载单个文件的相同.
Parameters: | remote_path – 需要下载的文件路径,以/开头的绝对路径,含文件名。
Warning
- 路径长度限制为1000;
- 径中不能包含以下字符:\\ ? | " > < : *;
- 文件名或路径名开头结尾不能是 .
或空白字符,空白字符包括:
\r, \n, \t, 空格, \0, \x0B 。
|
Returns: | Response 对象 |
秒传文件
-
PCS.rapid_upload(remote_path, content_length, content_md5, content_crc32, slice_md5, ondup=None, **kwargs)
秒传一个文件.
Warning
- 被秒传文件必须大于256KB(即 256*1024 B)。
- 校验段为文件的前256KB,秒传接口需要提供校验段的MD5。
(非强一致接口,上传后请等待1秒后再读取)
Parameters: |
- remote_path –
上传文件的全路径名。
Warning
- 路径长度限制为1000;
- 径中不能包含以下字符:\\ ? | " > < : *;
- 文件名或路径名开头结尾不能是 .
或空白字符,空白字符包括:
\r, \n, \t, 空格, \0, \x0B 。
- content_length – 待秒传文件的长度。
- content_md5 – 待秒传文件的MD5。
- content_crc32 – 待秒传文件的CRC32。
- slice_md5 – 待秒传文件校验段的MD5。
- ondup –
(可选)
- ‘overwrite’:表示覆盖同名文件;
- ‘newcopy’:表示生成文件副本并进行重命名,命名规则为“
文件名_日期.后缀”。
|
Returns: | Response 对象
|
添加离线下载任务
-
PCS.add_download_task(source_url, remote_path, rate_limit=None, timeout=3600, expires=None, callback='', **kwargs)
添加离线下载任务,实现单个文件离线下载.
Parameters: |
- source_url – 源文件的URL。
- remote_path –
下载后的文件保存路径。
Warning
- 路径长度限制为1000;
- 径中不能包含以下字符:\\ ? | " > < : *;
- 文件名或路径名开头结尾不能是 .
或空白字符,空白字符包括:
\r, \n, \t, 空格, \0, \x0B 。
- rate_limit (int or long) – 下载限速,默认不限速。
- timeout – 下载超时时间,默认3600秒。
- expires (int) – 请求失效时间,如果有,则会校验。
- callback (str) – 下载完毕后的回调,默认为空。
|
Returns: | Response 对象
|
精确查询离线下载任务
-
PCS.query_download_tasks(task_ids, operate_type=1, expires=None, **kwargs)
根据任务ID号,查询离线下载任务信息及进度信息。
Parameters: |
- task_ids (list or tuple) – 要查询的任务ID列表
- operate_type –
- expires (int) – 请求失效时间,如果有,则会校验。
|
Returns: | Response 对象
|
查询离线下载任务列表
-
PCS.list_download_tasks(need_task_info=1, start=0, limit=10, asc=0, create_time=None, status=None, source_url=None, remote_path=None, expires=None, **kwargs)
查询离线下载任务ID列表及任务信息.
Parameters: |
- need_task_info –
是否需要返回任务信息:
- start – 查询任务起始位置,默认为0。
- limit – 设定返回任务数量,默认为10。
- asc –
- create_time (int) – 任务创建时间,默认为空。
- status (int) – 任务状态,默认为空。
0:下载成功,1:下载进行中 2:系统错误,3:资源不存在,
4:下载超时,5:资源存在但下载失败, 6:存储空间不足,
7:目标地址数据已存在, 8:任务取消.
- source_url – 源地址URL,默认为空。
- remote_path –
文件保存路径,默认为空。
Warning
- 路径长度限制为1000;
- 径中不能包含以下字符:\\ ? | " > < : *;
- 文件名或路径名开头结尾不能是 .
或空白字符,空白字符包括:
\r, \n, \t, 空格, \0, \x0B 。
- expires (int) – 请求失效时间,如果有,则会校验。
|
Returns: | Response 对象
|
取消离线下载任务
-
PCS.cancel_download_task(task_id, expires=None, **kwargs)
取消离线下载任务.
Parameters: |
- task_id (str) – 要取消的任务ID号。
- expires (int) – 请求失效时间,如果有,则会校验。
|
Returns: | Response 对象
|
回收站
查询回收站文件
-
PCS.list_recycle_bin(start=0, limit=1000, **kwargs)
获取回收站中的文件及目录列表.
Parameters: |
- start – 返回条目的起始值,缺省值为0
- limit – 返回条目的长度,缺省值为1000
|
Returns: | Response 对象
|
还原单个文件或目录
-
PCS.restore_recycle_bin(fs_id, **kwargs)
还原单个文件或目录(非强一致接口,调用后请sleep 1秒读取).
Parameters: | fs_id (str) – 所还原的文件或目录在PCS的临时唯一标识ID。 |
Returns: | Response 对象 |
批量还原文件或目录
-
PCS.multi_restore_recycle_bin(fs_ids, **kwargs)
批量还原文件或目录(非强一致接口,调用后请sleep1秒 ).
Parameters: | fs_ids (list or tuple) – 所还原的文件或目录在 PCS 的临时唯一标识 ID 的列表。 |
Returns: | Response 对象 |
清空回收站
-
PCS.clean_recycle_bin(**kwargs)
清空回收站.