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)

获取当前用户空间配额信息.

Returns:Response 对象

上传单个文件

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 – 上传文件的内容。
  • ondup

    (可选)

    • ‘overwrite’:表示覆盖同名文件;
    • ‘newcopy’:表示生成文件副本并进行重命名,命名规则为“ 文件名_日期.后缀”。
Returns:

Response 对象

分片上传—文件分片及上传

PCS.upload_tmpfile(file_content, **kwargs)

分片上传—文件分片及上传.

百度 PCS 服务支持每次直接上传最大2G的单个文件。

如需支持上传超大文件(>2G),则可以通过组合调用分片文件上传的 upload_tmpfile 方法和 upload_superfile 方法实现:

  1. 首先,将超大文件分割为2G以内的单文件,并调用 upload_tmpfile 将分片文件依次上传;
  2. 其次,调用 upload_superfile ,完成分片文件的重组。

除此之外,如果应用中需要支持断点续传的功能, 也可以通过分片上传文件并调用 upload_superfile 接口的方式实现。

Parameters:file_content – 上传文件的内容
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 对象

下载单个文件

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:
  • 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 对象

移动单个文件/目录

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:
  • remote_path (str) –

    需要检索的目录路径,路径必须以 /apps/ 开头。

    Warning

    • 路径长度限制为1000;
    • 径中不能包含以下字符:\\ ? | " > < : *
    • 文件名或路径名开头结尾不能是 . 或空白字符,空白字符包括: \r, \n, \t, 空格, \0, \x0B
  • keyword (str) – 关键词
  • recurrent (str) –

    是否递归。

    • “0”表示不递归
    • “1”表示递归
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:
  • remote_path (str) –

    需要下载的视频文件路径,以/开头的绝对路径, 需含源文件的文件名。

    Warning

    • 路径长度限制为1000;
    • 径中不能包含以下字符:\\ ? | " > < : *
    • 文件名或路径名开头结尾不能是 . 或空白字符,空白字符包括: \r, \n, \t, 空格, \0, \x0B
  • video_type (str) – 目前支持以下格式: M3U8_320_240、M3U8_480_224、M3U8_480_360、 M3U8_640_480和M3U8_854_480
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
    • 0:查任务信息
    • 1:查进度信息,默认为1
  • 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

    是否需要返回任务信息:

    • 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 对象

取消离线下载任务

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)

清空回收站.

Returns:Response 对象