百度 PCS API的使用方法
见以下帮助地址：
http://developer.baidu.com/wiki/index.php?title=%E5%B8%AE%E5%8A%A9%E6%96%87%E6%A1%A3%E9%A6%96%E9%A1%B5/%E4%B8%AA%E4%BA%BA%E4%BA%91%E5%AD%98%E5%82%A8API/api%E6%8E%A5%E5%8F%A3%E6%96%87%E6%A1%A3#PCS_API.E5.88.97.E8.A1.A8
-
1 PCS API的使用方法
1.1 请求格式
1.1.1 说明
1.1.2 HTTP GET消息
1.1.3 HTTP POST消息
1.2 响应格式
1.3 通用参数
-
2 PCS API列表
2.1 quota
2.2 upload（单文件上传）
2.3 upload（分片文件上传）
2.4 create superfile
2.5 download
2.6 mkdir
2.7 meta
2.7.1 获取单文件meta
2.7.2 批量获取文件meta
2.8 list
2.9 move
2.9.1 移动单个文件/目录
2.9.2 批量移动文件/目录
2.10 copy
2.10.1 拷贝单个文件/目录
2.10.2 批量拷贝文件/目录
2.11 delete
2.11.1 删除单个文件/目录
2.11.2 批量删除文件/目录
2.12 search
2.13 thumbnail
2.14 diff
PCS API的使用方法请求格式说明
目前所有的提交类接口仅支持POST方式，查询类接口同时支持POST方式和GET方式。
所有参数应使用UTF-8编码。
-
URL
GET|POST https://pcs.baidu.com/rest/2.0/pcs/{object_name}?{query_string}
-
参数说明
参数名描述{object_name}操作实体，如quota，file{query_string}参数值需要进行urlencode后携带在query_string中HTTP GET消息
-
URL
GET https://pcs.baidu.com/rest/2.0/pcs/{object_name}?{query_string}
-
HTTP Body
HTTP GET请求不携带body
-
参数
GET请求的参数全部携带在query_string中
-
举例
发送两个参数，key1=value1和key2=value2
GET /rest/2.0/pcs/quota?key1=urlencode(value1)&key2=urlencode(value2)HTTP POST消息
-
URL
POST https://pcs.baidu.com/rest/2.0/pcs/{object_name}?{query_string}
-
HTTP Body
multipart/form-data参数不需要进行urlencode
-
参数
POST参数既可以携带在query_string中，也可以携带在HTTP Body中，放在query_string中的参数的值，必须进行urlencode
-
注意
1. 如果HTTP Body 和 query_string存在相同的key，以query_string中的为准2. HTTP URL长度有限，当参数值长度过长，建议将参数放在Body中进行传输
-
举例
发送三个参数，key1=value1、key2=value2和key3=value3。
例一效果等同于例二。
例一:
POST /rest/2.0/pcs/quota?key2=value2&key3=value3HTTP/1.1User-Agent: curl/7.12.1 (x86_64-redhat-linux-gnu) libcurl/7.12.1 OpenSSL/0.9.7a zlib/1.2.1.2 libidn/0.5.6Pragma: no-cacheAccept: */*Host:pcs.baidu.comContent-Length:123Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryS0JIa4uHF7yHd8xJ------WebKitFormBoundaryS0JIa4uHF7yHd8xJContent-Disposition: form-data; name="key1"value1------WebKitFormBoundaryS0JIa4uHF7yHd8xJ--
例二:
POST /rest/2.0/pcs/quota HTTP/1.1User-Agent: curl/7.12.1 (x86_64-redhat-linux-gnu) libcurl/7.12.1 OpenSSL/0.9.7a zlib/1.2.1.2 libidn/0.5.6Pragma: no-cacheAccept: */*Host:pcs.baidu.comContent-Length:123Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryS0JIa4uHF7yHd8xJ------WebKitFormBoundaryS0JIa4uHF7yHd8xJContent-Disposition: form-data; name="key1"value1------WebKitFormBoundaryS0JIa4uHF7yHd8xJContent-Disposition: form-data; name="key2"value2------WebKitFormBoundaryS0JIa4uHF7yHd8xJContent-Disposition: form-data; name="key3"value3------WebKitFormBoundaryS0JIa4uHF7yHd8xJ--响应格式
-
正常请求
Http Status Code
200 OK
Body
API响应内容
-
异常请求
Http Status Code
4** : 用户请求错误5** ：server服务失败
Body
异常请求的返回值为json字符串例如：{"error_code":110,"error_msg":"Access token invalid or no longer valid","request_id":729562373}error_code：错误码error_msg : 错误描述信息request_id: 请求id，server生成，用于追查和定位请求日志
-
错误码定义
HTTP状态码
Error_code
Error_msg
备注
2000no error没有错误4003Unsupported open api不支持此接口4034No permission to do this operation没有权限执行此操作4035Unauthorized client IP addressIP未授权50331001db query error数据库查询错误50331002db connect error数据库连接错误50331003db result set is empty数据库返回空结果50331021network error网络错误50331022can not access server暂时无法连接服务器40031023param error输入参数错误40031024app id is emptyapp id为空50331025bcs error后端存储错误40331041bduss is invalid用户的cookie不是合法的百度cookie40331042user is not login用户未登陆40331043user is not active用户未激活40331044user is not authorized用户未授权40331045user not exists用户不存在40331046user already exists用户已经存在40031061file already exists文件已经存在40031062file name is invalid文件名非法40031063file parent path does not exist文件父目录不存在40331064file is not authorized无权访问此文件40031065directory is full目录已满40331066file does not exist文件不存在50331067file deal failed文件处理出错50331068file create failed文件创建失败50331069file copy failed文件复制失败50331070file delete failed文件删除失败50331071get file meta failed不能读取文件元信息50331072file move failed文件移动失败50331073file rename failed文件重命名失败50331081superfile create failedsuperfile创建失败50331082superfile block list is emptysuperfile 块列表为空50331083superfile update failedsuperfile 更新失败50331101tag internal errortag系统内部错误50331102tag param errortag参数错误50331103tag database errortag系统错误40331110access denied to set quota未授权设置此目录配额40031111quota only sopport 2 level directories配额管理只支持两级目录40031112exceed quota超出配额40331113the quota is bigger than one of its parent directorys配额不能超出目录祖先的配额40331114the quota is smaller than one of its sub directorys配额不能比子目录配额小50331141thumbnail failed, internal error请求缩略图服务失败401110Access token invalid or no longer validAccess Token不正确或者已经过期40031201signature error签名错误40431202object not exists文件不存在40031203acl put error设置acl失败40031204acl query error请求acl验证失败40031205acl get error获取acl失败40431206acl get erroracl不存在40031207bucket already existsbucket已存在40031208bad request用户请求错误50031209baidubs internal error服务器错误50131210not implement服务器不支持40331211access denied禁止访问50331212service unavailable服务不可用50331213service unavailable重试出错50331214put object data error上传文件data失败50331215put object meta error上传文件meta失败50331216get object data error下载文件data失败50331217get object meta error下载文件meta失败40331218storage exceed limit容量超出限额40331219request exceed limit请求数超出限额40331220transfer exceed limit流量超出限额50031298the value of KEY[VALUE] in pcs response headers is invalid服务器返回值KEY非法50031299no KEY in pcs response headers服务器返回值KEY不存在
通用参数
以下参数是所有PCS-Http Open API接口都会用到的统一系统级参数。
参数名
类型
是否必需
描述
methodstring是API的资源操作方法名access_tokenstring是访问令牌，第三方访问任何需要授权才能访问的Restful API时都必须提供该参数以便平台验证其是否是一个合法的第三方。https接口时必须存在。
PCS API中用于描述文件或目录的变量，有以下三种，分别为path、from和to，下表描述他们的使用场景和区别：
参数名
类型
描述
pathstring
可指代文件，也可以指代目录
场景：用于PCS中绝大多数API
参数值：文件绝对路径或目录绝对路径
fromstring
可指代文件，也可以指代目录
场景：主要用于move,copy接口
参数值：文件绝对路径或目录绝对路径
tostring
可指代文件，也可以指代目录
场景：主要用于move,copy接口
参数值：文件绝对路径或目录绝对路径
PCS API列表quota
-
功能：获取当前用户空间配额信息
-
Request url
GET https://pcs.baidu.com/rest/2.0/pcs/quota
-
Request parameter
参数名类型是否必需描述methodstring是固定值：infoaccess_tokenstring是开发者准入token,https调用时必须使用
-
Response body
{"quota":15000000000,"used":5221166,"request_id":4043312634}
-
Response parameter
参数名类型Url Encode描述quotauint64否空间配额，单位为字节。useduint64否已使用空间，单位为字节。
-
Example
curl example
curl -X GET "http://pcs.baidu.com/rest/2.0/pcs/quota?access_token=1.54bef91df2416ee4a41791d4a8ea04fe.86400.1331206383.67272939-188383&method=info"
request
GET /rest/2.0/pcs/quota?access_token=1.54bef91df2416ee4a41791d4a8ea04fe.86400.1331206383.67272939-188383&method=info HTTP/1.1User-Agent: curl/7.12.1 (x86_64-redhat-linux-gnu) libcurl/7.12.1 OpenSSL/0.9.7a zlib/1.2.1.2 libidn/0.5.6Pragma: no-cacheAccept: */*Host:pcs.baidu.com
response
< HTTP/1.1 200 OK< x-pcs-request-id: MTAuMjMuMjQ3LjkxOjgwOjQwNDMzMTI2MzQA< Content-type: text/html< Date: Thu, 08 Mar 2012 05:05:21 GMT< Server: BWS/1.0< Transfer-Encoding: chunked* Connection #0 to host 10.237.1.252 left intact* Closing connection #0{"quota":15000000000,"used":5221166,"request_id":4043312634}upload（单文件上传）
-
功能：创建文件。百度PCS服务支持最大2G的单文件上传，如果需要支持超大文件的断点续传，请参考下面的分片文件上传的upload方法。
-
Request url
POST https://pcs.baidu.com/rest/2.0/pcs/file
-
Request parameter
参数名
类型
是否必须描述
methodstring是固定值，uploadaccess_tokenstring是开发者准入token,https调用时必须使用pathstring是上传文件路径(包含名称)filechar[]是上传文件的内容
注：以上四个参数中file需通过post表单传递，其他三个参数需通过querystring传递。
-
Response body
{"path":"\/apps\/yunform\/music\/hello","size":13,"ctime":1331184269,"mtime":1331184269,"md5":"59ca0efa9f5633cb0371bbc0355478d8","fs_id":3528850315,"request_id":4043312669}
-
Response parameter
参数名类型Url Encode描述pathstring是该文件的绝对路径sizeuint64否文件字节大小ctimeuint64否文件创建时间mtimeuint64否文件修改时间md5string否文件的md5签名fs_iduint64否文件在PCS的临时唯一标识id
-
Example
curl example
curl -X POST -F "file=@./helloworld" "http://pcs.baidu.com/rest/2.0/pcs/file?access_token=1.54bef91df2416ee4a41791d4a8ea04fe.86400.1331206383.67272939-188383&method=upload&path=%2Fapps%2Fyunform%2Fmusic%2Fhello"
request
POST /rest/2.0/pcs/file?access_token=1.54bef91df2416ee4a41791d4a8ea04fe.86400.1331206383.67272939-188383&method=upload&path=%2Fapps%2Fyunform%2Fmusic%2Fhello HTTP/1.1User-Agent: curl/7.12.1 (x86_64-redhat-linux-gnu) libcurl/7.12.1 OpenSSL/0.9.7a zlib/1.2.1.2 libidn/0.5.6Pragma: no-cacheAccept: */*Host:pcs.baidu.comContent-Length: 217Expect: 100-continueContent-Type: multipart/form-data; boundary=----------------------------a849129973a7
response
< HTTP/1.1 100 Continue< Date: Thu, 08 Mar 2012 05:24:28 GMT< Server: BaiduBS< HTTP/1.1 200 OK< x-pcs-request-id: MTAuMjMuMjQ3LjkxOjgwOjQwNDMzMTI2NjkA< x-bs-version: ABB8DC656F397EFBE49806CA296A1CEC< ETag: 59ca0efa9f5633cb0371bbc0355478d8< Content-MD5: 59ca0efa9f5633cb0371bbc0355478d8< x-bs-request-id: YmItaWlzLWRldjAzLnZtLmJhaWR1LmNvbTo4MTk1OjQwNDMzMTI2NjkA< Content-type: text/html< Date: Thu, 08 Mar 2012 05:24:29 GMT< Server: BWS/1.0< Transfer-Encoding: chunked* Connection #0 to host 10.237.1.252 left intact* Closing connection #0{"path":"\/apps\/yunform\/music\/hello","size":13,"ctime":1331184269,"mtime":1331184269,"md5":"59ca0efa9f5633cb0371bbc0355478d8","fs_id":3528850315,"request_id":4043312669}upload（分片文件上传）
-
功能：百度PCS服务支持每次直接上传最大2G的单文件，如果需要支持上传超大文件，那么可以通过组合调用分片文件上传的upload方法和create superfile接口实现：首先将超大文件分割为2G以内的单文件，并调用upload接口将分片文件依次上传，其次调用create superfile接口完成分片文件的重组。除此之外，如果应用中需要支持断点续传的功能，也可以通过分片上传文件并调用create superfile接口的方式实现。
-
Request url
POST https://pcs.baidu.com/rest/2.0/pcs/file
-
Request parameter
参数名
类型
是否必须描述
methodstring是固定值，uploadaccess_tokenstring是开发者准入token,https调用时必须使用typestring是固定值，tmpfilefilechar[]是上传文件的内容
注：以上四个参数中file需通过post表单传递，其他三个参数需通过querystring传递。
-
Response parameter
参数名类型Url Encode描述md5string否文件的md5签名
-
Example
request
https://pcs.baidu.com/rest/2.0/pcs/file?access_token=1.54bef91df2416ee4a41791d4a8ea04fe.86400.1331206383.67272939-188383&method=upload&type=tmpfile
response
{ "md5":"a7619410bca74850f985e488c9a0d51e", "request_id":3238563823 }create superfile
-
功能： 与分片文件上传的upload方法配合使用，可以实现超大文件上传。同时也可以用于断点续传的场景。
-
Request url
POST https://pcs.baidu.com/rest/2.0/pcs/file
-
Request parameter:
参数名
类型
是否必须描述
methodstring是固定值，createsuperfileaccess_tokenstring是开发者准入token,https调用时必须使用pathstring是上传文件路径(包含名称)paramstring是
block_list数组，数组的取值为子文件内容的MD5，子文件至少要有两个，
最多1024个。 本参数必须放在Http Body中进行传输，value示例：
{"block_list":["d41d8cd98f00b204e9800998ecf8427e",
"89dfb274b42951b973fc92ee7c252166","1c83fe229cb9b1f6116aa745b4ef3c0d"]}
-
Response body:
{"path":"\/apps\/yunform\/6ddddd.JPG","size":6844,"ctime":1331197101,"mtime":1331197101,"md5":"baa7c379639b74e9bf98c807498e1b64","fs_id":1548308694,"request_id":4043313276}
-
Response parameter:
参数名类型Url Encode描述pathstring是该文件的绝对路径sizeuint64否文件字节大小ctimeuint64否文件创建时间mtimeuint64否文件修改时间md5string否文件的md5签名fs_iduint64否文件在PCS的临时唯一标识id
-
Example
curl example
curl -v -H "Content-Type: application/x-www-form-urlencoded" -T "request_body.txt" -X POST "https://pcs.baidu.com/rest/2.0/file?method=createsuperfile&path=/apps/yunform/supefile.log&access_token=1.9fb09e8cce44c0d88fe6787138924a26.86400.1331273905.2600617452-188383"
request
> POST /rest/2.0/file?method=createsuperfile&path=/apps/yunform%2Fsupefile.log&access_token=1.9fb09e8cce44c0d88fe6787138924a26.86400.1331273905.2600617452-188383 HTTP/1.1User-Agent: curl/7.12.1 (x86_64-redhat-linux-gnu) libcurl/7.12.1 OpenSSL/0.9.7a zlib/1.2.1.2 libidn/0.5.6Pragma: no-cacheAccept: */*Host: pcs.baidu.comContent-Type: application/x-www-form-urlencodedContent-Length: 163Expect: 100-continue
response
< HTTP/1.1 100 Continue< Date: Thu, 08 Mar 2012 08:58:21 GMT< Server: BaiduBS< HTTP/1.1 200 OK< x-pcs-request-id: MTAuMjMuMjQ3LjkxOjgwOjQwNDMzMTMyNzYA< Content-type: text/html< Date: Thu, 08 Mar 2012 08:58:21 GMT< Server: BWS/1.0< Transfer-Encoding: chunked* Connection #0 to host 10.237.1.252 left intact* Closing connection #0{"path":"\/apps\/yunform\/6ddddd.JPG","size":6844,"ctime":1331197101,"mtime":1331197101,"md5":"baa7c379639b74e9bf98c807498e1b64","fs_id":1548308694,"request_id":4043313276}
download
-
功能：下载文件。Download接口支持HTTP协议标准range定义，通过指定range的取值可以实现断点下载功能。如在request消息中指定Range: bytes=0-99，那么响应消息中会返回该文件的前100个字节的内容，继续指定Range: bytes=100-199，那么响应消息中会返回该文件的第二个100字节内容。
-
Request url
GET https://pcs.baidu.com/rest/2.0/pcs/file
-
Request parameter
参数名
类型
是否必须描述
methodstring是固定值，downloadaccess_tokenstring是开发者准入token,https调用时必须使用pathstring是下载文件路径
-
Response body
文件内容
-
Response parameter
-
Example
curl example
curl -X GET "http://pcs.baidu.com/rest/2.0/pcs/file?access_token=1.54bef91df2416ee4a41791d4a8ea04fe.86400.1331206383.67272939-188383&method=download&path=%2Fapps%2Fyunform%2Fmusic%2Fhello" >hello
request
GET /rest/2.0/pcs/file?access_token=1.54bef91df2416ee4a41791d4a8ea04fe.86400.1331206383.67272939-188383&method=download&path=%2Fapps%2Fyunform%2Fmusic%2Fhello HTTP/1.1User-Agent: curl/7.12.1 (x86_64-redhat-linux-gnu) libcurl/7.12.1 OpenSSL/0.9.7a zlib/1.2.1.2 libidn/0.5.6Pragma: no-cacheAccept: */*Host:pcs.baidu.com
response
< HTTP/1.1 200 OK< x-pcs-request-id: MTAuMjMuMjQ3LjkxOjgwOjQwNDMzMTI4NDkA< Accept-Ranges: bytes< Last-Modified: Thu, 08 Mar 2012 05:24:29 GMT< Expires: Sun, 11 Mar 2012 06:10:43 GMT< x-bs-version: ABB8DC656F397EFBE49806CA296A1CEC< ETag: 59ca0efa9f5633cb0371bbc0355478d8< Content-Type: application/octet-stream< x-bs-request-id: YmItaWlzLWRldjAzLnZtLmJhaWR1LmNvbTo4MTk1OjQwNDMzMTI4NDkA< x-bs-meta-crc32: 2997478465< Content-MD5: 59ca0efa9f5633cb0371bbc0355478d8< Content-Disposition: attachment;filename="hello"< Content-Length: 13< Date: Thu, 08 Mar 2012 06:10:43 GMT< Server: BaiduBS % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 0 13 0 13 0 0 61 0 --:--:-- --:--:-- --:--:-- 0* Connection #0 to host 10.237.1.252 left intact* Closing connection #0mkdir