## File: README.md # BaiduPCS-Go 百度网盘客户端(加强版) 仿 Linux shell 文件处理命令的百度网盘命令行客户端. iikira/BaiduPCS-Go was largely inspired by [GangZhuo/BaiduPCS](https://github.com/GangZhuo/BaiduPCS) and this project was largely based on iikira/BaiduPCS-Go ## 注意 此版本基于iikira原版BaiduPCS-Go v3.6.2继续开发, 并添加了转存功能. 本软件不提供超出官方客户端的下载提速, 普通用户和SVIP的配置建议参见 [显示和修改程序配置项](#显示和修改程序配置项) ## 目录 - [特色](#特色) - [版本更新](#版本更新) - [编译/交叉编译 说明](#编译交叉编译-说明) - [下载/运行 说明](#下载运行-说明) * [安装](#安装) * [Windows](#windows) * [Linux / macOS](#linux--macos) * [Android / iOS](#android--ios) - [命令列表及说明](#命令列表及说明) * [注意 ! ! !](#注意---) * [检测程序更新](#检测程序更新) * [登录百度帐号](#登录百度帐号) * [列出帐号列表](#列出帐号列表) * [获取当前帐号](#获取当前帐号) * [切换百度帐号](#切换百度帐号) * [退出百度帐号](#退出百度帐号) * [获取网盘配额](#获取网盘配额) * [切换工作目录](#切换工作目录) * [输出工作目录](#输出工作目录) * [列出目录](#列出目录) * [列出目录树形图](#列出目录树形图) * [获取文件/目录的元信息](#获取文件目录的元信息) * [搜索文件](#搜索文件) * [下载文件/目录](#下载文件目录) * [上传文件/目录](#上传文件目录) * [获取下载直链](#获取下载直链) * [修复文件MD5](#修复文件MD5) * [创建目录](#创建目录) * [删除文件/目录](#删除文件目录) * [拷贝文件/目录](#拷贝文件目录) * [移动/重命名文件/目录](#移动重命名文件目录) * [转存文件/目录](#转存文件目录) * [分享文件/目录](#分享文件目录) + [设置分享文件/目录](#设置分享文件目录) + [列出已分享文件/目录](#列出已分享文件目录) + [取消分享文件/目录](#取消分享文件目录) * [离线下载](#离线下载) + [添加离线下载任务](#添加离线下载任务) + [精确查询离线下载任务](#精确查询离线下载任务) + [查询离线下载任务列表](#查询离线下载任务列表) + [取消离线下载任务](#取消离线下载任务) + [删除离线下载任务](#删除离线下载任务) * [回收站](#回收站) + [列出回收站文件列表](#列出回收站文件列表) + [还原回收站文件或目录](#还原回收站文件或目录) + [删除回收站文件或目录/清空回收站](#删除回收站文件或目录清空回收站) * [显示和修改程序配置项](#显示和修改程序配置项) * [测试通配符](#测试通配符) * [工具箱](#工具箱) - [初级使用教程](#初级使用教程) * [1. 查看程序使用说明](#1-查看程序使用说明) * [2. 登录百度帐号 (必做)](#2-登录百度帐号-必做) * [3. 切换网盘工作目录](#3-切换网盘工作目录) * [4. 网盘内列出文件和目录](#4-网盘内列出文件和目录) * [5. 下载文件](#5-下载文件) * [6. 设置下载最大并发量](#6-设置下载最大并发量) * [7. 恢复默认配置](#7-恢复默认配置) * [8. 退出程序](#8-退出程序) - [已知问题](#已知问题) - [TODO](#todo) - [交流反馈](#交流反馈) # 特色 多平台支持, 支持 Windows, macOS, linux, 移动设备等. 百度帐号多用户支持; 通配符匹配网盘路径和 Tab 自动补齐命令和路径, [通配符_百度百科](https://baike.baidu.com/item/通配符); [下载](#下载文件目录)网盘内文件, 支持多个文件或目录下载, 支持断点续传和单文件并行下载; [上传](#上传文件目录)本地文件, 支持上传最大128G大文件, 支持多个文件或目录上传; [转存](#转存文件目录)其他用户分享的文件, 支持带密码的分享链接; [离线下载](#离线下载), 支持http/https/ftp/电驴/磁力链协议. # 版本更新 **2026.03.26** v4.0.1 - 紧急修复ls等命令的param error **2025.10.29** v4.0.0 - 上传重新支持跳过秒传`--norapid` - 上传同名文件覆盖策略`--policy`支持`skip`,`overwrite`,`rsync`; 支持`config`配置全局默认策略 - 因接口变化上传不再支持断点续传, 下载不受影响 - 增加`config`配置`proxy_hostnames`, 国外VPS用户如遇上传问题可尝试为`pan.baidu.com`配置回国代理 - 其他细节优化 **2025.08.30** v3.9.9 - 最大上传单文件支持至128G - 上传速度优化 - 下载取消文件预分配 - 因官方接口变动上传文件强制计算秒传 - transfer命令修复`--download`参数 **2025.08.29** v3.9.8 - 全面修复了上传文件的问题 - 全面修复了下载文件的问题 - 去除部分已不可用的功能和已不支持的参数 **2025.01.07** v3.9.7 - fix #359, #360 - fix #339 **2024.12.14** v3.9.6 - 关闭秒传转存功能 - 修复常规转存失败 **2023.09.30** v3.9.5 - 恢复秒传转存功能, 使用前需设置accessToken, 参见setastoken --help - 本地文件上传用秒传无须accessToken - fix #301 - fix #302 **2023.09.06** v3.9.5-beta - 恢复了秒传转存(支持长短链), 感谢油猴脚本开发者tousakarin的贡献 - 新秒传接口需要开发者授权, 稳定性未知, 该测试版本仅供有秒传强需求的用户试用, 请谨慎更新 **2023.09.05** v3.9.4 - fix #244, 修复断点上传时偶发崩溃 - 优化本地上传秒传失败时的处理逻辑 **2023.08.26** v3.9.3 - 因官方接口从原理层面封禁秒传, 取消秒传转存功能 - 更新部分使用说明 - 建议使用文件上传功能的用户更新此版本 **2023.06.03** v3.9.2 - 修复秒传链接无法转存, 因官方接口变动秒传已不再支持短链接格式 - 修复上传文件无法使用秒传 - fix #254 支持-f参数输出带密码分享链接 - fix #251 根据mengzonefire同志提供函数增加md5解密 **2023.03.19** v3.9.1 - 修复秒传转存返回错误码9019 **2022.12.04** v3.9.0: - 优化转存错误提示 - fix #239 - update go version to 1.18 **2022.11.25** v3.8.9: - fix #234, 继续修复无法转存文件 **2022.11.12** v3.8.8: - fix #234, 修复无法转存文件 **2022.2.18** v3.8.7: - fix #175, 在正式上传前即进行文件大小检测 **2022.2.14** v3.8.6: - fix #160 #173, 修复上传出现空文件的bug - fix #165, 支持自带提取码的转存链接 - fix #175, upload增加-policy=rsync策略, 配合--norapid使用, 只跳过大小未发生改变的文件 - 鉴于 #172, 建议下载线程数最大不超过12 **2022.1.1** v3.8.5: #### 该版本存在已知问题将导致上传文件失败及出现空文件，建议跳过更新 - 2022新年好, 本次更新增加较多特性, 欢迎测试 - fix #146, 提前fail和skip上传策略中重名文件的检测环节（存在问题） - fix #158, config可配置关闭文件名合法性检测 - fix #141, download增加--mtime选项可保持文件修改时间 - fix #130, config可配置force_login_username, 强制登录指定用户名 - 首条下载链接不可用时自动切换, 增加下载成功率 **2021.10.6** v3.8.4: - fix 登录时可能出现内存溢出 - 上传文件名允许包含单引号 **2021.8.27** v3.8.3: - fix 更换默认panUA解决svip限速 - fix 移除失效的秒传修复功能 - 优化秒传逻辑, 提高成功率 - 优化秒传导出逻辑, 提高新文件的导出成功率 **2021.7.20** v3.8.2: - fix 读取大量文件信息容易超时 - fix 秒传链接文件名带"#"时解析错误 - share list增加分享下载数显示 - config增加配置: 上传的同名文件处理策略 **2021.6.9** v3.8.1: - fix 部分旧链接无法转存 - 增加上传同名文件自动跳过选项 **2021.5.21** v3.8.0: - fix 上传到100M左右自动回滚（待测试） - fix 个别正常的秒传链接无法转存 - fix 文件名含有百分号导出异常 - 优化上传重试策略（待测试） **2021.4.14** v3.7.9: - fix 上传时异常退出导致无法加载断点信息 - fix 上传偶发出现0B/s卡住 - 上传时预先检查文件名合法性 - 在线更新使用镜像源加速 **2021.3.20** v3.7.8: - 优化了上传的输出信息格式 - 优化了上传逻辑，提升上传速度 - transfer增加--fix参数，可转存被屏蔽的秒传链接（inspired by [dupan-rapid-extract](https://github.com/mengzonefire/dupan-rapid-extract)） **2021.3.11** v3.7.7: - fix 移动和重命名文件时末尾```/```导致报错 - fix 3.7.2版本后在线升级无效 - fix 转存误报缺少STOKEN **2021.2.23** v3.7.6: - fix 下载文件报```x509: certificate is valid```错误 - 完善了下载错误的捕获种类 - download增加--fullpath参数，本地目录保留网盘从根目录开始的完整结构 **2021.2.8** v3.7.5: - fix 某些时候误报stoken缺失 - fix windows平台上秒传链接转存失败 - fix 某些时候pcs请求缺少Host - 当分享链接包含多文件/目录时，可选归档到第一个文件命名的目录里（不支持秒传） **2021.1.31** v3.7.4: - fix 下载目录会丢失目录结构 - fix 分享列表状态信息显示错误 - 支持自定义文件上传服务器 **2021.1.22** v3.7.3: - 分享支持自定义分享码和有效天数 - 转存支持转存完毕后自动下载到默认目录 - 增加恢复默认配置功能 - tree命令支持指定输出最大层数和带fsid输出 **2021.1.9** v3.7.2: - 基本修复了登录验证失效问题([#15](https://github.com/qjfoidnh/BaiduPCS-Go/issues/15)) - 优化下载模块的实现策略, 保证稳定性同时进一步提升下载速度 (需按[显示和修改程序配置项](#显示和修改程序配置项)中建议修改) - update 功能恢复, 以后可以在线升级了 - 支持导出秒传链接不写文件, 直接输出到控制台; 支持通用秒传格式导出, 具体参见export --help - 其他bug修正 **2021.1.2** v3.7.1: - 支持了多文件并发上传，文件并发数和单文件分片数可在配置中指定 - 修复了最大同时下载文件数配置不生效的问题 - 修正了部分显示和帮助的错误 **2020.12.19** v3.7.0: * 替换了iikira版本的失效仓库 * 转存功能支持旧的短链接 * 默认关闭下载文件校验，配置文件可设置开启 * 修复了关闭校验时会误报下载失败的问题 * 转存功能除了cookies方式登录，现已支持用户名密码登录和bduss登录；bduss登录需同时指定stoken **2020.11.08** v3.6.3: * 修复转存失败 * 修复分享文件失败 # 编译/交叉编译 说明 设置好 GOOS 和 GOARCH 环境变量, 运行 go tool dist list 查看所有支持的 GOOS/GOARCH ## Linux/Darwin 例子: 编译 Windows 下的 64 位程序 ``` GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go build ``` ## Windows 例子: 编译 Linux 下的 32 位程序 ``` set GOOS=linux set GOARCH=386 set CGO_ENABLED=0 go build ``` # 下载/运行 说明 Go语言程序, 常用几种平台的已编译程序可直接在[蓝奏云](https://wws.lanzoui.com/b01berebe)下载使用. 密码:4pix 如果程序运行时输出乱码, 请检查下终端的编码方式是否为 `UTF-8`. 使用本程序之前, 建议学习一些 linux 基础知识 和 基础命令. 如果未带任何参数运行程序, 程序将会进入仿Linux shell系统用户界面的cli交互模式, 可直接运行相关命令. cli交互模式下, 光标所在行的前缀应为 `BaiduPCS-Go >`, 如果登录了百度帐号则格式为 `BaiduPCS-Go:<工作目录> <百度ID>$ ` 程序会提供相关命令的使用说明. ## 安装 ## Windows 程序应在 命令提示符 (Command Prompt) 或 PowerShell 中运行, 在 mintty (例如: GitBash) 可能会有显示问题. 也可直接双击程序运行, 具体使用方法请参见 [命令列表及说明](#命令列表及说明) 和 [初级使用教程](#初级使用教程). ## Linux / macOS 程序应在 终端 (Terminal) 运行. 具体使用方法请参见 [命令列表及说明](#命令列表及说明) 和 [初级使用教程](#初级使用教程). ## Android / iOS > Android / iOS 移动设备操作比较麻烦, 不建议在移动设备上使用本程序. 移动设备不可直接使用预编译的Linux arm64版本, 使用者需下载源码自行交叉编译. 安卓, 建议使用 [Termux](https://termux.com) 或 [NeoTerm](https://github.com/NeoTerm/NeoTerm) 或 终端模拟器, 以提供终端环境. 示例: [Android 运行本项目程序参考示例](https://web.archive.org/web/20190820154934/https://github.com/iikira/BaiduPCS-Go/wiki/Android-%E8%BF%90%E8%A1%8C%E6%9C%AC%E9%A1%B9%E7%9B%AE%E7%A8%8B%E5%BA%8F%E5%8F%82%E8%80%83%E7%A4%BA%E4%BE%8B), 有兴趣的可以参考一下. 苹果iOS, 需要越狱, 在 Cydia 搜索下载并安装 MobileTerminal, 或者其他提供终端环境的软件. 示例: [iOS 运行本项目程序参考示例](https://web.archive.org/web/20190820155025/https://github.com/iikira/BaiduPCS-Go/wiki/iOS-%E8%BF%90%E8%A1%8C%E6%9C%AC%E9%A1%B9%E7%9B%AE%E7%A8%8B%E5%BA%8F%E5%8F%82%E8%80%83%E7%A4%BA%E4%BE%8B), 有兴趣的可以参考一下. 具体使用方法请参见 [命令列表及说明](#命令列表及说明) 和 [初级使用教程](#初级使用教程). # 命令列表及说明 ## 注意 ! ! ! 命令的前缀 `BaiduPCS-Go` 为指向程序运行的全路径名 (ARGv 的第一个参数) 直接运行程序时, 未带任何其他参数, 则程序进入cli交互模式, 运行以下命令时, 要把命令的前缀 `BaiduPCS-Go` 去掉! cli交互模式已支持按tab键自动补全命令和路径. ## 检测程序更新 ``` BaiduPCS-Go update ``` ## 登录百度帐号 ### 常规登录百度帐号 支持在线验证绑定的手机号或邮箱, 注: 此方式已长期不维护, 建议使用其他登录方式 ``` BaiduPCS-Go login ``` ### 使用百度 BDUSS 和 百度网盘 STOKEN 来登录百度账号 [关于 获取百度 BDUSS](https://blog.csdn.net/ykiwmy/article/details/103730962) STOKEN 获取方式与 BDUSS 基本相同。注意 STOKEN 必须在百度网盘页面获取，否则无效. STOKEN是cookie中的一个字段, 注意不是bdstoken, 如果拿到的STOKEN里没有大写字母多半是拿错了 ``` BaiduPCS-Go login -bduss= -stoken= ``` ### 使用百度 Cookies 来登录百度账号(推荐) [关于 获取百度 Cookies](https://jingyan.baidu.com/article/5553fa829a6a9e65a23934b0.html) 教程中为百度经验的Cookies获取, 这里换成百度网盘首页即可. ``` BaiduPCS-Go login -cookies= ``` #### 例子 ``` BaiduPCS-Go login -bduss=1234567 -stoken=234567 ``` ``` BaiduPCS-Go login # 交互式login已不再维护，不推荐使用 请输入百度用户名(手机号/邮箱/用户名), 回车键提交 > 1234567 ``` ``` BaiduPCS-Go login -cookies="BAIDUID=50949C0890YG9735EA6Q3870AFE38:FG=1; BIDUPSID=112335C0ACCAFFJW675EA69A870AFE38; PSTM=1981928511; BDORZ=D6745EBF6F3SW24E515D22A1598; PANWEB=1; BDUSS=ASAYUGFHSTFKGBGSU; STOKEN=gfsdge9gisfgspig34254d7879eee5756b10sgeyrw5vyw342td510ffc9414d32251; SCRC=cwrywec5evyetra26bvvehefvfg6a8; BDCLND=C%4sfgGysrZ%2BML6; PANPSC=wreyewygdfhdggedhsdfg4353" ``` ## 列出帐号列表 ``` BaiduPCS-Go loglist ``` 列出所有已登录的百度帐号 ## 获取当前帐号 ``` BaiduPCS-Go who ``` ## 切换百度帐号 切换已登录的百度帐号 ``` BaiduPCS-Go su ``` ``` BaiduPCS-Go su 请输入要切换帐号的 # 值 > ``` ## 退出百度帐号 退出当前登录的百度帐号 ``` BaiduPCS-Go logout ``` 程序会进一步确认退出帐号, 防止误操作. ## 获取网盘配额 ``` BaiduPCS-Go quota ``` 获取网盘的总储存空间, 和已使用的储存空间 ## 切换工作目录 ``` BaiduPCS-Go cd <目录> ``` ### 切换工作目录后自动列出工作目录下的文件和目录 ``` BaiduPCS-Go cd -l <目录> ``` #### 例子 ``` # 切换 /我的资源 工作目录 BaiduPCS-Go cd /我的资源 # 切换 上级目录 BaiduPCS-Go cd .. # 切换 根目录 BaiduPCS-Go cd / # 切换 /我的资源 工作目录, 并自动列出 /我的资源 下的文件和目录 BaiduPCS-Go cd -l 我的资源 # 使用通配符 BaiduPCS-Go cd /我的* ``` ## 输出工作目录 ``` BaiduPCS-Go pwd ``` ## 列出目录 列出当前工作目录的文件和目录或指定目录 ``` BaiduPCS-Go ls ``` ``` BaiduPCS-Go ls <目录> ``` ### 可选参数 ``` -asc: 升序排序 -desc: 降序排序 -time: 根据时间排序 -name: 根据文件名排序 -size: 根据大小排序 ``` #### 例子 ``` # 列出 我的资源 内的文件和目录 BaiduPCS-Go ls 我的资源 # 绝对路径 BaiduPCS-Go ls /我的资源 # 降序排序 BaiduPCS-Go ls -desc 我的资源 # 按文件大小降序排序 BaiduPCS-Go ls -size -desc 我的资源 # 使用通配符 BaiduPCS-Go ls /我的* ``` ## 列出目录树形图 列出当前工作目录的文件和目录或指定目录的树形图 ``` BaiduPCS-Go tree <目录> # 默认获取工作目录元信息 BaiduPCS-Go tree ``` ## 获取文件/目录的元信息 ``` BaiduPCS-Go meta <文件/目录1> <文件/目录2> <文件/目录3> ... # 默认获取工作目录元信息 BaiduPCS-Go meta ``` #### 例子 ``` BaiduPCS-Go meta 我的资源 BaiduPCS-Go meta / ``` ## 搜索文件 按文件名搜索文件（不支持查找目录）。 默认在当前工作目录搜索. ``` BaiduPCS-Go search [-path=<需要检索的目录>] [-r] <关键字> ``` #### 例子 ``` # 搜索根目录的文件 BaiduPCS-Go search -path=/ 关键字 # 搜索当前工作目录的文件 BaiduPCS-Go search 关键字 # 递归搜索当前工作目录的文件 BaiduPCS-Go search -r 关键字 ``` ## 下载文件/目录 ``` BaiduPCS-Go download <网盘文件或目录的路径1> <文件或目录2> <文件或目录3> ... BaiduPCS-Go d <网盘文件或目录的路径1> <文件或目录2> <文件或目录3> ... ``` ### 可选参数 ``` --test 测试下载, 此操作不会保存文件到本地 --ow overwrite, 覆盖已存在的文件 --status 输出所有线程的工作状态 --save 将下载的文件直接保存到当前工作目录 --saveto value 将下载的文件直接保存到指定的目录 -x 为文件加上执行权限, (windows系统无效) --mode value 下载模式, 可选值: pcs, stream, locate, 默认为 locate, 相关说明见上面的帮助 (default: "locate") -p value 指定下载线程数 (default: 0) -l value 指定同时进行下载文件的数量 (default: 0) --retry value 下载失败最大重试次数 (default: 3) --nocheck 下载文件完成后不校验文件 ``` 下载的文件默认保存到 **程序所在目录** 的 download/ 目录, 支持设置指定目录, 重名的文件会自动跳过! 下载的文件默认保存到, **程序所在目录**的 **download/** 目录. 通过 `BaiduPCS-Go config set -savedir `, 自定义保存的目录. 支持多个文件或目录下载. 自动跳过下载重名的文件! #### 例子 ``` # 设置保存目录, 保存到 D:\Downloads # 注意区别反斜杠 "\" 和 斜杠 "/" !!! BaiduPCS-Go config set -savedir D:/Downloads # 下载 /我的资源/1.mp4 BaiduPCS-Go d /我的资源/1.mp4 # 下载 /我的资源 整个目录!! BaiduPCS-Go d /我的资源 # 下载网盘内的全部文件!! BaiduPCS-Go d / BaiduPCS-Go d * ``` ## 上传文件/目录 ``` BaiduPCS-Go upload <本地文件/目录的路径1> <文件/目录2> <文件/目录3> ... <目标目录> BaiduPCS-Go u <本地文件/目录的路径1> <文件/目录2> <文件/目录3> ... <目标目录> ``` * 上传默认采用分片上传的方式, 上传的文件将会保存到, <目标目录>. 不支持断点续传 * 遇到同名文件会自动跳过, 也可配置`upload_policy`选择覆盖或者只跳过同大小文件 * 当上传的文件名和网盘的目录名称相同时, 不会覆盖目录, 防止丢失数据. * 所有上传均默认检测秒传, 可添加参数`--norapid`跳过 #### 例子: ``` # 将本地的 C:\Users\Administrator\Desktop\1.mp4 上传到网盘 /视频 目录 # 注意区别反斜杠 "\" 和 斜杠 "/" !!! BaiduPCS-Go upload C:/Users/Administrator/Desktop/1.mp4 /视频 # 将本地的 C:\Users\Administrator\Desktop\1.mp4 上传到网盘 /视频 目录, 不检测秒传 BaiduPCS-Go upload C:/Users/Administrator/Desktop/1.mp4 /视频 --norapid # 将本地的 C:\Users\Administrator\Desktop\1.mp4 和 C:\Users\Administrator\Desktop\2.mp4 上传到网盘 /视频 目录 BaiduPCS-Go upload C:/Users/Administrator/Desktop/1.mp4 C:/Users/Administrator/Desktop/2.mp4 /视频 # 将本地的 C:\Users\Administrator\Desktop 整个目录上传到网盘 /视频 目录, 只覆盖与本地大小不同的同名文件 BaiduPCS-Go upload C:/Users/Administrator/Desktop /视频 --policy rsync ``` ## 获取下载直链 ``` BaiduPCS-Go locate <文件1> <文件2> ... ``` #### 例子: ``` BaiduPCS-Go config set -user_agent "netdisk;2.2.51.6;netdisk;10.0.63;PC;android-android" ``` ## 导出文件/目录 ``` BaiduPCS-Go export <文件/目录1> <文件/目录2> ... BaiduPCS-Go ep <文件/目录1> <文件/目录2> ... ``` 导出网盘内的文件或目录, 原理为秒传文件, 此操作会生成导出文件或目录的命令. #### 注意 **秒传已不被支持, 该功能已无实际作用** #### 例子: ``` # 导出当前工作目录: BaiduPCS-Go export # 导出所有文件和目录, 并设置新的根目录为 /root BaiduPCS-Go export -root=/root / # 导出 /我的资源 BaiduPCS-Go export /我的资源 # 导出 /我的资源 格式为通用秒传链接格式 BaiduPCS-Go export /我的资源 --link ``` ## 创建目录 ``` BaiduPCS-Go mkdir <目录> ``` #### 例子 ``` BaiduPCS-Go mkdir 123 ``` ## 删除文件/目录 ``` BaiduPCS-Go rm <网盘文件或目录的路径1> <文件或目录2> <文件或目录3> ... ``` 注意: 删除多个文件和目录时, 请确保每一个文件和目录都存在, 否则删除操作会失败. 被删除的文件或目录可在网盘文件回收站找回. #### 例子 ``` # 删除 /我的资源/1.mp4 BaiduPCS-Go rm /我的资源/1.mp4 # 删除 /我的资源/1.mp4 和 /我的资源/2.mp4 BaiduPCS-Go rm /我的资源/1.mp4 /我的资源/2.mp4 # 删除 /我的资源 内的所有文件和目录, 但不删除该目录 BaiduPCS-Go rm /我的资源/* # 删除 /我的资源 整个目录 !! BaiduPCS-Go rm /我的资源 ``` ## 拷贝文件/目录 ``` BaiduPCS-Go cp <文件/目录> <目标 文件/目录> BaiduPCS-Go cp <文件/目录1> <文件/目录2> <文件/目录3> ... <目标目录> ``` 注意: 拷贝多个文件和目录时, 请确保每一个文件和目录都存在, 否则拷贝操作会失败. #### 例子 ``` # 将 /我的资源/1.mp4 复制到 根目录 / BaiduPCS-Go cp /我的资源/1.mp4 / # 将 /我的资源/1.mp4 和 /我的资源/2.mp4 复制到 根目录 / BaiduPCS-Go cp /我的资源/1.mp4 /我的资源/2.mp4 / ``` ## 移动/重命名文件/目录 ``` # 移动: BaiduPCS-Go mv <文件/目录1> <文件/目录2> <文件/目录3> ... <目标目录> # 重命名: BaiduPCS-Go mv <文件/目录> <重命名的文件/目录> ``` 注意: 移动多个文件和目录时, 请确保每一个文件和目录都存在, 否则移动操作会失败. #### 例子 ``` # 将 /我的资源/1.mp4 移动到 根目录 / BaiduPCS-Go mv /我的资源/1.mp4 / # 将 /我的资源/1.mp4 重命名为 /我的资源/3.mp4 BaiduPCS-Go mv /我的资源/1.mp4 /我的资源/3.mp4 ``` ## 转存文件/目录 ``` # 转存分享链接里的文件到当前目录: BaiduPCS-Go transfer <分享链接> <提取码> ``` 注意: 转存文件保存到当前工作目录下, 不支持指定. #### 例子 ``` # 将 https://pan.baidu.com/s/12L_ZZVNxz5f_2CccoyyVrW (提取码edv4) 转存到当前目录 BaiduPCS-Go transfer https://pan.baidu.com/s/12L_ZZVNxz5f_2CccoyyVrW edv4 BaiduPCS-Go transfer https://pan.baidu.com/s/12L_ZZVNxz5f_2CccoyyVrW?pwd=edv4 ``` ## 分享文件/目录 ``` BaiduPCS-Go share ``` ### 设置分享文件/目录 ``` BaiduPCS-Go share set <文件/目录1> <文件/目录2> ... BaiduPCS-Go share s <文件/目录1> <文件/目录2> ... ``` ### 列出已分享文件/目录 ``` BaiduPCS-Go share list BaiduPCS-Go share l ``` ### 取消分享文件/目录 ``` BaiduPCS-Go share cancel ... BaiduPCS-Go share c ... ``` 目前只支持通过分享id (shareid) 来取消分享. ## 离线下载 ``` BaiduPCS-Go offlinedl BaiduPCS-Go clouddl BaiduPCS-Go od ``` 离线下载支持http/https/ftp/电驴/磁力链协议 离线下载同时进行的任务数量有限, 超出限制的部分将无法添加. ### 添加离线下载任务 ``` BaiduPCS-Go offlinedl add -path=<离线下载文件保存的路径> 资源地址1 地址2 ... ``` 添加任务成功之后, 返回离线下载的任务ID. ### 精确查询离线下载任务 ``` BaiduPCS-Go offlinedl query 任务ID1 任务ID2 ... ``` ### 查询离线下载任务列表 ``` BaiduPCS-Go offlinedl list ``` ### 取消离线下载任务 ``` BaiduPCS-Go offlinedl cancel 任务ID1 任务ID2 ... ``` ### 删除离线下载任务 ``` BaiduPCS-Go offlinedl delete 任务ID1 任务ID2 ... # 清空离线下载任务记录, 程序不会进行二次确认, 谨慎操作!!! BaiduPCS-Go offlinedl delete -all ``` #### 例子 ``` # 将百度和腾讯主页, 离线下载到根目录 / BaiduPCS-Go offlinedl add -path=/ http://baidu.com http://qq.com # 添加磁力链接任务 BaiduPCS-Go offlinedl add magnet:?xt=urn:btih:xxx # 查询任务ID为 12345 的离线下载任务状态 BaiduPCS-Go offlinedl query 12345 # 取消任务ID为 12345 的离线下载任务 BaiduPCS-Go offlinedl cancel 12345 ``` ## 回收站 ``` BaiduPCS-Go recycle ``` 回收站操作. ### 列出回收站文件列表 ``` BaiduPCS-Go recycle list ``` #### 可选参数 ``` --page value 回收站文件列表页数 (default: 1) ``` ### 还原回收站文件或目录 ``` BaiduPCS-Go recycle restore ... ``` 根据文件/目录的 fs_id, 还原回收站指定的文件或目录. ### 删除回收站文件或目录/清空回收站 ``` BaiduPCS-Go recycle delete [-all] ... ``` 根据文件/目录的 fs_id 或 -all 参数, 删除回收站指定的文件或目录或清空回收站. #### 例子 ``` # 从回收站还原两个文件, 其中的两个文件的 fs_id 分别为 1013792297798440 和 643596340463870 BaiduPCS-Go recycle restore 1013792297798440 643596340463870 # 从回收站删除两个文件, 其中的两个文件的 fs_id 分别为 1013792297798440 和 643596340463870 BaiduPCS-Go recycle delete 1013792297798440 643596340463870 # 清空回收站, 程序不会进行二次确认, 谨慎操作!!! BaiduPCS-Go recycle delete -all ``` ## 显示程序环境变量 ``` BaiduPCS-Go env ``` BAIDUPCS_GO_CONFIG_DIR: 配置文件路径, BAIDUPCS_GO_VERBOSE: 是否启用调试. ## 显示和修改程序配置项 ``` # 显示配置 BaiduPCS-Go config # 设置配置 BaiduPCS-Go config set ``` 注意: v3.5 以后, 程序对配置文件储存路径的寻找做了调整, 配置文件所在的目录可以是程序本身所在目录, 也可以是家目录. 配置文件所在的目录为家目录的情况: Windows: `%APPDATA%\BaiduPCS-Go` 其他操作系统: `$HOME/.config/BaiduPCS-Go` 可通过设置环境变量 `BAIDUPCS_GO_CONFIG_DIR`, 指定配置文件存放的目录. 谨慎修改 `appid`, `user_agent`, `pcs_ua`, `pan_ua` 的值, 否则访问网盘服务器时, 可能会出现错误. 如上传遇到异常可尝试修改 `pcs_addr`, 目前已知的地址有: ``` pcs.baidu.com c.pcs.baidu.com c2.pcs.baidu.com c3.pcs.baidu.com c4.pcs.baidu.com c5.pcs.baidu.com d.pcs.baidu.com ``` v3.9.8后上传时支持动态获取pcs服务器, 理论上不需要手动配置. 如希望使用静态pcs服务器, 可配置打开`fix_pcs_addr` `cache_size` 的值支持可选设置单位了, 单位不区分大小写, `b` 和 `B` 均表示字节的意思, 如 `64KB`, `1MB`, `32kb`, `65536b`, `65536`. `max_download_rate`, `max_upload_rate` 的值支持可选设置单位了, 单位为每秒的传输速率, 后缀`/s` 可省略, 如 `2MB/s`, `2MB`, `2m`, `2mb` 均为一个意思. 普通用户请将`max_parallel`和`max_download_load`都设置为1, 调大线程数只会在短时间内提升下载速度, 且极易很快触发限速, 导致几小时至几天内账号在各客户端都接近0速. 本软件不支持普通用户提速. SVIP用户建议`max_parallel`设置为10以上, 根据实际带宽可调大, 但不建议超过20, `max_download_load`设置为1 - 2, 实验表明可以稳定满速下载. #### 例子 ``` # 显示所有可以设置的值 BaiduPCS-Go config -h BaiduPCS-Go config set -h # 设置下载文件的储存目录 BaiduPCS-Go config set -savedir D:/Downloads # 设置下载最大并发量为 15 BaiduPCS-Go config set -max_parallel 15 # 组合设置 BaiduPCS-Go config set -max_parallel 150 -savedir D:/Downloads ``` ## 测试通配符 ``` BaiduPCS-Go match <通配符表达式> ``` 测试通配符匹配路径, 操作成功则输出所有匹配到的路径. #### 例子 ``` # 匹配 /我的资源 目录下所有mp4格式的文件 BaiduPCS-Go match /我的资源/*.mp4 ``` ## 工具箱 ``` BaiduPCS-Go tool ``` 目前工具箱支持加解密文件等. # 初级使用教程 新手建议: **双击运行程序**, 进入仿 Linux shell 的 cli 交互模式; cli交互模式下, 光标所在行的前缀应为 `BaiduPCS-Go >`, 如果登录了百度帐号则格式为 `BaiduPCS-Go:<工作目录> <百度ID>$ ` 以下例子的命令, 均为 cli交互模式下的命令 运行命令的正确操作: **输入命令, 按一下回车键 (键盘上的 Enter 键)**, 程序会接收到命令并输出结果 ## 1. 查看程序使用说明 cli交互模式下, 运行命令 `help` ## 2. 登录百度帐号 (必做) cli交互模式下, 运行命令 `login -h` (注意空格) 查看帮助 cli交互模式下, 运行命令 `login` 程序将会提示你输入百度用户名(手机号/邮箱/用户名)和密码, 必要时还可以在线验证绑定的手机号或邮箱 ## 3. 切换网盘工作目录 cli交互模式下, 运行命令 `cd /我的资源` 将工作目录切换为 `/我的资源` (前提: 该目录存在于网盘) 目录支持通配符匹配, 所以你也可以这样: 运行命令 `cd /我的*` 或 `cd /我的??` 将工作目录切换为 `/我的资源`, 简化输入. 将工作目录切换为 `/我的资源` 成功后, 运行命令 `cd ..` 切换上级目录, 即将工作目录切换为 `/` 为什么要这样设计呢, 举个例子, 假设 你要下载 `/我的资源` 内名为 `1.mp4` 和 `2.mp4` 两个文件, 而未切换工作目录, 你需要依次运行以下命令: ``` d /我的资源/1.mp4 d /我的资源/2.mp4 ``` 而切换网盘工作目录之后, 依次运行以下命令: ``` cd /我的资源 d 1.mp4 d 2.mp4 ``` 这样就达到了简化输入的目的 ## 4. 网盘内列出文件和目录 cli交互模式下, 运行命令 `ls -h` (注意空格) 查看帮助 cli交互模式下, 运行命令 `ls` 来列出当前所在目录的文件和目录 cli交互模式下, 运行命令 `ls /我的资源` 来列出 `/我的资源` 内的文件和目录 cli交互模式下, 运行命令 `ls ..` 来列出当前所在目录的上级目录的文件和目录 ## 5. 下载文件 说明: 下载的文件默认保存到 download/ 目录 (文件夹) cli交互模式下, 运行命令 `d -h` (注意空格) 查看帮助 cli交互模式下, 运行命令 `d /我的资源/1.mp4` 来下载位于 `/我的资源/1.mp4` 的文件 `1.mp4` , 该操作等效于运行以下命令: ``` cd /我的资源 d 1.mp4 ``` 现在已经支持目录 (文件夹) 下载, 所以, 运行以下命令, 会下载 `/我的资源` 内的所有文件 (违规文件除外): ``` d /我的资源 ``` ## 6. 设置下载最大并发量 cli交互模式下, 运行命令 `config set -h` (注意空格) 查看设置帮助以及可供设置的值 cli交互模式下, 运行命令 `config set -max_parallel 2` 将下载最大并发量设置为 2 注意：普通用户下载最大并发量的值超过1将导致账号被限速; SVIP同样不宜设置过高, 建议10~20 ## 7. 恢复默认配置 cli交互模式下, 运行命令 `config reset` ## 8. 退出程序 运行命令 `quit` 或 `exit` 或 组合键 `Ctrl+C` 或 组合键 `Ctrl+D` # 已知问题 * 分片上传文件时, 当文件分片数大于1, 网盘端最终计算所得的md5值和本地的不一致, 这可能是百度网盘的bug, 测试把上传的文件下载到本地后，对比md5值是匹配的. 可通过秒传的原理来修复md5值. * 开启MD5校验下载时可能有 check MD5 不通过, 但文件其实并未出错的情况, 使用--no-check下载或配置中启用no_check即可(3.7版本默认已启用). * 用户名登录时图片验证码至少要输入两次, 第一次的输入无效 * 登录出现手机/邮箱验证时要输入至少4次图片验证码 # TODO * 转存文件数量绕过单次限制 # 交流反馈 提交Issue: [Issues](https://github.com/qjfoidnh/BaiduPCS-Go/issues) --- ## File: docs/file_data_apis_error.md # 文件数据API错误码 | HTTP状态码 | 错误码 | 错误信息 | 备注 | | :- | -: | :- | :- | | 200 | 0 | no error | 没有错误 | | 400 | 3 | Unsupported open api | 不支持此接口 | | 403 | 4 | No permission to do this operation | 没有权限执行此操作 | | 403 | 5 | Unauthorized client IP address | IP未授权 | | 503 | 31001 | db query error | 数据库查询错误 | | 503 | 31002 | db connect error | 数据库连接错误 | | 503 | 31003 | db result set is empty | 数据库返回空结果 | | 503 | 31021 | network error | 网络错误 | | 503 | 31022 | can not access server | 暂时无法连接服务器 | | 400 | 31023 | param error | 输入参数错误 | | 400 | 31024 | app id is empty | app id为空 | | 503 | 31025 | bcs error | 后端存储错误 | | 403 | 31041 | bduss is invalid | 用户的cookie不是合法的百度cookie | | 403 | 31042 | user is not login | 用户未登陆 | | 403 | 31043 | user is not active | 用户未激活 | | 403 | 31044 | user is not authorized | 用户未授权 | | 403 | 31045 | user not exists | 用户不存在 | | 403 | 31046 | user already exists | 用户已经存在 | | 400 | 31061 | file already exists | 文件已经存在 | | 400 | 31062 | file name is invalid | 文件名非法 | | 400 | 31063 | file parent path does not exist | 文件父目录不存在 | | 403 | 31064 | file is not authorized | 无权访问此文件 | | 400 | 31065 | directory is full | 目录已满 | | 403 | 31066 | file does not exist | 文件不存在 | | 503 | 31067 | file deal failed | 文件处理出错 | | 503 | 31068 | file create failed | 文件创建失败 | | 503 | 31069 | file copy failed | 文件拷贝失败 | | 503 | 31070 | file delete failed | 文件删除失败 | | 503 | 31071 | get file meta failed | 不能读取文件元信息 | | 503 | 31072 | file move failed | 文件移动失败 | | 503 | 31073 | file rename failed | 文件重命名失败 | | 503 | 31081 | superfile create failed | superfile创建失败 | | 503 | 31082 | superfile block list is empty | superfile 块列表为空 | | 503 | 31083 | superfile update failed | superfile 更新失败 | | 503 | 31101 | tag internal error | tag系统内部错误 | | 503 | 31102 | tag param error | tag参数错误 | | 503 | 31103 | tag database error | tag系统错误 | | 403 | 31110 | access denied to set quota | 未授权设置此目录配额 | | 400 | 31111 | quota only sopport 2 level directories | 配额管理只支持两级目录 | | 400 | 31112 | exceed quota | 超出配额 | | 403 | 31113 | the quota is bigger than one of its parent directories | 配额不能超出目录祖先的配额 | | 403 | 31114 | the quota is smaller than one of its sub directories | 配额不能比子目录配额小 | | 503 | 31141 | thumbnail failed, internal error | 请求缩略图服务失败 | | 401 | 110 | Access token invalid or no longer valid | Access Token不正确或者已经过期 | | 400 | 31201 | signature error | 签名错误 | | 400 | 31203 | acl put error | 设置acl失败 | | 400 | 31204 | acl query error | 请求acl验证失败 | | 400 | 31205 | acl get error | 获取acl失败 | | 404 | 31079 | File md5 not found, you should use upload API to upload the whole file. | 未找到文件MD5 |，| 请使用上传API上传整个文件。 | | 404 | 31202 | object not exists | 文件不存在 | | 404 | 31206 | acl get error | acl不存在 | | 400 | 31207 | bucket already exists | bucket已存在 | | 400 | 31208 | bad request | 用户请求错误 | | 500 | 31209 | baidubs internal error | 服务器错误 | | 501 | 31210 | not implement | 服务器不支持 | | 403 | 31211 | access denied | 禁止访问 | | 503 | 31212 | service unavailable | 服务不可用 | | 503 | 31213 | service unavailable | 重试出错 | | 503 | 31214 | put object data error | 上传文件data失败 | | 503 | 31215 | put object meta error | 上传文件meta失败 | | 503 | 31216 | get object data error | 下载文件data失败 | | 503 | 31217 | get object meta error | 下载文件meta失败 | | 403 | 31218 | storage exceed limit | 容量超出限额 | | 403 | 31219 | request exceed limit | 请求数超出限额 | | 403 | 31220 | transfer exceed limit | 流量超出限额 | | 500 | 31298 | the value of KEY[VALUE] in pcs response headers is invalid | 服务器返回值KEY非法 | | 500 | 31299 | no KEY in pcs response headers | 服务器返回值KEY不存在 | --- ## File: docs/file_data_apis_list.md # 文件API列表 ## 更新通知： * 2013.6.20 上传、下载新域名正式上线使用，相关接口“上传单个文件”、“分片上传-文件分片上传”、“下载单个文件”及“下载流式文件”相关接口信息更新 * 2013.3.20 去除API权限申请开通相关说明，开发者可通过“管理中心”自行开启。 * 2013.3.1 新增“回收站功能”，新增“还原单个文件或目录”、“还原多个文件或目录”、“获取回收站文件或目录列表”及“清空回收站”等接口 ## 基本功能 ### 空间配额信息 #### 功能 获取当前用户空间配额信息。 #### HTTP请求方式 GET #### URL https://pcs.baidu.com/rest/2.0/pcs/quota #### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | method | string | 是 | 固定值：info。 | | access_token | string | 是 | 开发者准入标识，HTTPS调用时必须使用。 | #### 返回参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | quota | uint64 | 是 | 空间配额，单位为字节。 | | used | uint64 | 是 | 已使用空间大小，单位为字节。 | #### 示例 ##### 请求示例 GET https://pcs.baidu.com/rest/2.0/pcs/quota?method=info&access_token=1.54be391000a16ee6a21791d4a8ea04fe.86400.1331206383.67272939-188383 ##### 响应示例 { "quota":15000000000, "used":5221166, "request_id":4043312634 } ### 上传单个文件 #### 功能 上传单个文件。 百度PCS服务目前支持最大2G的单个文件上传。 如需支持超大文件（>2G）的断点续传，请参考下面的“分片文件上传”方法。 #### HTTP请求方式 POST #### URL https://pcs.baidu.com/rest/2.0/pcs/file #### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | method | string | 是 | 固定值：upload。 | | access_token | string | 是 | 开发者准入标识，HTTPS调用时必须使用。 | | path | string | 是 | 上传文件路径（含上传的文件名称)。注意： * 路径长度限制为1000 * 路径中不能包含以下字符：\\ ? \| " > < : * * 文件名或路径名开头结尾不能是“.”或空白字符，空白字符包括: \r, \n, \t, 空格, \0, \x0B| | file | char[] | 是 | 上传文件的内容。 | | ondup | string | 是 | * overwrite：表示覆盖同名文件； * newcopy：表示生成文件副本并进行重命名，命名规则为“文件名_日期.后缀”。 | #### 返回参数 | 参数名称 | 类型 | UrlEncode | 描述 | | :- | :-: | :-: | :- | | path | string | 是 | 该文件的绝对路径。 | | size | uint64 | 否 | 文件字节大小。 | | ctime | uint64 | 否 | 文件创建时间。 | | mtime | uint64 | 否 | 文件修改时间。 | | md5 | string | 否 | 文件的md5签名。 | | fs_id | uint64 | 否 | 文件在PCS的临时唯一标识ID。 | #### 示例 ##### 请求示例 POST https://pcs.baidu.com/rest/2.0/pcs/file?method=upload&path=%2fapps%2falbum%2f1.JPG&access_token=b778fb598c717c0ad7ea8c97c8f3a46f ##### 响应示例 { 　 "path" : "/apps/album/1.jpg", 　 "size" : 372121, 　 "ctime" : 1234567890, 　 "mtime" : 1234567890, 　 "md5" : "cb123afcc12453543ef", 　 "fs_id" : 12345, 　"request_id":4043312669 } ### 分片上传—文件分片及上传 #### 功能 百度PCS服务支持每次直接上传最大2G的单个文件。 如需支持上传超大文件（>2G），则可以通过组合调用分片文件上传的upload方法和createsuperfile方法实现： 首先，将超大文件分割为2G以内的单文件，并调用upload将分片文件依次上传； 其次，调用createsuperfile，完成分片文件的重组。 除此之外，如果应用中需要支持断点续传的功能，也可以通过分片上传文件并调用createsuperfile接口的方式实现。 #### HTTP请求方式 POST #### URL https://pcs.baidu.com/rest/2.0/pcs/file #### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | method | string | 是 | 固定值：upload。 | | access_token | string | 是 | 开发者准入标识，HTTPS调用时必须使用。 | | type | string | 是 | 固定值，tmpfile。 | | file | char[] | 是 | 上传文件的内容。 | #### 返回参数 | 参数名称 | 类型 | UrlEncode | 描述 | | :- | :-: | :-: | :- | | md5 | string | 否 | 文件的md5签名。 | #### 示例 ##### 请求示例 POST https://pcs.baidu.com/rest/2.0/pcs/file?method=upload&access_token=1.54bef000f2416ee4a41791d4a8ea04fe.86400.1331206383.67272939-188383&type=tmpfile ##### 响应示例 { "md5":"a7619410bca74850f985e488c9a0d51e", "request_id":3238563823 } ### 分片上传—合并分片文件 #### 功能 与分片文件上传的upload方法配合使用，可实现超大文件（>2G）上传，同时也可用于断点续传的场景。 #### HTTP请求方式 POST #### URL https://pcs.baidu.com/rest/2.0/pcs/file #### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | method | string | 是 | 固定值：createsuperfile。 | | access_token | string | 是 | 开发者准入标识，HTTPS调用时必须使用。 | | path | string | 是 | 上传文件路径（含上传的文件名称)。注意： * 路径长度限制为1000 * 路径中不能包含以下字符：\\ ? \| " > < : * * 文件名或路径名开头结尾不能是“.”或空白字符，空白字符包括: \r, \n, \t, 空格, \0, \x0B| | param | string | 是 | block_list数组，数组的取值为子文件内容的MD5；子文件至少两个，最多1024个。 *本参数必须放在Http Body中进行传输，value示例： {"block_list":["d41d8cd98f00b204e9800998ecf8427e","89dfb274b42951b973fc92ee7c252166","1c83fe229cb9b1f6116aa745b4ef3c0d"]} | | ondup | string | 是 | * overwrite：表示覆盖同名文件； * newcopy：表示生成文件副本并进行重命名，命名规则为“文件名_日期.后缀”。 | #### 返回参数 | 参数名称 | 类型 | UrlEncode | 描述 | | :- | :-: | :-: | :- | | path | string | 是 | 该文件的绝对路径。 | | size | uint64 | 否 | 文件大小（以字节为单位）。 | | ctime | uint64 | 否 | 文件创建时间。 | | mtime | uint64 | 否 | 文件修改时间。 | | md5 | string | 否 | 文件的md5签名。 | | fs_id | uint64 | 否 | 文件在PCS的临时唯一标识ID。 | #### 示例 ##### 请求示例 POST https://pcs.baidu.com/rest/2.0/file?method=createsuperfile&path=%2fapps%2fyunform%2f6ddddd.JPG&access_token=1.9fb09e8cce44c0d000e6787138924a26.86400.1331273905.2600617452-188383 ##### 响应示例 { "path":"/apps/yunform/6ddddd.JPG", "size":6844, "ctime":1331197101, "mtime":1331197101, "md5":"baa7c379639b74e9bf98c807498e1b64", "fs_id":1548308694, "request_id":4043313276 } ### 下载单个文件 #### 功能 下载单个文件。 Download接口支持HTTP协议标准range定义，通过指定range的取值可以实现断点下载功能。 例如： 如果在request消息中指定“Range: bytes=0-99”，那么响应消息中会返回该文件的前100个字节的内容；继续指定“Range: bytes=100-199”，那么响应消息中会返回该文件的第二个100字节内容。 #### HTTP请求方式 GET #### URL https://pcs.baidu.com/rest/2.0/pcs/file #### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | method | string | 是 | 固定值：download。 | | access_token | string | 是 | 开发者准入标识，HTTPS调用时必须使用。 | | path | string | 是 | 下载文件路径，以/开头的绝对路径。注意： * 路径长度限制为1000 * 路径中不能包含以下字符：\\ ? \| " > < : * * 文件名或路径名开头结尾不能是“.”或空白字符，空白字符包括: \r, \n, \t, 空格, \0, \x0B| #### 返回参数 无 #### 示例 ##### 请求示例 GET https://pcs.baidu.com/rest/2.0/pcs/file?method=download&access_token=3.d9000194f4b5d2da3fe8b6f850ace082.2592000.1348645419.2233553628-248414&path=%2Fapps%2F%E6%B5%8B%E8%AF%95%E5%BA%94%E7%94%A8%2F%2F01.jpg ##### 响应示例 文件内容 ### 创建目录 #### 功能 为当前用户创建一个目录。 #### HTTP请求方式 POST #### URL https://pcs.baidu.com/rest/2.0/pcs/file #### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | method | string | 是 | 固定值：mkdir。 | | access_token | string | 是 | 开发者准入标识，HTTPS调用时必须使用。 | | path | string | 是 | 需要创建的目录，以/开头的绝对路径。注意： * 路径长度限制为1000 * 路径中不能包含以下字符：\\ ? \| " > < : * * 文件名或路径名开头结尾不能是“.”或空白字符，空白字符包括: \r, \n, \t, 空格, \0, \x0B| #### 返回参数 | 参数名称 | 类型 | UrlEncode | 描述 | | :- | :-: | :-: | :- | | fs_id | uint64 | 否 | 目录在PCS的临时唯一标识id。 | | path | string | 否 | 该目录的绝对路径。 | | ctime | uint64 | 否 | 目录创建时间。 | | mtime | uint64 | 否 | 目录修改时间。 | #### 示例 ##### 请求示例 POST https://pcs.baidu.com/rest/2.0/pcs/file?method=mkdir&access_token=1.54bef000f2416ee4a41791d4a8ea04fe.86400.1331206383.67272939-188383&path=%2Fapps%2Fyunform%2Fmusic ##### 响应示例 { "fs_id":1636599174, "path":"/apps/yunfom/music", "ctime":1331183814, "mtime":1331183814, "request_id":4043312656 } ### 获取单个文件/目录的元信息 #### 功能 获取单个文件或目录的元信息。 #### HTTP请求方式 GET #### URL https://pcs.baidu.com/rest/2.0/pcs/file #### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | method | string | 是 | 固定值：meta。 | | access_token | string | 是 | 开发者准入标识，HTTPS调用时必须使用。 | | path | string | 是 | 需要获取文件属性的目录，以/开头的绝对路径。如：/apps/album/a/b/c 注意： * 路径长度限制为1000 * 路径中不能包含以下字符：\\ ? \| " > < : * * 文件名或路径名开头结尾不能是“.”或空白字符，空白字符包括: \r, \n, \t, 空格, \0, \x0B| #### 返回参数 | 参数名称 | 类型 | UrlEncode | 描述 | | :- | :-: | :-: | :- | | fs_id | uint64 | 否 | 文件或目录在PCS的临时唯一标识ID。 | | path | string | 否 | 文件或目录的绝对路径。 | | ctime | uint | 否 | 文件或目录的创建时间。 | | mtime | uint | 否 | 文件或目录的最后修改时间。 | | block_list | string | 否 | 文件所有分片的md5数组JSON字符串。 | | size | uint64 | 否 | 文件大小（byte）。 | | isdir | uint | 否 | 是否是目录的标识符： * “0”为文件 * “1”为目录 | | ifhassubdir | uint | 否 | 是否含有子目录的标识符： * “0”表示没有子目录 * “1”表示有子目录 | #### 示例 ##### 请求示例 GET https://pcs.baidu.com/rest/2.0/pcs/file?method=meta&access_token=1.5400f91df2416ee4a41791d4a8ea04fe.86400.1331206383.67272939-188383&path=%2Fapps%2Fyunform%2Fmusic%2Fhello ##### 响应示例 { "list": [{ "fs_id": 3528850315, "path": "/apps/yunform/music/hello", "ctime": 1331184269, "mtime": 1331184269, "block_list": ["59ca0efa9f5633cb0371bbc0355478d8"], "size": 13, "isdir": 1 }], "request_id": 4043312678 } ### 批量获取文件/目录的元信息 #### 功能 批量获取文件或目录的元信息。 #### HTTP请求方式 POST #### URL https://pcs.baidu.com/rest/2.0/pcs/file #### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | method | string | 是 | 固定值：meta。 | | access_token | string | 是 | 开发者准入标识，HTTPS调用时必须使用。 | | param | string | 是 | JSON字符串。 {"list":[{"path":"\/apps\/album\/a\/b\/c"},{"path":"\/apps\/album\/a\/b\/d"}]} 注意： * 路径长度限制为1000 * 路径中不能包含以下字符：\\ ? \| " > < : * * 文件名或路径名开头结尾不能是“.”或空白字符，空白字符包括: \r, \n, \t, 空格, \0, \x0B| #### 返回参数 | 参数名称 | 类型 | UrlEncode | 描述 | | :- | :-: | :-: | :- | | fs_id | uint64 | 否 | 文件或目录在PCS的临时唯一标识ID。 | | path | string | 否 | 文件或目录的绝对路径。 | | server_filename | string | 否 | 文件或目录的名称。 | | ctime | uint | 否 | 文件或目录的创建时间。 | | mtime | uint | 否 | 文件或目录的最后修改时间。 | | md5 | string | 否 | 文件的md5值。 | | block_list | string | 否 | 文件所有分片的md5数组JSON字符串。 | | size | uint64 | 否 | 文件大小（byte）。 | | isdir | uint | 否 | 是否是目录的标识符： * “0”为文件 * “1”为目录 | | ifhassubdir | uint | 否 | 是否含有子目录的标识符： * “0”表示没有子目录 * “1”表示有子目录 | #### 示例 ##### 请求示例 POST https://pcs.baidu.com/rest/2.0/pcs/file?method=meta&access_token=1.54b0091ee2416ee4a41791d4a8ea04fe.86400.1331206383.67272939-188383 ##### 响应示例 { "list": [{ "fs_id": 3528850315, "path": "/apps/album/a/b/c", "ctime": 1331184269, "mtime": 1331184269, "block_list": ["59ca0efa9f5633cb0371bbc0355478d8"], "size": 13, "isdir": 0 }, { "fs_id": 3528850320, "path": "/apps/album/a/b/d", "ctime": 1331184269, "mtime": 1331184269, "block_list": ["59ca0efa9f5633cb0371bbc0355478d8"], "size": 13, "isdir": 0 } ], "request_id": 4043312678 } ### 获取目录下的文件列表 #### 功能 获取目录下的文件列表。 #### HTTP请求方式 GET #### URL https://pcs.baidu.com/rest/2.0/pcs/file #### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | method | string | 是 | 固定值：list。 | | access_token | string | 是 | 开发者准入标识，HTTPS调用时必须使用。 | | path | string | 是 | 需要list的目录，以/开头的绝对路径。注意： * 路径长度限制为1000 * 路径中不能包含以下字符：\\ ? \| " > < : * * 文件名或路径名开头结尾不能是“.”或空白字符，空白字符包括: \r, \n, \t, 空格, \0, \x0B| | by | string | 否 | 排序字段，缺省根据文件类型排序： * time（修改时间） * name（文件名） * size（大小，注意目录无大小） | | order | string | 否 | “asc”或“desc”，缺省采用降序排序。 * asc（升序） * desc（降序） | | limit | string | 否 | 返回条目控制，参数格式为：n1-n2。 返回结果集的[n1, n2)之间的条目，缺省返回所有条目；n1从0开始。 | #### 返回参数 | 参数名称 | 类型 | UrlEncode | 描述 | | :- | :-: | :-: | :- | | fs_id | uint64 | 否 | 文件或目录在PCS的临时唯一标识ID。 | | path | string | 否 | 文件或目录的绝对路径。 | | server_filename | string | 否 | 文件或目录的名称。 | | ctime | uint | 否 | 文件或目录的创建时间。 | | mtime | uint | 否 | 文件或目录的最后修改时间。 | | md5 | string | 否 | 文件的md5值。 | | block_list | string | 否 | 文件所有分片的md5数组JSON字符串。 | | size | uint64 | 否 | 文件大小（byte）。 | | isdir | uint | 否 | 是否是目录的标识符： * “0”为文件 * “1”为目录 | #### 示例 ##### 请求示例 GET https://pcs.baidu.com/rest/2.0/pcs/file?method=list&access_token=1.54bef91002416ee4a41791d4a8ea04fe.86400.1331206383.67272939-188383&path=%2Fapps%2Fyunform%2Fhello ##### 响应示例 { "list": [{ "fs_id": 3528850315, "path": "/apps/yunform/music/hello", "ctime": 1331184269, "mtime": 1331184269, "block_list": ["59ca0efa9f5633cb0371bbc0355478d8"], "size": 13, "isdir": 0 }], "request_id": 4043312670 } ### 移动单个文件/目录 #### 功能 移动单个文件/目录。 #### HTTP请求方式 POST #### URL https://pcs.baidu.com/rest/2.0/pcs/file #### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | method | string | 是 | 固定值：move。 | | access_token | string | 是 | 开发者准入标识，HTTPS调用时必须使用。 | | from | string | 是 | 源文件地址（包括文件名）。注意： * 路径长度限制为1000 * 路径中不能包含以下字符：\\ ? \| " > < : * * 文件名或路径名开头结尾不能是“.”或空白字符，空白字符包括: \r, \n, \t, 空格, \0, \x0B| | to | string | 是 | 目标文件地址（包括文件名）。注意： * 路径长度限制为1000 * 路径中不能包含以下字符：\\ ? \| " > < : * * 文件名或路径名开头结尾不能是“.”或空白字符，空白字符包括: \r, \n, \t, 空格, \0, \x0B| #### 返回参数 如果move操作执行成功，那么response会返回执行成功的from/to列表。 | 参数名称 | 类型 | UrlEncode | 描述 | | :- | :-: | :-: | :- | | from | string | 是 | 执行move操作成功的源文件地址。 | | to | string | 是 | 执行move操作成功的目标文件地址。 | #### 示例 ##### 请求示例 POST https://pcs.baidu.com/rest/2.0/pcs/file?method=move&from=%2fapps%2f pcstest_oauth%2f test1%2fyyyytestwer.jpg&to=%2fapps%2fpcstest_oauth%2ftest2%2f2.jpg&access_token=b778fb598c717c0ad7ea8c97c8f3a46f ##### 响应示例 { "extra": { "list": [{ "to": "/apps/pcstest_oauth/test2/2.jpg", "from": "/apps/pcstest_oauth/test1/yyyytestwer.jpg" }] }, "request_id": 2298812844 } ### 批量移动文件/目录 #### 功能 批量移动文件/目录。 #### HTTP请求方式 POST #### URL https://pcs.baidu.com/rest/2.0/pcs/file #### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | method | string | 是 | 固定值：move。 | | access_token | string | 是 | 开发者准入标识，HTTPS调用时必须使用。 | | param | string | 是 | 源文件地址和目标文件地址对应的列表。 {"list":[{"from":"/apps/album/a/b/c","to":"/apps/album/b/b/c"},{"from":"/apps/album/a/b/d","to":"/apps/album/b/b/d"}]} 注意： * 路径长度限制为1000 * 路径中不能包含以下字符：\\ ? \| " > < : * * 文件名或路径名开头结尾不能是“.”或空白字符，空白字符包括: \r, \n, \t, 空格, \0, \x0B| #### 返回参数 返回参数extra由list数组组成，list数组的两个元素分别是“from”和“to”，代表move操作的源地址和目的地址。 | 参数名称 | 类型 | UrlEncode | 描述 | | :- | :-: | :-: | :- | | from | string | 是 | 执行move操作成功的源文件地址。 | | to | string | 是 | 执行move操作成功的目标文件地址。 | #### 注意 调用move接口时，目标文件的名称如果和源文件不相同，将会在move操作时对文件进行重命名。 #### 示例 ##### 请求示例 POST https://pcs.baidu.com/rest/2.0/pcs/file?method=move&from=%2fapps%2f pcstest_oauth%2f test1%2fyyyytestwer.jpg&to=%2fapps%2fpcstest_oauth%2ftest2%2f2.jpg&access_token=b778fb598c717c0ad7ea8c97c8f3a46f ##### 响应示例 { "extra": { "list": [{ "to": "/apps/pcstest_oauth/test2/2.jpg", "from": "/apps/pcstest_oauth/test1/yyyytestwer.jpg" }] }, "request_id": 2298812844 } ### 拷贝单个文件/目录 #### 功能 拷贝文件(目录)。 #### HTTP请求方式 POST #### URL https://pcs.baidu.com/rest/2.0/pcs/file #### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | method | string | 是 | 固定值：copy。 | | access_token | string | 是 | 开发者准入标识，HTTPS调用时必须使用。 | | from | string | 是 | 源文件地址。注意： * 路径长度限制为1000 * 路径中不能包含以下字符：\\ ? \| " > < : * * 文件名或路径名开头结尾不能是“.”或空白字符，空白字符包括: \r, \n, \t, 空格, \0, \x0B| | to | string | 是 | 目标文件地址。注意： * 路径长度限制为1000 * 路径中不能包含以下字符：\\ ? \| " > < : * * 文件名或路径名开头结尾不能是“.”或空白字符，空白字符包括: \r, \n, \t, 空格, \0, \x0B| #### 返回参数 如果copy操作执行成功，那么response会返回执行成功的from/to列表。 | 参数名称 | 类型 | UrlEncode | 描述 | | :- | :-: | :-: | :- | | from | string | 是 | 执行copy操作成功的源文件地址。 | | to | string | 是 | 执行copy操作成功的目标文件地址。 | #### 注意 move操作后，源文件被移动至目标地址；copy操作则会保留原文件。 #### 示例 ##### 请求示例 POST https://pcs.baidu.com/rest/2.0/pcs/file?method=copy&from=%2fapps%2fpcstest_oauth%2f test1%2f6.jpg&to=%2fapps%2fpcstest_oauth%2ftest2%2f6.jpg&access_token=b700fb598c717c0ad7ea8c97c8f3a46f ##### 响应示例 { "extra": { "list": [{ "to": "/apps/pcstest_oauth/test2/6.jpg", "from": "/apps/pcstest_oauth/test1/6.jpg" }] }, "request_id": 2298812844 } ### 批量拷贝文件/目录 #### 功能 批量拷贝文件/目录。 #### HTTP请求方式 POST #### URL https://pcs.baidu.com/rest/2.0/pcs/file #### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | method | string | 是 | 固定值：copy。 | | access_token | string | 是 | 开发者准入标识，HTTPS调用时必须使用。 | | param | string | 是 | 源文件地址和目标文件地址对应的列表。 {"list":[{"from":"/apps/album/a/b/c","to":"/apps/album/b/b/c"},{"from":"/apps/album/a/b/d","to":"/apps/album/b/b/d"}]} 注意： * 路径长度限制为1000 * 路径中不能包含以下字符：\\ ? \| " > < : * * 文件名或路径名开头结尾不能是“.”或空白字符，空白字符包括: \r, \n, \t, 空格, \0, \x0B| #### 返回参数 返回参数extra由list数组组成，list数组的两个元素分别是“from”和“to”，代表copy操作的源地址和目的地址。 | 参数名称 | 类型 | UrlEncode | 描述 | | :- | :-: | :-: | :- | | from | string | 是 | 执行copy操作成功的源文件地址。 | | to | string | 是 | 执行copy操作成功的目标文件地址。 | #### 注意 执行批量copy操作时，param参数通过HTTP Body传递； 批量执行copy操作时，copy接口一次对请求参数中的每个from/to进行操作；执行失败就会退出，成功就继续，返回执行成功的from/to列表。 #### 示例 ##### 请求示例 POST https://pcs.baidu.com/rest/2.0/pcs/file?method=copy&access_token=b778fb008c717c0ad7ea8c97c8f3a46f ##### 响应示例 { "extra": { "list": [{ "to": "/apps/pcstest_oauth/test1/6.jpg", "from": "/apps/pcstest_oauth/test2/6.jpg" }, { "to": "/apps/pcstest_oauth/test2/89.jpg", "from": "/apps/pcstest_oauth/89.jpg" } ] }, "request_id": 2166619191 } ### 删除单个文件/目录 #### 功能 删除单个文件/目录。 #### HTTP请求方式 POST #### URL https://pcs.baidu.com/rest/2.0/pcs/file #### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | method | string | 是 | 固定值：delete。 | | access_token | string | 是 | 开发者准入标识，HTTPS调用时必须使用。 | | path | string | 是 | 需要删除的文件或者目录路径。如：/apps/album/a/b/c 注意： * 路径长度限制为1000 * 路径中不能包含以下字符：\\ ? \| " > < : * * 文件名或路径名开头结尾不能是“.”或空白字符，空白字符包括: \r, \n, \t, 空格, \0, \x0B| #### 返回参数 无 #### 示例 ##### 请求示例 POST https://pcs.baidu.com/rest/2.0/pcs/file?method=delete&access_token=1.54bef91002416ee4a41791d4a8ea04fe.86400.1331206383.67272939-188383&path=%2Fapps%2Fyunform%2Fmusic ##### 响应示例 { "request_id": 4043312866 } ### 批量删除文件/目录 #### 功能 批量删除文件/目录。 注意： * 文件/目录删除后默认临时存放在回收站内，删除文件或目录的临时存放不占用用户的空间配额； * 存放有效期为10天，10天内可还原回原路径下，10天后则永久删除。 #### HTTP请求方式 POST #### URL https://pcs.baidu.com/rest/2.0/pcs/file #### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | method | string | 是 | 固定值：delete。 | | access_token | string | 是 | 开发者准入标识，HTTPS调用时必须使用。 | | param | string | 是 | 需要删除的文件或者目录路径。如： {"list":[{"path":"\/apps\/album\/a\/b\/c"},{"path":"\/apps\/album\/a\/b\/d"}]} 注意： * 路径长度限制为1000 * 路径中不能包含以下字符：\\ ? \| " > < : * * 文件名或路径名开头结尾不能是“.”或空白字符，空白字符包括: \r, \n, \t, 空格, \0, \x0B| #### 返回参数 无 #### 示例 ##### 请求示例 POST https://pcs.baidu.com/rest/2.0/pcs/file?method=delete&access_token=1.54bef91002416ee4a41791d400ea04fe.86400.1331206383.67272939-188383 ##### 响应示例 { "request_id": 4043312865 } ### 搜索 #### 功能 按文件名搜索文件（不支持查找目录）。 #### HTTP请求方式 GET #### URL https://pcs.baidu.com/rest/2.0/pcs/file #### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | method | string | 是 | 固定值：search。 | | access_token | string | 是 | 开发者准入标识，HTTPS调用时必须使用。 | | path | string | 是 | 需要检索的目录。 注意： * 路径长度限制为1000 * 路径中不能包含以下字符：\\ ? \| " > < : * * 文件名或路径名开头结尾不能是“.”或空白字符，空白字符包括: \r, \n, \t, 空格, \0, \x0B| | wd | string | 是 | 关键词。 | | re | string | 否 | 是否递归。 * “0”表示不递归 * “1”表示递归 * 缺省为“0” | #### 返回参数 | 参数名称 | 类型 | UrlEncode | 描述 | | :- | :-: | :-: | :- | | fs_id | uint64 | 否 | 文件或目录在PCS的临时唯一标识ID。 | | path | string | 否 | 文件或目录的绝对路径。 | | server_filename | string | 否 | 文件或目录的名称。 | | ctime | uint | 否 | 文件或目录的创建时间。 | | mtime | uint | 否 | 文件或目录的最后修改时间。 | | md5 | string | 否 | 文件的md5值。 | | block_list | string | 否 | 文件所有分片的md5数组JSON字符串。 | | size | uint64 | 否 | 文件大小（byte）。 | | isdir | uint | 否 | 是否是目录的标识符： * “0”为文件 * “1”为目录 | #### 示例 ##### 请求示例 GET https://pcs.baidu.com/rest/2.0/pcs/file?method=search&access_token=1.54bee00df241eee4a41791d4a8ea04fe.86400.1331206383.67272939-188383&path=%2Fapps%2Fyunform%2Fmusic&wd=hello&re=1 ##### 响应示例 { "list": [{ "fs_id": 3528850315, "path": "/apps/yunform/music/hello", "ctime": 1331184269, "mtime": 1331184269, "block_list": ["59ca0efa9f5633cb0371bbc0355478d8"], "size": 13, "isdir": 0 }], "request_id": 4043312670 } ## 高级功能 ### 缩略图 #### 功能 获取指定图片文件的缩略图。 #### HTTP请求方式 GET #### URL https://pcs.baidu.com/rest/2.0/pcs/thumbnail #### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | method | string | 是 | 固定值：generate。 | | access_token | string | 是 | 开发者准入标识，HTTPS调用时必须使用。 | | path | string | 是 | 源图片的路径。 注意： * 路径长度限制为1000 * 路径中不能包含以下字符：\\ ? \| " > < : * * 文件名或路径名开头结尾不能是“.”或空白字符，空白字符包括: \r, \n, \t, 空格, \0, \x0B| | quality | int32 | 否 | 缩略图的质量，默认为“100”，取值范围(0,100]。 | | height | int | 是 | 指定缩略图的高度，取值范围为(0,1600]。 | | width | int | 是 | 指定缩略图的宽度，取值范围为(0,1600]。 | #### 返回参数 无 #### 注意 有以下限制条件： * 原图大小(0, 10M]； * 原图类型: jpg、jpeg、bmp、gif、png； * 目标图类型:和原图的类型有关；例如：原图是gif图片，则缩略后也为gif图片。 #### 示例 ##### 请求示例 GET https://pcs.baidu.com/rest/2.0/pcs/thumbnail?method=generate&path=%2Fapps%2Fpcstest_oauth%2FSunset.jpg&quality=100&width=1600&height=1600 ##### 响应示例 缩略图文件内容 ### 增量更新查询 #### 功能 文件增量更新操作查询接口。本接口有数秒延迟，但保证返回结果为最终一致。 #### HTTP请求方式 GET #### URL https://pcs.baidu.com/rest/2.0/pcs/file #### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | method | string | 是 | 固定值：diff。 | | access_token | string | 是 | 开发者准入标识，HTTPS调用时必须使用。 | | cursor | string | 是 | 用于标记更新断点。 * 首次调用cursor=null； * 非首次调用，使用最后一次调用diff接口的返回结果中的cursor。 | #### 返回参数 | 参数名称 | 类型 | 描述 | | :- | :-: | :- | | entries | array | k-v形式的列表，分为以下两种形式： 1. key为path，value为path对应的meta值，meta中isdelete=0为更新操作 * 如果path为文件，则更新path对应的文件； * 如果path为目录，则更新path对应的目录信息，但不更新path下的文件。 2. key为path，value为path删除的meta信息，meta中“isdelete!=0”为删除操作。 * isdelete=1 该文件被永久删除； * isdelete=-1 该文件被放置进回收站； * 如果path为文件，则删除该path对应的文件； * 如果path为目录，则删除该path对应的目录和目录下的所有子目录和文件； * 如果path在本地没有任何记录，则跳过本删除操作。 | | has_more | boolean | * True： 本次调用diff接口，增量更新结果服务器端无法一次性返回，客户端可以立刻再调用一次diff接口获取剩余结果； * False： 截止当前的增量更新结果已经全部返回，客户端可以等待一段时间（1-2分钟）之后再diff一次查看是否有更新。 | | reset | boolean | * True： 服务器通知客户端，服务器端将按时间排序从第一条开始向客户端返回一份完整的数据列表； * False：返回上次请求返回cursor之后的增量更新结果。 | | cursor | string | 用于下一次调用diff接口时传入的断点参数。 | #### 示例 ##### 请求示例 *First time: cursor=null GET https://pcs.baidu.com/rest/2.0/pcs/file?method=diff&access_token=1.54bef91df2416ee4a41791d4a8ea04fe.86400.1331206383.67272939-188383&cursor=null *Next every time: cursor={cursor from last response} GET https://pcs.baidu.com/rest/2.0/pcs/file?method=diff&access_token=1.54bef91df2416ee4a41791d4a8ea04fe.86400.1331206383.67272939-188383&cursor=MxKx6UPi3w2Jt%2B%2BktMKKQpBbnC%2B11aH7Ec9pt%2BfteS%2F%2BknWrp3JIz%2F6fXHccEkZo2kkkSH748hScdRgcA4VCZJuCMQMvNkXAlSmzT5TwqBVc3xwhSxaFkClqbcogAOc8I0k7xtTb9nG6rBJsxNgRFgBV4F695TkrLDHYHRy%2BQ%3D%3D ##### 响应示例 { "entries": { "\/baiduapp\/browser": { "fs_id": 2427025269, "path": "\/baiduapp\/browser", "size": 0, "isdir": 1, "md5": "", "mtime": 1336631762, "ctime": 1336631762 } }, "has_more": true, "reset": true, "cursor": "MxKx6UPie/9WzBkwALPrVWQlyxlmK0LgHG8zutwXp8oyC/ngIdGgS3w2Jt++ktMKKQpBbnC+11aH7Ec9pt+fteS/+knWrp3JIz/6fXHccEkZo2kkkSH748hScdRgcA4VCZJuCMQMvNkXAlSmzT5TwqBVc3xwhSxaFkClqbcogAOc8I0k7xtTb9nG6rBJsxNgRFgBV4F695TkrLDHYHRy+Q==", "request_id": 3355443548 } ### 视频转码 #### 功能 对视频文件进行转码，实现实时观看视频功能。 可下载支持HLS/M3U8的[媒体云播放器SDK](http://developer.baidu.com/wiki/index.php?title=docs/cplat/media/sdk)配合使用。 #### HTTP请求方式 GET #### URL https://pcs.baidu.com/rest/2.0/pcs/file #### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | method | string | 是 | 固定值：streaming。 | | access_token | string | 是 | 开发者准入标识，HTTPS调用时必须使用。 | | path | string | 是 | 需要下载的视频文件路径，以/开头的绝对路径，需含源文件的文件名。 注意： * 路径长度限制为1000 * 路径中不能包含以下字符：\\ ? \| " > < : * * 文件名或路径名开头结尾不能是“.”或空白字符，空白字符包括: \r, \n, \t, 空格, \0, \x0B| | type | string | 是 | 目前支持以下格式： * M3U8_320_240、M3U8_480_224、M3U8_480_360、M3U8_640_480和M3U8_854_480 | #### 注意 目前这个接口支持的源文件格式如下： | 格式名称 | 扩展名 | 备注 | | :- | :- | :- | | 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视频格式 | #### 返回参数 无 #### 示例 ##### 请求示例 GET https://pcs.baidu.com/rest/2.0/pcs/file?method=streaming&path=%2fapps%2fvideo%2fv1.mov&access_token=b778fb000c717c0ad7ea8c97c8f3a46f&type=MP4_480P ##### 响应示例 直接返回文件内容 ### 获取流式文件列表 #### 功能 以视频、音频、图片及文档四种类型的视图获取所创建应用程序下的文件列表。 #### HTTP请求方式 GET #### URL https://pcs.baidu.com/rest/2.0/pcs/stream #### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | method | string | 是 | 固定值：list。 | | access_token | string | 是 | 开发者准入标识，HTTPS调用时必须使用。 | | type | string | 是 | 类型分为video、audio、image及doc四种。 | | start | string | 否 | 返回条目控制起始值，缺省值为0。 | | limit | string | 否 | 返回条目控制长度，缺省为1000，可配置。 | | filter_path | string | 否 | 需要过滤的前缀路径，如：/apps/album 注意： * 路径长度限制为1000 * 路径中不能包含以下字符：\\ ? \| " > < : * * 文件名或路径名开头结尾不能是“.”或空白字符，空白字符包括: \r, \n, \t, 空格, \0, \x0B| #### 返回参数 | 参数名称 | 类型 | 描述 | | :- | :-: | :- | | total | uint | 文件总数。 | | start | uint | 起始数。 | | limit | uint | 获取数。 | | path | string | 获取流式文件的绝对路径。 | | block_list | string | 分片MD5列表。 | | size | uint | 流式文件的文件大小（byte）。 | | mtime | uint | 流式文件在服务器上的修改时间 。 | | ctime | uint | 流式文件在服务器上的创建时间 。 | | fs_id | uint64 | 流式文件在PCS中的唯一标识ID 。 | | isdir | uint | * 0：文件 * 1：目录 | #### 示例 ##### 请求示例 GET https://pcs.baidu.com/rest/2.0/pcs/stream?method=list&type=image&start=50&limit=100&access_token=b778fb000c717c0ad7ea8c97c8f3a46f ##### 响应示例 { "total": 13, "start": 0, "limit": 1, "list": [{ "path": "/apps/album/1.jpg", "size": 372121, "ctime": 1234567890, "mtime": 1234567890, "md5": "cb123afcc12453543ef", "fs_id": 12345, "isdir": 0 }] } ### 下载流式文件 #### 功能 为当前用户下载一个流式文件。其参数和返回结果与下载单个文件的相同。 #### HTTP请求方式 GET #### URL https://pcs.baidu.com/rest/2.0/pcs/stream #### 注意 1. 兼容原有域名pcs.baidu.com；使用新域名d.pcs.baidu.com，则提供更快、更稳定的下载服务。 2. 需注意处理好 302 跳转问题。 #### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | method | string | 是 | 固定值：download。 | | access_token | string | 是 | 开发者准入标识，HTTPS调用时必须使用。 | | path | string | 是 | 需要下载的文件路径，以/开头的绝对路径，含文件名。 注意： * 路径长度限制为1000 * 路径中不能包含以下字符：\\ ? \| " > < : * * 文件名或路径名开头结尾不能是“.”或空白字符，空白字符包括: \r, \n, \t, 空格, \0, \x0B| #### 返回参数 无 #### 示例 ##### 请求示例 GET https://pcs.baidu.com/rest/2.0/pcs/stream?method=download&access_token=b778fb000c717c0ad7ea8c97c8f3a46f&path=%2fapps%2falbum%2f1.jpg ##### 响应示例 流式文件内容 ### 秒传文件 #### 功能 秒传一个文件。 注意： * 被秒传文件必须大于256KB（即 256*1024 B）。 * 校验段为文件的前256KB，秒传接口需要提供校验段的MD5。(非强一致接口，上传后请等待1秒后再读取) #### HTTP请求方式 POST #### URL https://pcs.baidu.com/rest/2.0/pcs/file #### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | method | string | 是 | 固定值：rapidupload。 | | access_token | string | 是 | 开发者准入标识，HTTPS调用时必须使用。 | | path | string | 是 | 上传文件的全路径名。 注意： * 路径长度限制为1000 * 路径中不能包含以下字符：\\ ? \| " > < : * * 文件名或路径名开头结尾不能是“.”或空白字符，空白字符包括: \r, \n, \t, 空格, \0, \x0B| | content-length | int | 是 | 待秒传的文件长度。 | | content-md5 | string | 是 | 待秒传的文件的MD5。 | | slice-md5 | string | 是 | 待秒传文件校验段的MD5。 | | content-crc32 | string | 是 | 待秒传文件CRC32 | | ondup | string | 否 | * overwrite：表示覆盖同名文件； * newcopy：表示生成文件副本并进行重命名，命名规则为“文件名_日期.后缀”。 | #### 返回参数 | 参数名称 | 类型 | 描述 | | :- | :-: | :- | | path | string | 秒传文件的绝对路径。 | | size | uint64 | 秒传文件的字节大小 。 | | ctime | uint64 | 秒传文件的创建时间。 | | mtime | uint64 | 秒传文件的修改时间 。 | | md5 | string | 秒传文件的md5签名。 | | fs_id | uint64 | 秒传文件在PCS的唯一标识ID。 | | isdir | uint | * 0：文件 * 1：目录 | #### 示例 ##### 请求示例 POST https://pcs.baidu.com/rest/2.0/pcs/file?method=rapidupload&access_token=b778fb000c717c0ad7ea8c97c8f3a46f&content-length=1542719&content-md5=3edf3d47292280e0182db6750bd176e5&slice-md5=6fce289cfee3e4414788dcd000a3ddc4&path=%2fa%2fb%2fc ##### 响应示例 { "path": "/apps/album/1.jpg", "size": 372121, "ctime": 1234567890, "mtime": 1234567890, "md5": "cb123afcc12453543ef", "fs_id": 12345, "isdir": 0, "request_id": 12314124 } ### 添加离线下载任务 #### 功能 添加离线下载任务，实现单个文件离线下载。 #### HTTP请求方式 POST #### URL https://pcs.baidu.com/rest/2.0/pcs/services/cloud_dl #### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | method | string | 是 | 固定值：add_task。 | | access_token | string | 是 | 开发者准入标识，HTTPS调用时必须使用。 | | expires | int | 否 | 请求失效时间，如果有，则会校验。 | | save_path | string | 是 | 下载后的文件保存路径。注意： * 路径长度限制为1000 * 路径中不能包含以下字符：\\ ? \| " > < : * * 文件名或路径名开头结尾不能是“.”或空白字符，空白字符包括: \r, \n, \t, 空格, \0, \x0B | | source_url | string | 是 | 源文件的URL。 | | rate_limit | int | 否 | 下载限速，默认不限速。 | | timeout | int | 否 | 下载超时时间，默认3600秒。 | | callback | string | 否 | 下载完毕后的回调，默认为空。 | #### 返回参数 任务ID号 #### 示例 ##### 请求示例 POST https://pcs.baidu.com/rest/2.0/pcs/service/cloud_dl?method=add_task&access_token=40001fsdjfdjskaf&source_url=http:\/\/dl_dir.qq.com:80\/qqfile\/qq\/QQ2012\/QQ2012.exe ##### 响应示例 任务ID号成功： {"task_id":432432432432432,"request_id":3372220525} 任务并发太大： {"error_code":36013,"error_msg":"too many tasks","request_id":3372220539} ### 精确查询离线下载任务 #### 功能 根据任务ID号，查询离线下载任务信息及进度信息。 #### HTTP请求方式 POST #### URL https://pcs.baidu.com/rest/2.0/pcs/service/cloud_dl #### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | method | string | 是 | 固定值：query_task。 | | access_token | string | 是 | 开发者准入标识，HTTPS调用时必须使用。 | | expires | int | 否 | 请求失效时间，如果有，则会校验。 | | task_ids | string | 是 | 要查询的任务ID信息，如：1,2,3,4 | | op_type | int | 是 | * 0：查任务信息 * 1：查进度信息，默认为1 | #### 返回参数 无 #### 示例 ##### 请求示例 POST https://pcs.baidu.com/rest/2.0/pcs/services/cloud_dl?method=query_task&access_token=43000fsdjfdjskaf ##### Body示例 查询任务信息： { “request_id”:12394838223, “task_info”: { “123456” : { "result" : 0, //0查询成功，结果有效，1要查询的task_id不存在 "source_url":"http://www.example.com/xxx.zip",//下载数据源地址 "save_path":"http://xxxx/",//下载完成后的存放地址 "rate_limit":10, "timeout": 3600, "callback":"http://XXX", "status":1 (0下载成功，1下载进行中 2系统错误，3资源不存在，4下载超时，5资源存在但下载失败 6存储空间不足 7目标地址数据已存在 8任务取消) "create_time":"UNIX_TIMESTAMP",//任务创建时间 } “43829483”: { "result" : 1, //要查询的task_id不存在 } } } 查询进度信息： { “request_id”:12394838223, “task_info”: { “123456” : { "result" : 0, //0查询成功，结果有效，1要查询的task_id不存在 "status": (0下载成功，1下载进行中 2系统错误，3资源不存在，4下载超时，5资源存在但下载失败 6存储空间不足 7任务取消) //其余字段，在status为0、1时有效 "file_size":1024 "finished_size":512 "create_time": 123232132, "start_time": 43728943, "finish_time": 43728948, } “43829483”: { "result" : 1, //要查询的task_id不存在 } } } ##### 响应示例 任务信息或进度信息 ### 查询离线下载任务列表 #### 功能 查询离线下载任务ID列表及任务信息。 #### HTTP请求方式 POST #### URL https://pcs.baidu.com/rest/2.0/pcs/services/cloud_dl #### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | method | string | 是 | 固定值：list_task。 | | access_token | string | 是 | 开发者准入标识，HTTPS调用时必须使用。 | | expires | int | 否 | 请求失效时间，如果有，则会校验。 | | start | int | 否 | 查询任务起始位置，默认为0。 | | limit | int | 否 | 设定返回任务数量，默认为10。 | | asc | int | 否 | * 0：降序，默认值 * 1：升序 | | source_url | string | 否 | 源地址URL，默认为空。 | | save_path | string | 否 | 文件保存路径，默认为空。注意： * 路径长度限制为1000 * 路径中不能包含以下字符：\\ ? \| " > < : * * 文件名或路径名开头结尾不能是“.”或空白字符，空白字符包括: \r, \n, \t, 空格, \0, \x0B | | create_time | int | 否 | 任务创建时间，默认为空。 | | status | int | 否 | 任务状态，默认为空。 | | need_task_info | int | 否 | 是否需要返回任务信息: * 0：不需要 * 1：需要，默认为1 | #### 返回参数 任务信息或任务列表 #### 示例 ##### 请求示例 查询离线下载任务ID列表 POST https://pcs.baidu.com/rest/2.0/pcs/services/cloud_dl?method=list_task&access_token=43000fsdjfdjskaf&need_task_info=1 ##### 响应示例 任务列表 {"task_info":[{"task_id":"26"}],"total":"1","request_id":1283164486} 任务信息 {"task_info":[{"task_id":"26","source_url":"http:\/\/dl_dir.qq.com:80\/qqfile\/qq\/QQ2012\/QQ2012.exe","save_path":"\/apps\/Slideshow\/wu_jing_test0","rate_limit":"100","timeout":"10000","callback":"http:\/\/www.baidu.com","status":"1","create_time":"1347449048"}],"total":"1","request_id":1285732167} ### 取消离线下载任务 #### 功能 取消离线下载任务。 #### HTTP请求方式 POST #### URL https://pcs.baidu.com/rest/2.0/pcs/services/cloud_dl #### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | method | string | 是 | 固定值：cancel_task。 | | access_token | string | 是 | 开发者准入标识，HTTPS调用时必须使用。 | | expires | int | 否 | 请求失效时间，如果有，则会校验。 | | task_id | string | 是 | 要取消的任务ID号。 | #### 返回参数 任务信息或任务列表 #### 示例 ##### 请求示例 POST https://pcs.baidu.com/rest/2.0/pcs/services/cloud_dl?method=cancel_task&access_token=43000fsdjfdjskaf&task_id=26 ##### 响应示例 { “request_id”:12394838223, } ### 回收站 #### 功能 回收站用于临时存放删除文件，且不占空间配额；但回收站的文件存放具有10天有效期，删除文件默认扔到回收站，10天内可通过回收站找回，逾期永久删除。 回收站功能，目前支持以下几种操作和接口： * 删除文件到回收站： delete （目前默认是删除到回收站），API详细说明请参考“删除单个文件或目录”及“批量删除文件或目录”部分 * 查看回收站文件： listrecycle * 还原回收站文件（单个文件或多个文件）： restore * 清空回收站：delete ### 查询回收站文件 #### 功能 获取回收站中的文件及目录列表。 #### HTTP请求方式 GET #### URL https://pcs.baidu.com/rest/2.0/pcs/file #### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | method | string | 是 | 固定值：listrecycle。 | | access_token | string | 是 | 开发者准入标识，HTTPS调用时必须使用。 | | start | int | 否 | 返回条目的起始值，缺省值为0 | | limit | int | 否 | 返回条目的长度，缺省值为1000 | #### 返回参数 获取成功，返回回收站文件或目录列表信息 | 参数名称 | 描述 | | :- | :- | | list | list是一个数组，以JSON串的形式显示所获取到的回收站文件或目录的具体信息，详细信息参考下面的“list数组元素说明”。 | | request_id | 请求ID，也就是服务器用于追踪错误的的日志ID | list数组中的元素说明如下： | 参数名称 | 类型 | UrlEncode | 描述 | | :- | :-: | :-: | :- | | fs_id | uint64 | 否 | 目录在PCS上的临时唯一标识 | | path | string | 是 | 该目录的绝对路径 | | ctime | uint | 否 | 文件在服务器上的创建时间 | | mtime | uint | 否 | 文件在服务器上的修改时间 | | md5 | string | 否 | 分片MD5 | | size | uint | 否 | 文件大小（byte） | | isdir | uint | 否 | 是否是目录的标识符： * “0”为文件 * “1”为目录 | 获取失败，则返回错误信息 | 参数名称 | 描述 | | :- | :- | | error_code | 错误码，详见“[文件API错误码列表](https://github.com/qjfoidnh/BaiduPCS-Go/blob/master/docs/file_data_apis_error.md)” | | error_msg | 错误信息，详见“[文件API错误码列表](https://github.com/qjfoidnh/BaiduPCS-Go/blob/master/docs/file_data_apis_error.md)” | | request_id | 请求ID，也就是服务器用于追踪错误的的日志ID | #### 示例 ##### 请求示例 GET https://pcs.baidu.com/rest/2.0/pcs/file?method=listrecycle&start=50&limit=100&access_token=111f1118c717111a8111c8f3a46f ##### 响应示例 获取成功: { "list":[ { "fs_id":1579174, "path":"\/apps\/CloudDriveDemo\/testfile-10.rar", "ctime":1361934614, "mtime":1361934625, "md5":"1131170ac11cfbec411a5e8d4e111769", "size":10730431, "isdir":0 }, { "fs_id":304521061, "path":"\/apps\/CloudDriveDemo\/testfile-4.rar", "ctime":1361934605, "mtime":1361934625, "md5":"9552bf5e5abdf962e2de94be243bec7c", "size":4287611, "isdir":0 } ], "request_id":3779302504 } 获取失败: {"error_code":110,"error_msg":"Access token invalid or no longer valid","request_id":1444638699} ### 还原单个文件或目录 #### 功能 还原单个文件或目录（非强一致接口，调用后请sleep 1秒读取） #### HTTP请求方式 POST #### URL https://pcs.baidu.com/rest/2.0/pcs/file #### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | method | string | 是 | 固定值：restore。 | | access_token | string | 是 | 开发者准入标识，HTTPS调用时必须使用。 | | fs_id | string | 是 | 所还原的文件或目录在PCS的临时唯一标识ID。 | #### 返回参数 还原成功时，返回以下参数 | 参数名称 | 描述 | | :- | :- | | extra | extra由list数组组成，list数组中包含一个元素fs_id，即文件或目录在PCS的临时唯一标识ID。 | | request_id | 请求ID，也就是服务器用于追踪错误的的日志ID | 还原失败，则返回错误信息 | 参数名称 | 描述 | | :- | :- | | error_code | 错误码，详见“[文件API错误码列表](https://github.com/qjfoidnh/BaiduPCS-Go/blob/master/docs/file_data_apis_error.md)” | | error_msg | 错误信息，详见“[文件API错误码列表](https://github.com/qjfoidnh/BaiduPCS-Go/blob/master/docs/file_data_apis_error.md)” | | request_id | 请求ID，也就是服务器用于追踪错误的的日志ID | #### 示例 ##### 请求示例 POST https://pcs.baidu.com/rest/2.0/pcs/file?method=restore&fs_id=123456&access_token=111f1118c717111a8111c8f3a46f ##### 响应示例 还原成功 {"extra":{"list":[{"fs_id":"1356099017"}]},"request_id":3775323016} 还原失败 {"error_code":31061,"error_msg":"file already exists","request_id":811204199} ### 批量还原文件或目录 #### 功能 批量还原文件或目录（非强一致接口，调用后请sleep1秒 ） #### HTTP请求方式 POST #### URL https://pcs.baidu.com/rest/2.0/pcs/file #### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | method | string | 是 | 固定值：restore。 | | access_token | string | 是 | 开发者准入标识，HTTPS调用时必须使用。 | | param | string | 是 | Body中的JSON串，用于批量处理 | #### 返回参数 | 参数名称 | 描述 | | :- | :- | | error_code | 错误码，详见“[文件API错误码列表](https://github.com/qjfoidnh/BaiduPCS-Go/blob/master/docs/file_data_apis_error.md)” | | error_msg | 错误信息，详见“[文件API错误码列表](https://github.com/qjfoidnh/BaiduPCS-Go/blob/master/docs/file_data_apis_error.md)” | | extra | extra由list数组组成，list数组中包含一个元素fs_id，即文件或目录ID | | request_id | 请求ID，也就是服务器用于追踪错误的的日志ID | 说明： * 全部还原成功的情况下，返回extra及request_id信息； * 还原多个文件或目录时，如果还原某个文件或目录失败，则报错并终止还原操作，返回error_code、error_msg、extra及request_id信息； * 其中，如果未成功还原任何文件时，返回的extra中的list数组为空； * 部分文件或目录还原成功时，则返回的extra中list数组中显示该部分文件的fs_id。 #### 示例 ##### 请求示例 POST https://pcs.baidu.com/rest/2.0/pcs/file?method=restore&access_token=111f1118c717111a8111c8f3a46f.2592000.1364548100.3123371436-248414¶m={"list":[{"fs_id":"4059450057"},{"fs_id":"2959141864"}]} ##### 响应示例 全部还原成功 {"extra":{"list":[{"fs_id":"2959141864"}],"request_id":1359873129} 全部还原失败 {"error_code":31061,"error_msg":"file already exists","extra":{"list":[]},"request_id":1342759216} 部分还原成功 {"error_code":31061,"error_msg":"file already exists","extra":{"list":[{"fs_id":"2959141864"}]},"request_id":1359873129} ### 清空回收站 #### 功能 清空回收站 #### HTTP请求方式 POST #### URL https://pcs.baidu.com/rest/2.0/pcs/file #### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | :- | :-: | :-: | :- | | method | string | 是 | 固定值为delete | | access_token | string | 是 | 开发者准入标识，HTTPS调用时必须使用。 | | type | string | 是 | 固定值为recycle | #### 返回参数 清空成功，返回请求ID | 参数名称 | 描述 | | :- | :- | | request_id | 请求ID，也就是服务器用于追踪错误的的日志ID | 清空失败，则返回错误信息 | 参数名称 | 描述 | | :- | :- | | error_code | 错误码，详见“[文件API错误码列表](https://github.com/qjfoidnh/BaiduPCS-Go/blob/master/docs/file_data_apis_error.md)” | | error_msg | 错误信息，详见“[文件API错误码列表](https://github.com/qjfoidnh/BaiduPCS-Go/blob/master/docs/file_data_apis_error.md)” | | request_id | 请求ID，也就是服务器用于追踪错误的的日志ID | #### 示例 ##### 请求示例 POST https://pcs.baidu.com/rest/2.0/pcs/file?method=delete&type=recycle&access_token=111f1118c717111a8111c8f3a46f ##### 响应示例 清空成功 {"request_id":2307473052} 清空失败 {"error_code":31070,"error_msg":"file delete failed","request_id":12345678} --- ## File: docs/overview.md # 概述 百度开放云平台为广大开发者提供了访问PCS资源的系列接口，目前开放的接口主要分两个部分： * 文件API: 主要提供文件上传、下载、拷贝、删除、搜索、断点续传及缩略图等功能。 * 结构化数据API: 主要提供结构数据存储、查询、删除及同步等功能。 通过对这些API的组合调用，开发者可以实现基本的用户文件操作以及结构数据存储和管理功能，也能够支持用户数据在多种不同终端上的同步，以提供更优质的用户体验。 除了原生的REST（Representational State Transfer，即“表述性状态转移”） API之外，百度开放云平台还提供了多种平台的SDK来帮助开发者缩短开发周期，具体请参考“SDK”部分相关内容。 ## PCS REST API使用说明 ### 开通PCS API权限 PCS所有REST API都必须经过开通权限才能正常使用。申请的方法请参考“开通PCS API权限”部分相关内容。 注意：PCS未提供分享接口，download等接口仅供个人获取数据使用。 access_token不能泄露，否则会直接封禁应用。 ### API请求方式说明 目前所有的提交类接口仅支持POST方式，查询类接口同时支持POST方式和GET方式。 PCS REST API的所有参数在传入时应当使用：UTF-8编码。 #### HTTP 请求方式 GET | POST #### URL https://pcs.baidu.com/rest/2.0/pcs/{object_name}?{query_string} #### 参数说明 | 参数名称 | 描述 | | :- | :- | | object_name | PCS REST API操作实体名称，如：quota、file、thumbnail。 | | query_string | 放在HTTP头部传入的参数，必须经过UrlEncode编码。 | #### HTTP GET和POST方式使用说明 | 请求方式 | GET | POST | | --- | --- | --- | | URL | https://pcs.baidu.com/rest/2.0/pcs/{object_name}?{query_string} | | | 请求参数 | 全部携带在 HTTPS 请求头部的 query_string 中。 | 既可携带在 query_string 中，也可携带在 HTTP Body 中。 method 及 access token 等参数必须携带在 query_string 中进行传输，请参考各个API的具体说明； 携带在 query_string 中的参数的值，必须进行 UrlEncode 编码； 携带在 HTTP Body 中的参数，则不需要进行 UrlEncode 编码。 注 HTTP URL 长度有限，若参数值长度过长，建议将参数放在 HTTP Body 中进行传输。 | | HTTP BODY | 不携带HTTP Body | multipart/form-data | | 注意 | 如果 HTTP Body 和 query_string 存在相同的参数，则以 query_string 中的参数为准。 | | #### 使用示例 1. GET请求： 用HTTP GET请求方式发送两个参数：key1=value1和key2=value2。 https://pcs.baidu.com/rest/2.0/pcs/quota?key1=UrlEncode(value1)&key2=UrlEncode(value2) 2. POST请求： 分别用两种方式使用POST方式发送三个参数：key1=value1、key2=value2和key3=value3；方式一与方式二效果等同。 ##### 方式一： POST /rest/2.0/pcs/quota?key2=value2&key3=value3 HTTP/1.1 User-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.6 Pragma: no-cache Accept: */* Host:pcs.baidu.com Content-Length:123 Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryS0JIa4uHF7yHd8xJ ------WebKitFormBoundaryS0JIa4uHF7yHd8xJ Content-Disposition: form-data; name="key1" value1 ------WebKitFormBoundaryS0JIa4uHF7yHd8xJ— ##### 方式二： POST /rest/2.0/pcs/quota HTTP/1.1 User-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.6 Pragma: no-cache Accept: */* Host:pcs.baidu.com Content-Length:123 Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryS0JIa4uHF7yHd8xJ ------WebKitFormBoundaryS0JIa4uHF7yHd8xJ Content-Disposition: form-data; name="key1" value1 ------WebKitFormBoundaryS0JIa4uHF7yHd8xJ Content-Disposition: form-data; name="key2" value2 ------WebKitFormBoundaryS0JIa4uHF7yHd8xJ Content-Disposition: form-data; name="key3" value3 ------WebKitFormBoundaryS0JIa4uHF7yHd8xJ-- ### API响应格式说明 | | 正常请求 | 异常请求 | | --- | --- | --- | | HTTP状态码 | 200 OK | 4** : 用户请求错误。5** ：server服务失败。 | | HTTP BODY | API响应内容 | 异常请求的返回值为JSON字符串。例如：{"error_code":110,"error_msg":"Access token invalid or no longer valid","request_id":729562373}说明： - error_code：错误码； - error_msg: 错误描述信息； - request_id: 请求ID。由server生成，用于追查和定位请求日志。 | --- ## File: docs/README.md # 文档目录 ## 百度PCS文档 ### 文件API [综述](https://github.com/qjfoidnh/BaiduPCS-Go/blob/master/docs/overview.md) [文件API列表](https://github.com/qjfoidnh/BaiduPCS-Go/blob/master/docs/file_data_apis_list.md) [文件API错误码列表](https://github.com/qjfoidnh/BaiduPCS-Go/blob/master/docs/file_data_apis_error.md) ### 结构化数据API [综述](https://github.com/qjfoidnh/BaiduPCS-Go/blob/master/docs/structured_data_apis_overview.md) [结构化数据API列表](https://github.com/qjfoidnh/BaiduPCS-Go/blob/master/docs/structured_data_api_list.md) [结构化数据API错误码](https://github.com/qjfoidnh/BaiduPCS-Go/blob/master/docs/structured_data_apis_error.md) --- ## File: docs/structured_data_api_list.md # 结构化数据API列表 ## 更新通知： 2013.7.2 修改“创建table”接口，请求参数增加“sk” ## 创建table ### 功能 创建一个表，定义索引，其中包括对唯一索引的支持。 **注意：** * 一个应用最多创建5个表，一个表上最多创建5个索引； * 关于表和索引的创建规则，您可以参考“结构化数据表基本概念”； * 为保证一致性，创建表后，可能需要等待一段时间才能用describe table接口查看到； * 创建一张表必须带有该表所属app的密匙sk，用于之后的psstoken鉴权使用。 **关于“唯一索引”的说明：** * 可以建联合的唯一索引； * 一个table上唯一索引数量同一般索引限制，5个； * 唯一索引不支持在表创建后在增加，所以需要在表设计的时候尽量考虑；（如确实需要，可联系我们。） * insert的时候必须带上唯一索引的所有字段，否则会失败。 ### HTTP请求方式 POST ### URL https://pcs.baidu.com/rest/2.0/structure/table ### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | --- | --- | --- | --- | | v | string | 否 | 版本号，默认为“1.0”。 | | method | string | 是 | 固定值：create。 | | access_token | string | 是 | 开发者的应用所对应的access_token。 | | table | string | 是 | 表名。 | | sk | string | 是 | 该表所属app的密匙（secret key），用于psstoken鉴权使用。 | | column | json | 否 | 列描述。 | | index | json | 否 | 索引描述： * 1：表示升序索引 * -1：表示降序索引 | 返回参数 | 参数名称 | 类型 | 描述 | | --- | --- | --- | | error_code | number | 错误码, 如果不出错, 则返回值没有该字段。 | | error_msg | string | 错误提示, 如果不出错, 则返回值没有该字段。 | | app_id | int | 应用对应的ID。 | | table | string | 表名。 | | request_id | int | 请求ID号。 | ### 示例 请求示例: #### 1. 创建一般索引 $ cat > ./artists_create_table <<DELIM { "table" : "artists", "column" : { "id" : { "description" : "", "type" : "int", "required" : true } }, "index": { "id_index" : { "column" : {"id" : 1} } } } DELIM   $ curl -v -X POST "http://pcs.baidu.com/rest/2.0/structure/table?method=create&access_token=2.b06c3e00010fdb879d12345dcd5f8545.2587600.134819999.1175746697-238347&sk=cRgk8uMGX098yMfmttoVYswcv3XKBLGX" -F "param=<artists_create_table" #### 2. 创建唯一索引 $ cat > ./artists_create_table <<DELIM { "table" : "artists", "column" : { "id" : { "description" : "", "type" : "int", "required" : true } }, "index": { "id_index" : { "column" : {"id" : 1}, "unique" : true } } } DELIM   $ curl -v -X POST "http://pcs.baidu.com/rest/2.0/structure/table?method=create&access_token=2.b06c3e00010fdb879d12345dcd5f8545.2587600.134819999.1175746697-238347&sk=cRgk8uMGX098yMfmttoVYswcv3XKBLGX " -F "param=<artists_create_table" ### 注意 unique字段为true，表示唯一索引；为false，则表示一般索引；不指定则默认为一般索引。 正确响应示例：HTTP/1.1 200 OK   { "app_id" : 1, "table" : "artists", "request_id" : 3728395580 } 出错响应示例：HTTP/1.1 400 Bad Request   { "error_code" : 31472, "error_msg" : "table already exist", "request_id" : 9085631045 } ## 修改table ### 功能 修改一个表，添加或者删除索引 ### HTTP请求方式 POST ### URL https://pcs.baidu.com/rest/2.0/structure/table ### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | --- | --- | --- | --- | | v | string | 否 | 版本号，默认为“1.0”。 | | method | string | 是 | 固定值：alter。 | | access_token | string | 是 | 开发者的access_token。 | | table | string | 是 | 表名。 | | add_index | json | 否 | 增加的索引。 | | drop_index | json | 否 | 删除的索引。 | ### 返回参数 | 参数名称 | 类型 | 描述 | | --- | --- | --- | | error_code | number | 错误码，如果不出错，则返回值没有该字段。 | | error_msg | string | 错误提示，如果不出错，则返回值没有该字段。 | | appid | int | 开发者App ID。 | | table | string | 表名。 | | column | json | 列描述。 | | index | json | 索引描述： * 1：表示升序索引； * -1：表示降序索引。 | ### 示例 请求示例: $ cat > ./artists_alter_table <<DELIM { "table" : "artists", "add_index" : { "direction" : { "column" : {"direction" : 1} } }, "drop_index": { "id_index" : { "column" : {"id" : 1} } } } DELIM   $ curl -v -X POST "http://pcs.baidu.com/rest/2.0/structure/table?method=alter&access_token=2.b06c3e00010fdb879d12345dcd5f8545.2587600.134819999.1175746697-238347" -F "param=<artists_alter_table"   正确响应示例：HTTP/1.1 200 OK   { "app_id" : 1, "table" : "artists", "lastindex" : { "direction" : { "column" : { "direction" : 1 } } }, "request_id" : 6402295586 } 出错响应示例：HTTP/1.1 400 Bad Request   { "error_code" : 31409, "error_msg" : "table not exist", "request_id" : 9360693908 } ## 删除table ### 功能 删除一个table ### 注意 如果drop到回收站（默认情况），则drop后该表处于不可访问状态，不能再创建同名的table。 ### HTTP请求方式 POST ### URL https://pcs.baidu.com/rest/2.0/structure/table ### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | --- | --- | --- | --- | | v | string | 否 | 版本号，默认为“1.0”。 | | method | string | 是 | 固定值：drop。 | | access_token | string | 是 | 开发者的App对应的access_token。 | | table | string | 是 | 表名。 | | op | string | 否 | 值为recycled: drop到回收站，可用restore接口恢复。 | 返回参数 | 参数名称 | 类型 | 描述 | | --- | --- | --- | | error_code | number | 错误码。如果不出错，则返回值没有该字段。 | | error_msg | string | 错误提示。如果不出错，则返回值没有该字段。 | | app_id | int | App对应的ID。 | | table | string | 表名。 | | request_id | int | 请求ID号。 | ### 示例 请求示例: $ cat > ./artists_drop_table <<DELIM { "table" : "artists" } DELIM   $ curl -v -X POST "http://pcs.baidu.com/rest/2.0/structure/table?method=drop&access_token=2.b06c3e00010fdb879d12345dcd5f8545.2587600.134819999.1175746697-238347" -F "param=<artists_drop_table" 正确响应示例：HTTP/1.1 200 OK   { "app_id" : 1, "table" : "artists", "request_id" : 3728395580 }   </pre> 出错响应示例：<javascript>HTTP/1.1 400 Bad Request   { "error_code" : 31409, "error_msg" : "table not exist", "request_id" : 9085631045 } ## 从回收站恢复table ### 功能 恢复一个在回收站中的表。 ### HTTP请求方式 POST ### URL https://pcs.baidu.com/rest/2.0/structure/table ### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | --- | --- | --- | --- | | v | string | 否 | 版本号，默认为“1.0”。 | | method | string | 是 | 固定值：restore。 | | access_token | string | 是 | 开发者的App对应的access_token。 | | table | string | 是 | 表名。 | 返回参数 | 参数名称 | 类型 | 描述 | | --- | --- | --- | | error_code | number | 错误码。如果不出错，则返回值没有该字段。 | | error_msg | string | 错误提示。如果不出错，则返回值没有该字段。 | | app_id | int | App对应的ID。 | | table | string | 表名。 | | request_id | int | 请求ID号。 | ### 示例 请求示例: $ cat > ./artists_restore_table <<DELIM { "table" : "artists" } DELIM   $ curl -v -X POST "http://pcs.baidu.com/rest/2.0/structure/table?method=restore&access_token=2.b06c3e00010fdb879d12345dcd5f8545.2587600.134819999.1175746697-238347" -F "param=<artists_restore_table"   正确响应示例：HTTP/1.1 200 OK { "app_id" : 1, "table" : "artists", "request_id" : 3728395580 } 出错响应示例：HTTP/1.1 400 Bad Request { "error_code" : 31474, "error_msg" : "table not drop, cannot restore", "request_id" : 9085631045 } ## 查看table创建信息 ### 功能 查看一个表的创建信息。 ### HTTP请求方式 POST ### URL https://pcs.baidu.com/rest/2.0/structure/table ### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | --- | --- | --- | --- | | v | string | 否 | 版本号， 默认为“1.0”。 | | method | string | 是 | 固定值：describe。 | | access_token | string | 是 | 开发者的App对应的access_token。 | | table | string | 是 | 表名。 | 返回参数 | 参数名称 | 类型 | 描述 | | --- | --- | --- | | error_code | number | 错误码。如果不出错，则返回值没有该字段。 | | error_msg | string | 错误提示。如果不出错，则返回值没有该字段。 | | app_id | int | App对应的ID。 | | table | string | 表名。 | | request_id | int | 请求ID号。 | | column | json | 表的列描述。 | | index | json | 表的索引描述。 | | quota | int | 该表单个用户最大的条目数限制。 | | auth_code | string | 第三方应用请忽略此参数。 | ### 示例 请求示例: $ cat > ./artists_describe_table <<DELIM { "table" : "artists" } DELIM   $ curl -v -X POST "http://pcs.baidu.com/rest/2.0/structure/table?method=describe&access_token=2.b06c3e00010fdb879d12345dcd5f8545.2587600.134819999.1175746697-238347" -F "param=<artists_describe_table" 正确响应示例：HTTP/1.1 200 OK { "appid" : 1, "table" : "artists008", "status" : 0, "ctime" : 1347417209, "mtime" : 1347417209, "cluster" : "cluster0", "subtablenum" : 1, "column" : { "id" : { "description" : "", "type" : "number", "required" : true } }, "index": { "id_index" : { "column" : {"id" : 1} } }, "quota" : 10000, "auth_code" : "e3725dd9a7cbd0a5e3eb7928ab922d33", "request_id" : 2707788940 } 出错响应示例：HTTP/1.1 400 Bad Request   { "error_code" : 31409, "error_msg" : "table not exist", "request_id" : 5574355722 } ## 添加record ### 功能 新增record，每次调用都会新增传入的record。 ### HTTP请求方式 POST ### URL https://pcs.baidu.com/rest/2.0/structure/data ### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | --- | --- | --- | --- | | v | string | 否 | 版本号，默认为“1.0”。 | | method | string | 是 | 固定值：insert。 | | access_token | string | 是 | 用户的access_token，HTTPS调用时必须使用。 | | table | string | 是 | 要插入的目标表名。 | | records | json array | 是 | 需要插入的record JSON对象构成的数组。 | 返回参数 | 参数名称 | 类型 | 描述 | | --- | --- | --- | | error_code | number | 错误码。如果不出错，则返回值没有该字段。 | | error_msg | string | 错误提示。如果不出错，则返回值没有该字段。 | | records | json array | 返回服务器端已经处理的records(_key, _mtime, _ctime)列表，顺序与输入顺序一致；如果一个请求包含多个record，遇到第一个出错record即中止，返回的records只包含已处理成功的key。 | ### 示例 请求示例: cat > ./artists_insert_request <<DELIM { "table":"artists", "records": [ { "id": 85617, "name": "刘德华", "type": "男歌手", "intro": "香港著名歌手、演员", "add_time": 1340949289, "language": ["国语", "粤语"], "tags": ["香港电影金像奖", "四大天王", "东亚唱片"], "top_song": { "id": 3, "name": "爱你一万年" } }, { "id": 85618, "name": "凤凰传奇", "type": "组合", "intro": "中国大陆具有广泛知名度的男女二人音乐组合", "add_time": 1340949289, "language": ["国语"], "tags": ["月亮之上", "最炫民族风"], "top_song": { "id": 5, "name": "月亮之上" } } ] } DELIM   $ curl -v -X POST "http://pcs.baidu.com/rest/2.0/structure/data?method=insert&access_token=2.b06c3e86610fdb879d12345dcd5f8545.2587600.134819999.1175746697-238347" -F "param=<artists_select1_request" 正确响应示例：HTTP/1.1 200 OK   { "records":[ { "_key":"f44603de003c57d5-1346066442", "_mtime":1346066442, "_ctime":1346066442 }, { "_key":"1aaef0010c012db7-1346066442", "_mtime":1346066442, "_ctime":1346066442 } ], "request_id":3728395580 } 出错响应示例：HTTP/1.1 400 Bad Request   { "error_code":31430, "error_msg":"bad record", "request_id":0 "records": [ {"_key": "7d4febca4a68e763-1344915172"}, ] } ## 更新record ### 功能 根据_key更新record；支持批量更新，但只能更新非回收站的record。 ### HTTP请求方式 POST ### URL https://pcs.baidu.com/rest/2.0/structure/data ### 请求参数 | 参数名称 | 类型 | 是否 必需 | 描述 | | --- | --- | --- | --- | | v | string | 否 | 版本号，默认为“1.0”。 | | method | string | 是 | 固定值：update。 | | access_token | string | 是 | 用户的access_token，HTTPS调用时必须使用。 | | table | string | 是 | 要更新的目标表名。 | | records | json array | 是 | 需要更新的record。 | | op | string | 否 | * 当值为“merge”时，请求中record不带的column，保持旧值（默认值）； * 当值为“replace”时，参数中传的record将全量替换整个旧的record。 | 说明： #### 其中records是一个数组，其数组成员结构如下： | 名称 | 类型 | 是否必需 | 描述 | | --- | --- | --- | --- | | record | json | 是 | 需要更新的record，只能是一个record，并且必须指定_key。 | | if-match | string | 否 | 条件更新，防止写操作覆盖了其它client的数据值；为上次获取该item时返回的_mtime属性，只有server端保存的_mtime和用户携带的_mtime一致时，才会进行更新操作。 | 返回参数 | 参数名称 | 类型 | 描述 | | --- | --- | --- | | error_code | number | 错误码。如果不出错，则返回值没有该字段。 | | error_msg | string | 错误提示。如果不出错，则返回值没有该字段。 | | records | json array | 返回服务器端已经处理的records(_key, _mtime)列表，顺序与输入顺序一致；如果一个请求包含多个record，遇到第一个出错record即中止，返回的records只包含已经处理成功的key。 | ### 示例 请求示例: $ cat > ./artists_update_request <<DELIM { "table":"artists", "records": [ { "record": { "_key":"f44603de003c57d5-1346066442", "id": 85617, "name": "刘德华", "type": "男歌手", "intro": "香港著名歌手、演员", "add_time": 1340949289, "language": ["国语", "粤语"], "tags": ["香港电影金像奖", "四大天王", "东亚唱片"] }, "if-match": 1346066442 }, { "record": { "_key":"1aaef0010c012db7-1346066442", "id": 85618, "name": "凤凰传奇", "type": "组合", "intro": "中国大陆具有广泛知名度的男女二人音乐组合", "add_time": 1340949289, "language": ["国语"], "tags": ["月亮之上", "最炫民族风"] }, "if-match": 1346066442 } ] } DELIM   $ curl -v -X POST "http://pcs.baidu.com/rest/2.0/structure/data?method=update&access_token=2.b06c3e00010fdb879d12345dcd5f8545.2587600.134819999.1175746697-238347" -F "param=<artists_update_request"   正确响应示例：HTTP/1.1 200 OK   { "records":[ { "_key":"f44603de003c57d5-1346066442", "_mtime":1346066823 }, { "_key":"1aaef0010c012db7-1346066442", "_mtime":1346066824 } ], "request_id":9201162933 } 出错响应示例：HTTP/1.1 400 Bad Request   { "error_code":31430, "error_msg":"bad record", "request_id":0 "records": [ ] } ## 删除record ### 功能 根据_key，删除record。 ### HTTP请求方式 POST ### URL https://pcs.baidu.com/rest/2.0/structure/data ### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | --- | --- | --- | --- | | v | string | 否 | 版本号，默认为“1.0”。 | | method | string | 是 | 固定值：delete。 | | access_token | string | 是 | 用户access_token，HTTPS调用时必须使用。 | | table | string | 是 | 要删除的目标表名。 | | records | json array | 是 | 需要删除的record _key 数组。 | | op | string | 否 | * 当值为“permanent”时，永久删除record；无论是普通record还是回收record。 * 当值为“recycled”时，将普通record放进回收站；缺省情况为放进回收站。 | ### 说明： #### 其中records是一个数组，其数组成员结构如下： | 名称 | 类型 | 是否必需 | 描述 | | --- | --- | --- | --- | | _key | string | 是 | 需要更新的record _key字段的值。 | | if-match | string | 否 | 类似update中的条件更新值为上次获取该item时返回的_mtime属性；只有server端保存的_mtime和用户携带的_mtime一致时，才会发生delete。 | 返回参数 | 参数名称 | 类型 | 描述 | | --- | --- | --- | | error_code | number | 错误码。如果不出错，则返回值没有该字段。 | | error_msg | string | 错误消息。如果不出错，则返回值没有该字段。 | | records | json array | 返回服务器端已经处理的records(_key, _mtime)列表，顺序与输入顺序一致，如果一个请求包含多个record，遇到第一个出错record即中止，返回的records 只包含已经处理成功的key。 | ### 示例 请求示例: $ cat > ./artists_delete_request <<DELIM { "table":"artists", "records": [ { "_key": "f44603de003c57d5-1346066442", "if-match": 1346066823 } ] } DELIM   $ curl -v -X POST "http://pcs.baidu.com/rest/2.0/structure/data?method=delete&access_token=2.b06c3e00010fdb879d12345dcd5f8545.2587600.134819999.1175746697-238347" -F "param=<artists_delete_request"   正确响应示例：HTTP/1.1 200 OK   { "records":[ { "_key":"f44603de003c57d5-1346066442", "_mtime":1346066823 } ], "request_id":9494352006 } 出错响应示例：HTTP/1.1 400 Bad Request   { "error_code":31430, "error_msg":"bad record", "request_id":0 "records": [ {"_key": "7d4febca4a68e763-1344915172"}, ] } ## 查询record ### 功能 通过一定条件查询record，只能select非回收站的record。 ### HTTP请求方式 POST ### URL https://pcs.baidu.com/rest/2.0/structure/data ### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | --- | --- | --- | --- | | v | string | 否 | 版本号，默认为“1.0”。 | | method | string | 是 | 固定值：select。 | | access_token | string | 是 | 用户的access_token，HTTPS调用时必须使用。 | | table | string | 是 | 查询的目标表名。 | | condition | json | 是 | 查询条件，参见查询条件描述。 | | projection | array | 否 | 指定需要哪些字段，_key为默认返回值。 | | order_by | array | 否 | 排序字段。 | | start | number | 否 | 分页用，默认为“0”，范围要求>=0。 | | limit | number | 否 | 分页用，默认为“100”，范围要求[1, 10000]。 | 所支持的查询条件如下表所示： | 查询条件 | 类型 | 表达查询条件 | 示例 | | --- | --- | --- | --- | | '=' | number/string | 表示范围查询= | "name": {"=": "刘德华"} | | '<' | number/string | 表示范围查询< | | | '>' | number/string | 表示范围查询> | "add_time": {">": 1340949589} | | '<=' | number/string | 表示范围查询<= | | | '>=' | number/string | 表示范围查询>= | "add_time": {">=": 1340949589} | | '!= ' | number/string | 不等于 | "add_time": {"!=": 1340949589} (coming soon) | | 'like' | string | SQL中like语法(不区分大小写) * 表示0到多个字符，_ 表示一个字符 | "message": {"like": "%windows%"} | | 'like_binary' | string | SQL中binary like语法（区分大小写） * 表示0到多个字符， _ 表示一个字符 | "message": {"like_binary": "%Windows%"} | | 'contain' | string | 包含在数组中 | "language": {"contain": "国语"} | | 'in' | array | in | "_key": {"in": ["_key1", "_key2"]} | | ‘notin’ | array | 不在集合中 | "_key": {"notin": ["_key1", "_key2"]} | 说明： （1）当“condition”条件为空时，表示获取所有record。 （2）根据key获取一条record，可使用如下condition条件表达： "_key": {"=": "385d24b3baef3290-1344915172"} （3）order_by表示支持的排序方式，它是一个数组，数组元素信息如下： | Key | Value | 描述 | | --- | --- | --- | | 列名 | asc/desc | 将某列按照“asc/desc”排序。 | 返回参数 (JSON格式) | 参数名称 | 类型 | 描述 | | --- | --- | --- | | error_code | number | 错误码，如果不出错，则返回值没有该字段。 | | error_msg | string | 错误提示，如果不出错，则返回值没有该字段。 | | count | number | 总条目数。 | | records | json array | record 数组。 | ### 示例 请求示例: 1. 简单查询 cat > ./artists_select_request <<DELIM { "table": "artists", "condition": { "and": [ { "name": { "=": "刘德华" } } ] }, "order_by" : [ {"add_time" : "desc" }, {"name" : "asc" } ], "start": 0, "limit": 10 } DELIM   curl -v -X POST "http://pcs.baidu.com/rest/2.0/structure/data?method=select&access_token=2.85e37d20acd37c3a5ebc9726bd5606eb.31536000.1384932826.1175746697-309847" -F "param=<artists_select_request" 2>/dev/null 2. 组合查询 cat > ./artists_select_request <<DELIM { "table": "artists", "condition": { "and": [ { "name": { "=": "刘德华" } }, { "tags": { "contain": "四大天王" } } ] }, "projection": ["name", "intro"] } DELIM   curl -v -X POST "http://pcs.baidu.com/rest/2.0/structure/data?method=select&access_token=2.85e37d20acd37c3a5ebc9726bd5606eb.31536000.1384932826.1175746697-309847" -F "param=<artists_select_request" 2>/dev/null 3. select 支持对嵌套属性的查询 cat > ./artists_select_request <<DELIM { "table": "artists", "condition": { "and": [ { "top_song.name": { "=": "爱你一万年" } } ] }, "projection": ["name", "intro"] } DELIM   curl -v -X POST "http://pcs.baidu.com/rest/2.0/structure/data?method=select&access_token=2.85e37d20acd37c3a5ebc9726bd5606eb.31536000.1384932826.1175746697-309847" -F "param=<artists_select_request" 2>/dev/null |./json_decode 4. or 条件支持 cat > ./artists_select_request <<DELIM { "table": "artists", "condition": { "or": [ { "name": { "=": "刘德华" } }, { "top_song.name": { "=": "月亮之上" } } ] }, "projection": ["name", "intro"] } DELIM   curl -v -X POST "http://pcs.baidu.com/rest/2.0/structure/data?method=select&access_token=2.85e37d20acd37c3a5ebc9726bd5606eb.31536000.1384932826.1175746697-309847" -F "param=<artists_select_request" 2>/dev/null 5. and/or 混合条件支持 cat > ./artists_select_request <<DELIM { "table": "artists", "condition": { "or": [ { "name": { "=": "刘德华" } }, { "and": [ { "top_song.name": { "=": "月亮之上" } }, { "tags": { "contain": "月亮之上" } } ]} ] }, "projection": ["name", "intro"] } DELIM   curl -v -X POST "http://pcs.baidu.com/rest/2.0/structure/data?method=select&access_token=2.85e37d20acd37c3a5ebc9726bd5606eb.31536000.1384932826.1175746697-309847" -F "param=<artists_select_request" 2>/dev/null 响应示例：{ "table":"artists", "count": 1, "start": 0, "limit": 0, "records": [ { "_key": "f44603de003c57d5-1346066442", "name": "刘德华", "intro": "香港著名歌手、演员", }, ] } ## record增量更新查询 ### 功能 数据更新增量查询接口。 ### HTTP请求方式 POST ### URL https://pcs.baidu.com/rest/2.0/structure/data ### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | --- | --- | --- | --- | | v | string | 否 | 版本号，默认为“1.0”。 | | method | string | 是 | 固定值：diff。 | | access_token | string | 是 | 用户的access_token，HTTPS调用时必须使用。 | | table | string | 是 | 要更新的目标表名。 | | cursor | string | 是 | 用于标记更新的游标。第一次调用时设置cursor=null，第二次调用时，使用上一次调用该接口的返回结果中的cursor。 | | projection | array | 否 | 指定需要哪些字段，“_key”、“_mtime”、“_ctime”是默认返回的。 | 返回参数 | 参数名称 | 类型 | 描述 | | --- | --- | --- | | error_code | number | 错误码。如果不出错，则返回值没有该字段。 | | error_msg | string | 错误提示。如果不出错，则返回值没有该字段。 | | table | string | 表名。 | | entries | array | record 数组。 | | reset | boolean | 客户端是否需要清空本地所有数据。True：表示服务器通知客户端清理所有本地数据，从头获取一份完整的数据列表。 | | has_more | boolean | 是否还有更新。 * True：本次调用diff接口结果无法一次返回，立刻再调用一次diff接口获取剩余结果； * False：已返回全部更新，等待一段时间（5分钟）之后再调用该接口查看是否有更新。 | | cursor | string | 游标，下次调用diff 接口，需要使用该参数 | 说明： （1）其中records是一个record数组，标志从上次调用该接口以来的更新操作： * 对于update后的record，会得到一个最新版的record； * 对于删除的record，得到的record中_isdelete字段为“1”。 （2）常见“reset=true”的场景如下： * 服务器端程序升级等，提示客户端重新拉去文件列表等。 （3）**注意：** #### diff接口有一定延迟（约10s），客户端不可假设新增record之后马上就会在diff 接口中获得更新。 示例 请求示例: 当创建了“刘德华”和“凤凰传奇”两个record后，第一次调用diff接口，使用cursor为null作为参数：   $ cat > ./artists_diff1_request <<DELIM { "table":"artists", "cursor" : "null", "projection": ["name", "intro"] } DELIM   $ curl -v -X POST "http://pcs.baidu.com/rest/2.0/structure/data?method=diff&access_token=2.b06c3e00010fdb879d12345dcd5f8545.2587600.134819999.1175746697-238347" -F "param=<artists_diff1_request" 返回： { "table":"artists", "entries": [ { "_key": "f44603de003c57d5-1346066442", "name": "刘德华", "intro": "香港著名歌手、演员", "_ctime":1345786801, "_mtime":1345786801, "_isdelete":0 }, { "_key": "1aaef0010c012db7-1346066442", "name": "凤凰传奇", "intro": "中国大陆具有广泛知名度的男女二人音乐组合", "_ctime":1345787059, "_isdelete":0, "_mtime":1345787666 } ], "cursor":"3861315431477246513534776b33573367765677314d595a6571724c69753574426133356f4f71316239342b5937577037766874316330493447465a346172445776504e45793235552b456f39796f4c6b307a30447a6f4e68774233616130362f63356f67586d66647879736f72686a70757a575a5342582b4c4b506479325431486f3937526333514a4a6d72626d7830574a35456d46705153454c4873614f6a6368743948743575386b45765477376a634e453848457737522f756d714235464d7a374372574b5777675134423231366a6f3431673d3d", "request_id":4060333081 } 此时如果删除了“刘德华”，再调用diff接口，应该使用刚才的cursor作为参数调用diff接口： $ cat > ./artists_diff2_request <<DELIM { "table":"artists","cursor":"3861315431477246513534776b33573367765677314d595a6571724c69753574426133356f4f71316239342b5937577037766874316330493447465a346172445776504e45793235552b456f39796f4c6b307a30442b6f6b4f585a7672687647426342783858576a524666316470356473754f6a364356674365366f53647979663646356649744747336e50694a44767a7258627a77473078572b327a366c4f674a4c757a76596e3843454b36496b59474153566c4447514c506632704c64494a5a764f337269546d6d454c6869676765367a4866513d3d", "projection": [ "name", "id" ] } DELIM   curl -i -X POST "http://pcs.baidu.com/rest/2.0/structure/data?method=diff&access_token=2.b06c3e00010fdb879d12345dcd5f8545.2587600.134819999.1175746697-238347" -F "param=artists_diff2_request" 得到的响应如下： { "table":"artists", "entries": [ { "id":85617, "name":"\u5218\u5fb7\u534e", "_ctime":1346066442, "_mtime":1346067702, "_isdelete":1, "_key":"f44603de003c57d51346066442" } ], "has_more":false, "reset":false,"cursor":"3861315431477246513534776b33573367765677314d595a6571724c69753574426133356f4f71316239342b5937577037766874316330493447465a346172445776504e45793235552b456f39796f4c6b307a304434436368685971496f4e544d446e326a6341505358767251356b79616244597a52745750436d544a327250703956444f7338593752737a4e32735a4d634233372f34416e454e4f3744474c4b4e6d726d64726f774e6b594a4e6553524a716d65743442553375696b354f585738474d376e4f635973507239636c6e5071585141673d3d", "request_id":1242060313 } ## 查询record（回收站） ### 功能 与select相同，只不过操作对象是回收站中。 ### HTTP请求方式 POST ### URL https://pcs.baidu.com/rest/2.0/structure/data ### 说明 该接口参数与select完全一样, 只不过操作对象是回收站中的records；返回的records中_isdelete为“1”。详细信息，请参考“查询record—select”。 ## 从回收站中恢复record ### 功能 从回收站中恢复文件。 ### HTTP请求方式 POST ### URL https://pcs.baidu.com/rest/2.0/structure/data ### 请求参数 | 参数名称 | 类型 | 是否必需 | 描述 | | --- | --- | --- | --- | | v | string | 否 | 版本号，默认为“1.0”。 | | method | string | 是 | 固定值：restore。 | | access_token | string | 是 | 用户的access_token，HTTPS调用时必须使用。 | | table | string | 是 | 要恢复的目标表名。 | | records | json array | 是 | 需要恢复的record _key数组。 | 说明： #### 其中records是一个数组，每个数组成员结构如下： | 名称 | 类型 | 是否必需 | 描述 | | --- | --- | --- | --- | | _key | string | 是 | 需要恢复的record _key字段的值。 | 返回参数 | 参数名称 | 类型 | 描述 | | --- | --- | --- | | error_code | number | 错误码。如果不出错，则返回值没有该字段 | | error_msg | string | 错误提示。如果不出错，则返回值没有该字段 | | records | json array | 返回服务器端已经处理的records(_key,_mtime)列表，顺序与输入顺序一致，如果一个请求包含多个record，遇到第一个出错record即中止，返回的records只包含已经处理成功的key。 | ### 示例 请求示例: $ cat > ./artists_restore_request <<DELIM { "table":"artists", "records": [ {"_key": "7d4febca4a68e763-1344915172"}, {"_key": "385d24b3baef3290-1344915172"} ] } DELIM   $ curl -v -X POST "http://pcs.baidu.com/rest/2.0/structure/data?method=restore&access_token=2.b06c3e00010fdb879d12345dcd5f8545.2587600.134819999.1175746697-238347" -F "param=<artists_restore_request"   正确响应示例：HTTP/1.1 200 OK { "records": [ { "_key":"7d4febca4a68e763-1344915172", "_mtime":1344927006 }, { "_key":"385d24b3baef3290-1344915172", "_mtime":1344927006 },   ] } 出错响应示例：HTTP/1.1 400 Bad Request { "error_code":31430, "error_msg":"key not exist", "request_id":0 "records": [ {'_key': "7d4febca4a68e763-1344915172"}, ] } ## 按条件更新record ### 功能 对符合一定条件的record 执行更新操作。 ### HTTP请求方式 POST ### URL https://pcs.baidu.com/rest/2.0/structure/data ### 请求参数 | 参数名称 | 类型 | 是否 必需 | 描述 | | --- | --- | --- | --- | | v | string | 否 | 版本号，默认为“1.0” | | method | string | 是 | 固定值：update | | type | string | 是 | 固定值：by-condition。 | | access_token | string | 是 | 用户的access_token，HTTPS调用时必须使用。 | | table | string | 是 | 查询的目标表名。 | | condition | json | 是 | 条件描述, 与select 中的condition一样。 | | action | json | 是 | 需要对命中的record进行的操作。 | #### 说明： ##### action为一个json字典，其格式为： "action": { column: {action: value} } ##### 如: "action": { "name": {"=": "LiuDeHua"} } #### 其中column 支持嵌套列。 * 所支持的action如下表所示： | action | 类型 | 描述 | 示例 | | --- | --- | --- | --- | | '=' | number/string | 表示将目标列设置为value。 | "name": {"=": "LiuDeHua"}, | | '+=' | number | 表示将目标列的值增加value，如果该列不存在，默认值为0。 | "age": {"+=":1}, | | '-=' | number | 表示将目标列的值减少value，如果该列不存在，默认值为0。 | "age": {"-=":1}, | 返回参数 (JSON格式) | 参数名称 | 类型 | 描述 | | --- | --- | --- | | error_code | number | 错误码，如果不出错，则返回值没有该字段。 | | error_msg | string | 错误提示，如果不出错，则返回值没有该字段。 | | request_id | number | 请求唯一标识ID。 | | affected | number | 返回受影响的行数。 | ### 示例 请求示例: cat > ./artists_update_request <<DELIM { "table": "artists", "condition": { "and": [ { "name": { "=": "刘德华" } } ] }, "action": { "name": {"=": "LiuDeHua"}, "age": { "+=": 1 } } } DELIM   curl -v -X POST "http://pcs.baidu.com/rest/2.0/structure/data?method=update&type=by-condition&access_token=2.85e37d20acd37c3a5ebc9726bd5606eb.31536000.1384932826.1175746697-309847" -F "param=<artists_update_request" 响应示例：{ "affected": 1, "request_id": 4060311005 } ## 按条件删除record ### 功能 对符合一定条件的record 执行删除操作。 ### HTTP请求方式 POST ### URL https://pcs.baidu.com/rest/2.0/structure/data ### 请求参数 | 参数名称 | 类型 | 是否 必需 | 描述 | | --- | --- | --- | --- | | v | string | 否 | 版本号，默认为“1.0”。 | | method | string | 是 | 固定值：delete。 | | type | string | 是 | 固定值：by-condition。 | | access_token | string | 是 | 用户的access_token，HTTPS调用时必须使用。 | | table | string | 是 | 查询的目标表名。 | | condition | json | 是 | 条件描述，与select 中的condition一样。 | 返回参数 (JSON格式) | 参数名称 | 类型 | 描述 | | --- | --- | --- | | error_code | number | 错误码，如果不出错，则返回值没有该字段。 | | error_msg | string | 错误提示，如果不出错，则返回值没有该字段。 | | request_id | number | 请求唯一标识ID。 | | affected | number | 返回受影响的行数。 | ### 示例 请求示例: cat > ./artists_update_request <<DELIM { "table": "artists", "condition": { "and": [ { "name": { "=": "LiuDeHua" } } ] } } DELIM   curl -v -X POST "http://pcs.baidu.com/rest/2.0/structure/data?method=delete&type=by-condition&access_token=2.85e37d20acd37c3a5ebc9726bd5606eb.31536000.1384932826.1175746697-309847" -F "param=<artists_update_request" 响应示例：{ "affected": 1, "request_id": 4060311005 } ## 按条件恢复record ### 功能 对回收站中符合一定条件的record 执行restore操作。 ### HTTP请求方式 POST ### URL https://pcs.baidu.com/rest/2.0/structure/data ### 请求参数 | 参数名称 | 类型 | 是否 必需 | 描述 | | --- | --- | --- | --- | | v | string | 否 | 版本号，默认为“1.0”。 | | method | string | 是 | 固定值：restore。 | | type | string | 是 | 固定值：by-condition。 | | access_token | string | 是 | 用户的access_token，HTTPS调用时必须使用。 | | table | string | 是 | 查询的目标表名。 | | condition | json | 是 | 条件描述, 与select 中的condition一样。 | 返回参数 (JSON格式) | 参数名称 | 类型 | 描述 | | --- | --- | --- | | error_code | number | 错误码，如果不出错，则返回值没有该字段。 | | error_msg | string | 错误提示，如果不出错，则返回值没有该字段。 | | request_id | number | 请求唯一标识ID。 | | affected | number | 返回受影响的行数。 | ### 示例 请求示例: cat > ./artists_update_request <<DELIM { "table": "artists", "condition": { "and": [ { "name": { "=": "LiuDeHua" } } ] } } DELIM curl -v -X POST "http://pcs.baidu.com/rest/2.0/structure/data?method=restore&type=by-condition&access_token=2.85e37d20acd37c3a5ebc9726bd5606eb.31536000.1384932826.1175746697-309847" -F "param=<artists_update_request" 响应示例：{ "affected": 1, "request_id": 4060311005 } --- ## File: docs/structured_data_apis_error.md # 结构化数据API错误码 结构化数据API以HTTP提供，因此请求者应首先检查HTTP协议级别的响应状态码。 当请求有错误或执行失败时，HTTP协议的返回响应状态码不为“200”，且在Content-body的JSON格式数据中以error_code给出错误码，并可能以error_msg字段提示错误信息。错误码的详细信息，请参考以下错误码列表。 一般来说, 错误分为客户端错误和服务器端错误： * 客户端错误： 返回状态码4xx表示结构化数据平台认为客户端请求有错误，例如：auth失败，参数不对，超出quota等。这些情况，客户端需要先解决参数问题，再向服务器端重新发起请求。 * 服务器端错误： 返回状态码为5xx，表示结构化数据平台内部发生错误，客户端需要重试。 ## 注意 请求成功时，HTTP协议的返回响应状态码为“200”，不会设置error_code和error_msg。 ## 结构化数据API错误码 | HTTP状态码 | 错误码 | 错误信息 | 备注 | 是否重试 | | - | :- | :- | :- | - | | 500 | 1 | Unknown error | 未知错误 | 是 | | 500 | 2 | Service temporarily unavailable | 服务暂不可用 | 是 | | 403 | 6 | No permission to access user data | 无权访问用户数据 | 否 | | 403 | 7 | No permission to access data for this referer | 无权访问数据 | 否 | | 400 | 100 | Invalid parameter | 无效参数 | 否 | | 401 | 101 | Invalid API key | 无效API Key | 否 | | 401 | 102 | Session key invalid or no longer valid | 会话密钥无效 | 否 | | 401 | 103 | Invalid/Used call_id parameter | call_id参数无效/已被使用 | 否 | | 400 | 104 | Incorrect signature | 签名错误 | 否 | | 400 | 105 | Too many parameters | 参数过多 | 否 | | 400 | 106 | Unsupported signature method | 不支持此签名方式 | 否 | | 400 | 107 | Invalid/Used timestamp parameter | 时间戳无效 | 否 | | 401 | 108 | Invalid user id | 用户ID无效 | 否 | | 400 | 109 | Invalid user info field | 用户信息字段无效 | 否 | | 401 | 110 | Access token invalid or no longer valid | Access token无效或已失效 | 否 | | 401 | 111 | Access token expired | Access token已过期 | 否 | | 401 | 112 | Session key expired | 会话密钥已过期 | 否 | | 400 | 114 | Invalid Ip | 无效IP | 否 | | 400 | 31400 | param error | 参数错误 | 否 | | 400 | 31401 | malformed json | JSON格式错误 | 否 | | 400 | 31402 | no "table" in request | 请求中没有“table”字段 | 否 | | 400 | 31403 | no "records" in request | 请求中没有“records”字段 | 否 | | 400 | 31405 | too many records in request | 请求中的records 过多，目前限制为500 | 否 | | 400 | 31406 | bad columnname | 列名非法，请参考API文档 | 否 | | 400 | 31407 | record too large | record过大，> 1M | 否 | | 400 | 31408 | bad table name | table名称不合法 | 否 | | 400 | 31409 | table not exist | table不存在，请先创建 | 否 | | 400 | 31410 | bad record | record格式错误，请检查JSON | 否 | | 400 | 31411 | no appid | 请求中没有“app_id”字段 | 否 | | 400 | 31412 | no userid | 请求中没有“user_id”字段 | 否 | | 400 | 31420 | bad condition | condition描述错误。 | 否 | | 400 | 31421 | bad projection | projection描述错误 | 否 | | 400 | 31422 | bad order_by | order_by描述错误 | 否 | | 400 | 31423 | bad operator | condition中的operation 非法 | 否 | | 400 | 31424 | bad start/limit | start/limit 错误 | 否 | | 400 | 31425 | unsupported operator | 操作符暂未支持，如：or、like、regex等 | 否 | | 400 | 31430 | no key in record | update/delete 请求，但是record 中没有_key 字段 | 否 | | 400 | 31431 | record not exist | 符合条件的record不存在，比如if-match不匹配、在回收站等 | 否 | | 400 | 31432 | unknown op | 参数op非法 | 否 | | 400 | 31433 | bad key | key非法 | 否 | | 400 | 31440 | param cursor not set | 参数cursor未设值 | 否 | | 400 | 31441 | param cursor format error | 参数cursor格式错误 | 否 | | 400 | 31442 | param cursor appid wrong | 参数cursor appid错误 | 否 | | 400 | 31443 | param cursor user_id wrong | 参数cursor user_id错误 | 否 | | 400 | 31450 | exceed quota | 超出配额 | 否 | | 400 | 31451 | quota size param not exist | 找不到参数quota size | 否 | | 503 | 31452 | quota info fail | quota info失败 | 是 | | 400 | 31453 | quota too big | quota过大 | 否 | | 400 | 31454 | quota size param not numeric | quota size 参数未数值化 | 否 | | 400 | 31460 | no permission | 未授权 | 否 | | 400 | 31461 | account not login | 账户为登录，使用bduss认证失败 | 否 | | 400 | 31462 | access token error | access token校验失败 | 否 | | 400 | 31470 | index num too much | index num太多 | 否 | | 400 | 31472 | table already exist | table已存在 | 否 | | 400 | 31473 | abnormal table already exist | 异常table已存在 | 否 | | 400 | 31474 | table not drop, cannot restore | table不在回收站，无法恢复 | 否 | | 400 | 31475 | engine not support | 不支持此项操作 | 否 | | 400 | 31480 | param op wrong, should be recycled or permanent | 参数op错误，应为可回收或永久的 | 否 | | 400 | 31490 | api not support | 调用了错误的API | 否 | | 500 | 31500 | Internal error (Try Again Later) | 内部错误 | 是 | | 503 | 31501 | storeengine construct fail | construct失败 | 是 | | 503 | 31502 | storeengine select fail | 选择操作失败 | 是 | | 503 | 31503 | storeengine insert fail | 插入操作失败 | 是 | | 503 | 31504 | storeengine update fail | 更新操作失败 | 是 | | 503 | 31505 | storeengine delete fail | 删除操作失败 | 是 | | 503 | 31506 | storeengine count fail | count操作失败 | 是 | | 503 | 31507 | storeengine ensure index fail | 查询或创建索引失败 | 是 | | 503 | 31508 | storeengine delete index fail | 删除索引失败 | 是 | | 503 | 31509 | storeengine drop table fail | 删除table操作失败 | 是 | | 503 | 31530 | config set num match fail | 配置中num匹配失败 | 是 | | 503 | 31590 | db query error | db交互出错 | 是 | | 503 | 31591 | network error | 内部网络交互错误 | 是 | --- ## File: docs/structured_data_apis_overview.md # 结构化数据API说明 ## 结构化数据API简要说明 结构化数据API包括table操作API和record操作API。 * Table操作API： 是由开发者在使用结构化数据API开发应用时调用，包括创建、修改、删除、查看表信息及恢复表等接口； * Record操作API： 即数据操作API，是由最终用户在使用基于PCS结构化数据API开发的应用时触发，第三方应用通过使用用户身份（以Access Token认证）在服务器端对用户数据进行增加、删除、修改、查询等系列操作。 ## 结构化数据基本概念 1. 表（table） 结构化数据以表为单位组织用户数据；表名和表中的索引由开发者定义。 2. 表名（tablename） 表的名字。表名可以由字母和下划线组成（a-z，A-Z，0-9，'_'）, 长度为3-63个字符，必须字母开头；同一个应用中，不能重复使用同一表名。 3. 记录（record） 每一条结构化数据就是一个记录，一个表中可有多条记录。 4. 列（column） 结构中的每一个字段就是一列。列名可以由字母和下划线组成（a-z，A-Z，0-9，'_'）, 长度为1-255个字符，必须字母开头。 5. 索引（index） 在表中的某些列上创建索引，可以提高查询速度。一个表中，最多可以定义5个索引，只能定义普通索引。 6. 限额（quota） 同一个表中同一个用户最多多少条数据，现在每个用户最多10000条数据。 ## 结构化数据功能列表 使用PCS结构化数据功能，可以轻松的完成应用上结构化数据的存储及同步等功能。 PCS结构化数据具有如下的特性： * 提供Restful API； * 数据灵活性大：定义表时，不需要完全确定表中的所有列，可以增加一列或减少一列而无需重新定义表。 * 在数据上动态增减索引：定义表时，无需完全确定所有的索引； * 数据多端同步：结构化数据提供接口，支持数据多端同步； * 对数据进行增加、删除、修改及查询； * 回收站：数据删除后，10天内可以还原； * 支持应用数据隔离：不同应用的数据可以支持物理隔离； * 支持超大数据量： * 一个应用可以创建5个表； * 单个表没有数据总量限制； * 单个表中，单个用户的数据量可以达到1万条； * 用户数无限制。 ## 结构化数据存储限制 ### （1）全局限制： 每个记录的大小限制为1MB （服务器端会把记录做json_encode, 得到的大小为记录大小）； 每个应用最多只能创建5个表； 批量的insert/update/delete/restore每次最多500条； 批量的select每次最多返回10000条记录。 ### （2）表级别限制（quota）： 应用上的用户在表里的条目数限制（创建表的时候，每个表都有一个default_quota，以后用户在该表上都使用此default_quota，单个用户的quota可以通过quota接口设置）。 ## Record操作API说明 ### （1） insert、update、delete默认都支持批量操作，但是每次批量的record个数不能超过500； ### （2） 数据操作API对用户需要保持最终一致性，即： insert、update、delete操作不保证返回后即可select 出来，通常延迟小于1s； update、delete操作不支持条件操作，即where子句的操作，如有需要请先select出来。 ## 字段说明 ### 字段定义 #### PCS结构化数据平台中，表中的字段支持如下类型： | 字段类型 | 描述 | | :- | :- | | string | 字符串。 | | int | 整型数字，64位有符号，范围为[-9223372036854775808, 9223372036854775807]，超出范围自动转为float。 | | float | 带小数点的数字。 | | boolean | true 或者false。 | | array | 数组，元素可以是string/number。 | | object | 可以是一个json 对象。 | | null | null | #### 说明： 字段名必须符合以下标准: 可以是a-z、A-Z、0-9、'_'； 长度范围是[1, 255]； 必须字母开头。 ### 默认字段 #### 插入的记录将会有以下默认字段： | 字段 | 类型 | 描述 | | :- | :- | :- | | _key | string | 全局唯一key i string(16)。 | | _ctime | int | record创建时间。 | | _mtime | int | record修改时间。 | | _isdelete | int | 是否删除。 |