SDK 使用文档
PHP SDK¶
又拍云 PHP SDK 托管在 github ，它包含如下功能：1）存储管理；2）图片处理；3）音视频处理；4）缓存刷新。本段介绍 PHP SDK 的使用。
开发准备¶
运行环境
PHP SDK version 3.0，需要 PHP 版本 >= 5.5。您可以通过 php -v 命令查看当前的 PHP 版本。
安装
- Composer 方式
Composer 是 PHP 的依赖管理工具。您可以在自己的项目中声明所依赖的外部工具库，Composer 会自动帮您安装这些依赖的库文件。
在项目根目录运行：
composer require upyun/sdk
- 源码方式
如果使用 Composer 方式较慢，可以直接下载 SDK 包，放到项目根目录，然后把包导入工程中。
初始化¶
Config（配置）和 Upyun（连接）是 PHP SDK 的初始化类，在操作云存储、云处理之前，需要先实例化它们。
<?php
// 包含文件
require_once('vendor/autoload.php');
use Upyun\Upyun;
use Upyun\Config;
// 创建实例
$bucketConfig = new Config('您的服务名', '您的操作员名', '您的操作员密码');
$client = new Upyun($bucketConfig);
?>
说明，为了避免重复，后续 「功能使用」 中的 DEMO 不再包含这段代码，请在使用时注意。
功能使用¶
列表：文件上传、文件删除、目录创建和删除、列目录、获取文件信息、获取服务容量
<?php
// 省略初始化代码
// 读文件
$file = fopen('/root/13.jpg', 'r');
// 上传文件
$res = $client->write('/up/dd.jpg', $file);
// 打印上传结果
print_r($res);
?>
说明，/root/13.jpg 为本地文件绝对路径，/up/dd.jpg 为保存到又拍云存储的路径及文件名。
<?php
// 省略初始化代码
// 读文件
$file = fopen('/root/13.jpg', 'r');
// 添加作图参数
$tasks = array('x-gmkerl-thumb' => '/format/png/fw/100');
// 上传文件
$res = $client->write('/up/dd.png', $file, $tasks);
// 打印上传结果
print_r($res);
?>
说明，上传图片同时，对图片进行处理，把处理后的图片存进存储。具体详见图片处理（同步）。
<?php
// 省略初始化代码
// 单文件删除
$res=$client->delete('/up/dd.txt');
echo $res;
?>
说明，/up/dd.txt 为文件在又拍云存储的路径。结果为 1，表示删除成功。异常直接抛出。
<?php
// 省略初始化代码
// 创建目录
$res=$client->createDir('/up/tt/ss');
echo $res;
// 删除空目录
$res=$client->deleteDir('/up/tt/ss');
echo $res;
?>
说明，/up/tt/ss 为目录的路径。结果为 1，表示成功。异常直接抛出。
<?php
// 省略初始化代码
$res=$client->info('/up/dd.jpg');
print_r($res);
?>
说明，/up/dd.jpg 为文件在又拍云存储的路径。结果以数组形式返回，内容包括：文件类型、文件大小和文件最后修改时间。
<?php
// 省略初始化代码
$res=$client->usage();
echo $res;
?>
说明，结果为容量数值，单位字节。异常直接抛出。
Java SDK¶
又拍云 Java SDK 托管在 github ，它包含如下功能：1）存储管理；2）图片处理；3）音视频处理；4）缓存刷新。本段介绍 Java SDK 的使用。
开发准备¶
运行环境
Java SDK version 3.0+，需要 Java 版本 >= 6。可以通过 java -version 命令查看当前的 Java 版本。
安装
- Maven 方式
Maven 是一个项目管理及自动构建工具。您可以在自己的项目中声明所依赖的外部工具库，Maven 会自动帮您安装这些依赖的库文件。
<dependency>
<groupId>com.upyun</groupId>
<artifactId>java-sdk</artifactId>
<version>4.0.1</version>
</dependency>
- 源码方式
除了 Maven 方式外，还可以直接下载 SDK 包，放到项目根目录，然后把包导入工程中。
初始化¶
UpYun 是 Java SDK 的初始化类，在操作云存储、云处理之前，需要先实例化它。
// 创建实例
UpYun upyun = new UpYun('您的服务名', '您的操作员名', '您的操作员密码');
// 可选属性1，是否开启 debug 模式，默认不开启
upyun.setDebug(false);
// 可选属性2，超时时间，默认 30s
upyun.setTimeout(30);
说明，为了避免重复，后续 「功能使用」 中的 DEMO 不再包含初始化这段代码，请在使用时注意。
功能使用¶
列表：文件上传、表单上传、文件删除、目录创建和删除、列目录、获取文件信息、获取服务容量
REST API、FORM API
// 文件上传
upyun.setContentMD5(UpYun.md5('/root/13.jpg')); // 计算文件 MD5，如果文件太大或计算不便，可以不计算
boolean result4 = upyun.writeFile('/up/dd.jpg', '/root/13.jpg');
说明，/root/13.jpg 为本地文件绝对路径，/up/dd.jpg 为保存到又拍云存储的路径及文件名。
// 定义保存路径
String savePath = "/uploads/{year}{mon}{day}/{random32}{.suffix}";
paramsMap.put(Params.SAVE_KEY, savePath);
// 上传文件
FormUploader uploader = new FormUploader(BUCKET_NAME, APIKEY, null);
Result result = uploader.upload(paramsMap, file); // file（File 类型） 表示一个待上传的文件
说明，savePath 的解释详见 FORM API 路径设置。
上传预处理
// 文件上传
boolean result3 = upyun.writeFile('/up/dd.jpg', '/root/13.jpg');
// 图片上传预处理（同步）
params.put(“x-gmkerl-thumb”,"/fw/300/unsharp/true/quality/80/format/png")
// 单个文件删除
boolean result = upyun.deleteFile('/up/dd.jpg');
说明，/up/dd.jpg 为文件的路径。
// 创建目录
boolean result = upyun.mkDir('/up/tt/');
// 删除目录
boolean result = upyun.rmDir('/up/tt/');
说明，/up/tt/ 为目录的路径。
List<UpYun.FolderItem> items = upyun.readDir('/up/tt/');
说明，/up/tt/ 为目录的路径。结果返回目录下前 10000 个文件列表，超出 10000 个的不会返回，如果需要列出来，需要使用分页参数循环获取，直到取完。
Map<String,String> result = upyun.getFileInfo('/up/dd.jpg');
说明，/up/dd.jpg 为文件在又拍云存储的路径。结果以 Map 形式返回，内容包括：文件类型、文件大小和文件最后修改时间。
long usage = upyun.getBucketUsage();
说明，结果为容量数值，单位字节。
Python SDK¶
又拍云 Python SDK 托管在 github ，它包含如下功能：1）存储管理；2）图片处理；3）音视频处理；4）缓存刷新。本段介绍 Python SDK 的使用。
开发准备¶
运行环境
- Python SDK version 2.2+，适用于 Python 2.6、2.7、3.3、3.4 版本。可以通过
python -V命令查看当前的 Python 版本。 - Python SDK version 2.3+，不再直接使用默认标准库 httplib，使用基于 httplib 的 requests 这个第三方库。
安装
- pip 方式
pip 是 Python 的依赖管理工具。您可以在自己的项目中声明所依赖的外部工具库，pip 会自动帮您安装这些依赖的库文件。
安装 requests
pip install requests
安装 Python SDK
pip install upyun
运行测试用例，判断安装成功与否
# 配置参数
export UPYUN_SERVICE=<service>
export UPYUN_USERNAME=<username>
export UPYUN_PASSWORD=<password>
# 执行测试用例
make init test
- 源码方式
除了 pip 方式外，还可以直接下载 SDK 包，放到项目根目录，然后把包导入工程中。
初始化¶
UpYun 是 Python SDK 的初始化类，在操作云存储、云处理之前，需要先实例化它。
# 包含文件
import upyun
# 创建实例
up = upyun.UpYun('您的服务名', '您的操作员名', '您的操作员密码')
说明，为了避免重复，后续 「功能使用」 中的 DEMO 不再包含初始化这段代码，请在使用时注意。
功能使用¶
列表：文件上传、表单上传、断点续传上传、文件删除、目录创建和删除、列目录、获取文件信息、获取服务容量
/*
* 参数说明
* checksum，表示是否进行 MD5 校验，如果是小文件，建议进行，为 True；如果是大文件，建议不进行，为 False
* headers，表示需要的头信息，见 REST API 上传文件
*/
headers = { 'x-gmkerl-thumb': '/fw/300' }
with open('dd.png', 'rb') as f:
res = up.put('/up/dd.png', f, checksum=True, headers=headers)
说明，上传成功，如果是图片，返回包含图片宽、高、格式、帧数的 Python Dict 对象，如果不是，是空 Python Dict 对象；上传失败，抛出异常。
// 设定参数
kwargs = { 'allow-file-type': 'jpg,jpeg,png',
'notify-url': 'http://notify-url/',
'x-gmkerl-thumb':'/fw/300' }
// checksum，表示是否进行 MD5 校验，如果是小文件，建议进行，为 True；如果是大文件，建议不进行，为 False
with open('dd.png', 'rb') as f:
res = up.put('/up/dd.png', f, checksum=True, form=True, **kwargs)
说明，上传成功，返回内容见 FORM API 的通知设置；上传失败，抛出异常。
from upyun import FileStore
from upyun import print_reporter
/*
* 参数说明
* need_resume，表示是否需要断点续传，默认 False
* headers，表示需要的头信息，，见 REST API 断点续传
* store，表示断点信息存储位置，默认 memory_store。memory_store 表示存放在内存，FileStore() 表示存放在文件，默认是 ~/.up-python-resume/
* reporter，表示报告上传进度，默认忽略。print_reporter 只是 print 上传进度，有其他需要的用户可以自行实现
*/
with open('dd.png', 'rb') as f:
res = up.put('/up/dd.png', f, checksum=True, need_resume=True, headers={}, store=None, reporter=print_reporter)
说明，上传成功，返回空 Python Dict 对象；上传失败，抛出异常。
up.delete('/up/dd.png')
说明，成功，返回 Python None 对象；失败，抛出异常。
up.mkdir('/up/temp/') // 创建
up.delete('/up/temp/') // 删除
说明，成功，返回 Python None 对象；失败，抛出异常。注，目录删除只能删除空目录。
res = up.getlist('/up/', limit=100, order='asc', begin='')
说明，获取成功，返回 Python List 对象；获取失败，抛出异常。
res = up.getinfo('/up/dd.png')
print res['file-type']
print res['file-size']
print res['file-date']
说明，获取成功，返回 Python List 对象，内容包括：文件类型、文件大小和文件最后修改时间；获取失败，抛出异常。
res = up.usage()
说明，获取成功，返回 Python String 对象，单位 Bytes；获取失败，抛出异常。