API¶
PCS 类¶
- 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.upload(remote_path, file_content, ondup=None, **kwargs)¶
上传单个文件(<2G).
百度PCS服务目前支持最大2G的单个文件上传。如需支持超大文件(>2G)的断点续传,请参考下面的“分片文件上传”方法。Parameters: - remote_path –
网盘中文件的保存路径(包含文件名)。 必须以 /apps/ 开头。
Warning
- 路径长度限制为1000;
- 径中不能包含以下字符:\\ ? | " > < : *;
- 文件名或路径名开头结尾不能是 . 或空白字符,空白字符包括: \r, \n, \t, 空格, \0, \x0B 。
- file_content – 上传文件的内容/文件对象 。 (e.g. open('foobar', 'rb') )
- ondup –
(可选)
- ‘overwrite’:表示覆盖同名文件;
- ‘newcopy’:表示生成文件副本并进行重命名,命名规则为“ 文件名_日期.后缀”。
Returns: Response 对象
- remote_path –
分片上传—文件分片及上传¶
- PCS.upload_tmpfile(file_content, **kwargs)¶
分片上传—文件分片及上传.
百度 PCS 服务支持每次直接上传最大2G的单个文件。
如需支持上传超大文件(>2G),则可以通过组合调用分片文件上传的 upload_tmpfile 方法和 upload_superfile 方法实现:
- 首先,将超大文件分割为2G以内的单文件,并调用 upload_tmpfile 将分片文件依次上传;
- 其次,调用 upload_superfile ,完成分片文件的重组。
除此之外,如果应用中需要支持断点续传的功能, 也可以通过分片上传文件并调用 upload_superfile 接口的方式实现。
Parameters: file_content – 上传文件的内容/文件对象 (e.g. open('foobar', 'rb') ) Returns: Response 对象
分片上传—合并分片文件¶
- PCS.upload_superfile(remote_path, block_list, ondup=None, **kwargs)¶
分片上传—合并分片文件.
与分片文件上传的 upload_tmpfile 方法配合使用, 可实现超大文件(>2G)上传,同时也可用于断点续传的场景。
Parameters: - remote_path –
网盘中文件的保存路径(包含文件名)。 必须以 /apps/ 开头。
Warning
- 路径长度限制为1000;
- 径中不能包含以下字符:\\ ? | " > < : *;
- 文件名或路径名开头结尾不能是 . 或空白字符,空白字符包括: \r, \n, \t, 空格, \0, \x0B 。
- block_list (list) – 子文件内容的 MD5 值列表;子文件至少两个,最多1024个。
- ondup –
(可选)
- ‘overwrite’:表示覆盖同名文件;
- ‘newcopy’:表示生成文件副本并进行重命名,命名规则为“ 文件名_日期.后缀”。
Returns: Response 对象
- remote_path –
下载单个文件¶
- 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 = PCS('token') >>> 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.list_files(remote_path, by=None, order=None, limit=None, **kwargs)¶
获取目录下的文件列表.
Parameters: - remote_path –
网盘中目录的路径,必须以 /apps/ 开头。
Warning
- 路径长度限制为1000;
- 径中不能包含以下字符:\\ ? | " > < : *;
- 文件名或路径名开头结尾不能是 . 或空白字符,空白字符包括: \r, \n, \t, 空格, \0, \x0B 。
- by –
排序字段,缺省根据文件类型排序:
- time(修改时间)
- name(文件名)
- size(大小,注意目录无大小)
- order –
“asc”或“desc”,缺省采用降序排序。
- asc(升序)
- desc(降序)
- limit –
返回条目控制,参数格式为:n1-n2。
返回结果集的[n1, n2)之间的条目,缺省返回所有条目; n1从0开始。
Returns: Response 对象
- remote_path –
移动单个文件/目录¶
- 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 对象
- from_path –
批量移动单个文件/目录¶
- 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 操作则会保留原文件。
- from_path –
批量拷贝文件/目录¶
- 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.thumbnail(remote_path, height, width, quality=100, **kwargs)¶
获取指定图片文件的缩略图.
Parameters: Returns: Response 对象
Warning
有以下限制条件:
- 原图大小(0, 10M];
- 原图类型: jpg、jpeg、bmp、gif、png;
- 目标图类型:和原图的类型有关;例如:原图是gif图片, 则缩略后也为gif图片。
增量更新查询¶
视频转码¶
- 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: 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 –
是否需要返回任务信息:
- 0:不需要
- 1:需要,默认为1
- start – 查询任务起始位置,默认为0。
- limit – 设定返回任务数量,默认为10。
- asc –
- 0:降序,默认值
- 1:升序
- 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 对象
- need_task_info –
取消离线下载任务¶
回收站¶
查询回收站文件¶
- PCS.list_recycle_bin(start=0, limit=1000, **kwargs)¶
获取回收站中的文件及目录列表.
Parameters: - start – 返回条目的起始值,缺省值为0
- limit – 返回条目的长度,缺省值为1000
Returns: Response 对象
还原单个文件或目录¶
tools¶
获取新的 Access Token 和 Refresh Token¶
- baidupcs.tools.get_new_access_token(refresh_token, client_id, client_secret, scope=None, **kwargs)¶
使用 Refresh Token 刷新以获得新的 Access Token.
Parameters: - refresh_token – 用于刷新 Access Token 用的 Refresh Token;
- client_id – 应用的 API Key;
- client_secret – 应用的 Secret Key;
- scope – 以空格分隔的权限列表,若不传递此参数,代表请求的数据访问 操作权限与上次获取 Access Token 时一致。通过 Refresh Token 刷新 Access Token 时所要求的 scope 权限范围必须小于等于上次 获取 Access Token 时授予的权限范围。 关于权限的具体信息请参考 “ 权限列表 ”。
Returns: Response 对象
关于 response.json() 字典的内容所代表的含义, 请参考 相关的百度帮助文档 。