Image Server 使用帮助

SDK

1. PHP SDK

PHP SDK[下载]

此 SDK 适用于 PHP 5.1.0 及其以上版本。基于得图云存储HTTP REST API接口 构建。使用此 SDK 构建您的网络应用程序,能让您以非常便捷地方式将数据安全地存储到得图云存储上。无论您的网络应用是一个网站程序,还是包括从云端(服务端程序)到终端(手持设备应用)的架构的服务或应用,通过得图云存储及其 SDK,都能让您应用程序的终端用户高速上传和下载,同时也让您的服务端更加轻盈。

1.1 应用接入

(1) 获取Access Key 和 Secret Key

要接入得图云存储,您需要拥有一对有效的 Access Key 和 Secret Key 用来进行签名认证。可以通过如下步骤获得:

登录得图云开发者自助平台,查看 Access Key 和 Secret Key 。

1.2 使用说明

(1)设置初始参数
require_once('detuyun.class.php');
$detuyun = new DetuYun('bucketname',  Access Key, Secret Key);

参数 bucketname 为空间名称。

示例代码如下:

$detuyun = new DetuYun('bucketname', Access Key, Secret Key);

超时时间设置在初始化DetuYun上传时,可以选择设置上传请求超时时间(默认30s):

$detuyun = new DetuYun('bucketname',  Access Key, Secret Key, 600);

(2) 上传文件
// 直接传递文件内容的形式上传
$detuyun->writeFile('/temp/text_demo.txt', 'Hello World', True);

// 数据流方式上传,可降低内存占用
$fh = fopen('demo.png', 'r');
$detuyun->writeFile('/temp/upload_demo.png', $fh, True);
fclose($fh);

第三个参数为可选。True 表示自动创建相应目录,默认值为False。

本方法还有一个数组类型的可选参数,用来设置文件类型、缩略图处理等参数。

$opts = array(
    X_GMKERL_THUMBNAIL => 'square' // 缩略图版本,仅适用于图片空间
);

$fh = fopen('demo.png', 'r');
$detuyun->writeFile('/temp/upload_demo.png', $fh, $opts);
fclose($fh);

该参数可以设置的值还包括:

  • CONTENT_TYPE
  • CONTENT_MD5
  • X_GMKERL_THUMBNAIL
  • X_GMKERL_TYPE
  • X_GMKERL_VALUE
  • X_GMKERL_QUALITY

参数的具体使用方法,请参考 标准API上传文件

文件空间上传成功后返回True,图片空间上传成功后一数组形式返回图片信息:

array(
  'x-detuyun-width' => 2000,
  'x-detuyun-height' => 1000,
  'x-detuyun-frames' => 1
  'x-detuyun-type' => "JPEG"
)

如果上传失败,则会抛出异常。

(3) 下载文件
// 直接读取文件内容
$data = $detuyun->readFile('/temp/upload_demo.png');

// 使用数据流模式下载,节省内存占用
$fh = fopen('/tmp/demo.png', 'w');
$detuyun->readFile('/temp/upload_demo.png', $fh);
fclose($fh);

直接获取文件时,返回文件内容,使用数据流形式获取时,成功返回True。 如果获取文件失败,则抛出异常。

(4)创建目录
$detuyun->mkDir('/demo/');

目录路径必须以斜杠 / 结尾,创建成功返回 True,否则抛出异常。

(5)删除目录或者文件
$detuyun->delete('/demo/'); // 删除目录
$detuyun->delete('/demo/demo.png'); // 删除文件

删除成功返回True,否则抛出异常。注意删除目录时,必须保证目录为空 ,否则也会抛出异常。

(6)获取目录文件列表
$list = $detuyun->getList('/demo/');
$file = $list[0];
echo $file['name']; // 文件名
echo $file['type']; // 类型(目录: folder; 文件: file)
echo $file['size']; // 尺寸
echo $file['time']; // 创建时间
echo $file['filetype']; //定义文件类型

获取目录文件以及子目录列表。需要获取根目录列表是,使用 $detuyun->getList('/') ,或直接用方法不传递参数。 目录获取失败则抛出异常。

(7)获取文件信息
$result = $detuyun->getFileInfo('/demo/demo.png');
$arr = explode("\t",$result["x-detuyun-file"]);

获取文件信息时通过Tab键分隔获取相应内容,返回结果为一个数组。

(8)获取空间使用状况
$detuyun->getFolderUsage(); // 获取Bucket空间使用情况
$detuyun->getFolderUsage('/demo/'); 获取目录空间使用情况

返回的结果为空间使用量,单位 kb

1.3 异常处理

当API请求发生错误时,SDK将抛出异常,具体错误代码请参考 标准API错误代码表

根据返回HTTP CODE的不同,SDK将抛出以下异常:

  • DetuYunAuthorizationException 401,授权错误
  • DetuYunForbiddenException 403,权限错误
  • DetuYunNotFoundException 404,文件或目录不存在
  • DetuYunNotAcceptableException 406, 目录错误
  • DetuYunServiceUnavailable 503,系统错误

未包含在以上异常中的错误,将统一抛出 DetuYunException 异常。

为了真确处理API请求中可能出现的异常,建议将API操作放在try{...}catch(Exception $e){…} 块中

try{
    $detuyun->getFolderUsage('/demo/');
    ...
}
catch(Exception $e) {
    echo $e->getCode();     // 错误代码
    echo $e->getMessage();  // 具体错误信息
}

2. C# SDK

CSharp SDK [下载]

此 CSharp SDK 适用于.net framework>4.0版本,基于 得图云存储官方API 构建。使用此 SDK 构建您的网络应用程序,能让您以非常便捷地方式将数据安全地存储到得图云云存储上。无论您的网络应用是一个网站程序,还是包括从云端(服务端程序)到终端(手持设备应用)的架构的服务或应用,通过得图云存储及其 SDK,都能让您应用程序的终端用户高速上传和下载,同时也让您的服务端更加轻盈。

2.1 应用接入

获取Access Key 和 Secret Key

要接入得图云存储,您需要拥有一对有效的 Access Key 和 Secret Key 用来进行签名认证。可以通过如下步骤获得:

登录得图云开发者自助平台,查看 Access Key 和 Secret Key 。

2.2 使用说明

(1)初始化DetuYun
    public DetuYun(string bucketname, string username, string password)
    {
        this.bucketname = bucketname;
        this.username = username;
        this.password = password;
    }

参数bucketname为空间名称,username为Access Key,password为Access Secret。

示例代码如下:

DetuYun detuyun = new DetuYun("moriaty", "ifzdm129", "xsgam6abjrmm2jytcnc4enzwpu8wtd");

超时时间设置 在初始化DetuYun上传时,可以选择设置上传请求超时时间(默认30s):

DetuYun detuyun = new DetuYun("moriaty", "ifzdm129", "xsgam6abjrmm2jytcnc4enzwpu8wtd",600);

(2)上传文件
// 直接传递文件内容的形式上传
bool b = detuyun.writeFile('/temp/text_demo.txt', 'Hello World', True);
Console.WriteLine(b);

// 数据流方式上传,可降低内存占用
Hashtable headers = new Hashtable();
FileStream fs = new FileStream("f:\\picture\\detu1.jpg", FileMode.Open, FileAccess.Read);
BinaryReader r = new BinaryReader(fs);
byte[] postArray = r.ReadBytes((int)fs.Length);
bool b = detuyun.writeFile("/a/test.jpg", postArray, true);
Console.WriteLine(b);

上传成功返回true,上传失败则抛出异常。

(3)下载文件
    byte[] contents = detuyun.readFile("/a/test.jpg");
        Console.WriteLine(contents.Length);

下载成功,返回文件内容; 失败则抛出相应异常。

(4)创建目录
detuyun.mkDir("/b/ccc",true)

创建目录时可使用 detuyun.mkDir("/a/b/c", true)进行父级目录的自动创建,最深10级目录。目录路径必须以斜杠 / 结尾,创建成功返回 True,否则抛出异常。

(5)删除目录或者文件
Console.WriteLine(detuyun.rmDir("/a/"));//删除目录
Console.WriteLine(detuyun.deleteFile("/dc1/my.jpg"));//删除文件

删除成功返回True,否则抛出异常。注意删除目录时,必须保证目录为空 ,否则也会抛出异常。

(6)获取目录文件列表
    public ArrayList readDir(string url)
    {
        Hashtable headers = new Hashtable();
        byte[] a = null;
        HttpWebResponse resp = newWorker("GET", DL + this.bucketname + url, a, headers);
        StreamReader sr = new StreamReader(resp.GetResponseStream(), Encoding.UTF8);
        string strhtml = sr.ReadToEnd();
        resp.Close();
        strhtml = strhtml.Replace("\t", "\\");
        strhtml = strhtml.Replace("\n", "\\");
        string[] ss = strhtml.Split('\\');
        int i = 0;
        ArrayList AL = new ArrayList();
        while (i < ss.Length)
        {
            FolderItem fi = new FolderItem(ss[i], ss[i + 1], int.Parse(ss[i + 2]), int.Parse(ss[i + 3]), ss[i + 4]);
            AL.Add(fi);
            i +=6;
        }
        return AL;
    }

获取目录文件以及子目录列表。需要获取根目录列表是,使用 string[] ss = strhtml.Split('\\'); ,或直接表用方法不传递参数。 目录获取失败则抛出异常。

(7)获取文件信息
    public Hashtable getFileInfo(string file)
    {
        Hashtable headers = new Hashtable();
        byte[] a = null;
        HttpWebResponse resp = newWorker("HEAD", DL + this.bucketname + file, a, headers);
        resp.Close();
        Hashtable ht;
        string  tmp = this.tmp_infos["x-detuyun-file"].ToString();
        string[] info = tmp.Split('\t');
        try
        {
            ht = new Hashtable();
            ht.Add("name",info[0]);
            ht.Add("type", info[1]);
            ht.Add("size", info[2]);
            ht.Add("date", info[3]);

        }
        catch (Exception)
        {
            ht = new Hashtable();
        }
        return ht;
    }

获取文件信息时通过Tab键分隔获取相应内容,返回结果为一个数组。

(8)获取空间使用状况
    public int getFolderUsage(string url)
    {
        Hashtable headers = new Hashtable();
        int size;
        byte[] a = null;
        HttpWebResponse resp = newWorker("GET", DL + this.bucketname + url + "?usage", a, headers);
        try
        {
            StreamReader sr = new StreamReader(resp.GetResponseStream(), Encoding.UTF8);
            string strhtml = sr.ReadToEnd();
            resp.Close();
            size = int.Parse(strhtml);
        }
        catch (Exception ex)
        {
            size = 0;
        }
        return size;
    }

示例代码:

var s = detuyun.getFolderUsage("/");

返回的结果为空间使用量,单位 kb

返回的结果为空间使用量,单位 kb

2.3 异常处理

当API请求发生错误时,SDK将抛出异常,具体错误代码请参考 标准API错误代码表

根据返回HTTP CODE的不同,SDK将抛出以下异常:

  • DetuYunAuthorizationException 401,授权错误
  • DetuYunForbiddenException 403,权限错误
  • DetuYunNotFoundException 404,文件或目录不存在
  • DetuYunNotAcceptableException 406, 目录错误
  • DetuYunServiceUnavailable 503,系统错误

未包含在以上异常中的错误,将统一抛出 DetuYunException 异常。

3. Python SDK

Python SDK[下载]

得图云存储 Python SDK,基于得图云存储 HTTP REST API 接口 开发。该SDK不再兼容 1.x 的版本,相比旧版本,新版接口设计和实现更加 Pythonic ,且代码风格完全符合 pep8 规范。

3.1 应用接入

获取Access Key 和 Secret Key

要接入得图云存储,您需要拥有一对有效的 Access Key 和 Secret Key 用来进行签名认证。可以通过如下步骤获得:

  1. 登录得图云开发者自助平台,查看 Access Key 和 Secret Key 。

3.2 使用说明

(1)初始化 DetuYun
import detuyun

dt = detuyun.DetuYun('bucket', 'username', 'password', timeout=30)

其中,参数 bucket 为空间名称,usernamepassword 分别为授权操作员帐号和密码,必选。

参数 timeout 为 HTTP 请求超时时间,默认 60 秒,可选。

根据网络状况,得图云存储 API 默认设置接入点为:ED_HOST=s.detuyun.com,并自动接入。

(2)上传文件
直接传递文件内容的形式上传
res = dt.put(rootpath + 'ascii.txt', ascii(), checksum=True)

其中,方法 dt.put 默认已开启相应目录的自动创建。

数据流方式上传,可降低内存占用
headers = {"x-gmkerl-rotate": "180"}
with open('unix.png', 'rb') as f:
    res = dt.put(rootpath + 'xinu.png', f, checksum=False,
        headers=headers)

其中,参数 checksumheaders 可选,前者默认 False,表示不进行 MD5 校验; 后者可根据需求设置自定义 HTTP Header,例如作图参数 x-gmkerl-*, 具体请参考 标准 API 上传文件

上传成功,如果当前空间是图片空间,那么 res 返回的是一个包含图片长、宽、帧数和类型信息的 Python Dict 对象 (文件空间,返回一个空的 Dict):

{ 'width': '1280', 'height': '800', 'frames': '1','type': 'PNG'}

上传失败,则抛出相应异常。

(3) 下载文件
直接读取文件内容
res = dt.get(rootpath + 'ascii.txt')

下载成功,返回文件内容; 失败则抛出相应异常。

使用数据流模式下载,节省内存占用

with open('xinu.png', 'wb') as f:
    dt.get(rootpath + 'xinu.png', f)

下载成功,返回 Python None 对象; 失败则抛出相应异常。

(4)创建目录
dt.mkdir(rootpath + 'temp')

创建成功,返回 Python None 对象; 失败则抛出相应异常。

(5)删除目录或文件
dt.delete(rootpath + 'xinu.png')
if not ispicbucket:
dt.delete(rootpath + 'ascii.txt')   
dt.delete(rootpath + 'temp')
dt.delete(rootpath)

删除成功,返回 Python None 对象; 失败则抛出相应异常。注意删除目录时,必须保证目录为空。

(6)获取目录文件列表
res = dt.getlist(rootpath)

print "oked\n"
    if res:
        space = 12
        types = ["name", "type", "size", "time","filetype"]
        print '|'.join([t.center(space) for t in types])
        print '-'*(space*len(types)+len(types)-1)
        for item in res:
            print '|'.join([' ' + item[t].ljust(space-1) for t in types])

获取目录文件以及子目录列表。需要获取根目录列表是,使用 res = dt.getlist(rootpath) ,或直接用方法不传递参数。获取失败,则抛出相应的异常。

(7)获取文件信息
res = dt.getinfo(rootpath + 'xinu.png')

获取文件信息时通过Tab键分隔获取相应内容,返回结果为一个数组。

(8)获取空间使用情况
res = dt.usage()

获取成功,始终返回该空间当前使用的总容量,单位 Bytes; 失败则抛出相应异常。

3.3 异常处理

except detuyun.DetuYunServiceException as se:
    print "failed\n"
    print "Except an DetuYunServiceException ..."
    print "HTTP Status Code: " + str(se.status)
    print "Error Message:    " + se.msg + "\n"
    if se.err:
        print se.err
except detuyun.DetuYunClientException as ce:
    print "failed\n"
    print "Except an DetuYunClientException ..."
    print "Error Message: " + ce.msg + "\n"

其中, DetuYunServiceException 主要是得图云存储端返回的错误信息,具体错误代码请参考标准 API 错误代码表; 而 DetuYunClientException 则主要是一些客户端环境的异常,例如客户端网络超时等。

3.4 其他说明

具体请参考 demo/try.py 的代码,建议可在修改以下代码后直接运行该脚本,观察其输出情况,以便对整个 Python SDK 接口有个大致的了解:

BUCKETNAME = 'bucketname'

USERNAME = 'username'

PASSWORD = 'password'

4. Java SDK

Java SDK[下载]

此SDK适用于Java 6及以上版本。基于得图云存储HTTP REST API接口 构建。使用此 SDK 构建您的网络应用程序,能让您以非常便捷地方式将数据安全地存储到得图云存储上。无论您的网络应用是一个网站程序,还是包括从云端(服务端程序)到终端(手持设备应用)的架构的服务或应用,通过得图云存储及其 SDK,都能让您应用程序的终端用户高速上传和下载,同时也让您的服务端更加轻盈。

4.1 应用接入

获取Access Key 和 Secret Key

要接入得图云存储,您需要拥有一对有效的 Access Key 和 Secret Key 用来进行签名认证。可以通过如下步骤获得:

登录得图云开发者自助平台,查看 Access Key 和 Secret Key 。

4.2 使用说明

(1)初始化DetuYun
public DetuYun(String bucketName, String userName, String password) {
    this.bucketName = bucketName;
    this.userName = userName;
    this.password = md5(password);
}

参数bucketName为空间名称,usernameName为Access Key,password为Access Secret。

示例代码如下:

// 运行前先设置好以下三个参数
private static final String BUCKET_NAME = "abcdd";//"空间名称";
private static final String USER_NAME = "faith196";//"Access Key";
private static final String USER_PWD = "fhx442gh1n1qmeuqyvmtf5nt2uk482";//"Access Secret";
   ...
    // 初始化空间
    detuyun = new DetuYun(BUCKET_NAME, USER_NAME, USER_PWD);

超时时间设置 在初始化DetuYun上传时,可以选择设置上传请求超时时间(默认30s):

public void setTimeout(int second) {
    this.timeout = second * 1000;
}

(2) 上传文件
    boolean result3 = detuyun.writeFile(filePath, file, true);
    System.out.println("3.上传 " + filePath + isSuccess(result3));

采用数据流模式上传文件(节省内存),可自动创建父级目录(最多10级)。第三个参数为可选。True 表示自动创建相应目录,默认值为False。

文件空间上传成功后返回True,图片空间上传成功后一数组形式返回图片信息:

            picWidth = conn.getHeaderField(X_DETUYUN_WIDTH);
            picHeight = conn.getHeaderField(X_DETUYUN_HEIGHT);
            picFrames = conn.getHeaderField(X_DETUYUN_FRAMES);
            picType = conn.getHeaderField(X_DETUYUN_FILE_TYPE);

如果上传失败,则会抛出异常。

(3) 下载文件
    boolean result = detuyun.readFile(filePath, file);
    System.out.println(filePath + " 下载" + isSuccess(result) + ",保存到 "
            + file.getAbsolutePath());
    System.out.println();

直接获取文件时,返回文件内容,使用数据流形式获取时,成功返回True。 如果获取文件失败,则抛出异常。

(4)创建目录
    // 方法1:创建一级目录
    String dir1 = DIR_ROOT + FOLDER_NAME;

    boolean result1 = detuyun.mkDir(dir1);
    System.out.println("创建目录:" + dir1 + isSuccess(result1));

    // 方法2:创建多级目录,自动创建父级目录(最多10级)
    String dir2 = DIR_MORE + FOLDER_NAME;

    boolean result2 = detuyun.mkDir(dir2, true);
    System.out.println("自动创建多级目录:" + dir2 + isSuccess(result2));
    System.out.println();

目录路径必须以斜杠 / 结尾,创建成功返回 True,否则抛出异常。

(5)删除目录或者文件
    boolean result = detuyun.deleteFile(filePath);
    System.out.println(filePath + " 删除" + isSuccess(result));
    System.out.println();

删除成功返回True,否则抛出异常。注意删除目录时,必须保证目录为空 ,否则也会抛出异常。

(6)获取目录文件列表
public FolderItem(String data) {
    String[] a = data.split("\t");
        ...
    }

    ...

    List<DetuYun.FolderItem> items = detuyun.readDir(dirPath);

    if (null == items) {
        System.out.println("'" + dirPath + "'目录下没有文件。");

    } else {

        for (int i = 0; i < items.size(); i++) {
            System.out.println(items.get(i));
        }

        System.out.println("'" + dirPath + "'目录总共有 " + items.size()
                + " 个文件。");
    }

    System.out.println();

获取目录文件以及子目录列表。需要获取根目录列表,使用 data.split("\t") 分隔获取相应内容,返回结果为一个数组。目录获取失败则抛出异常。

(7)获取文件信息
System.out.println(filePath + " 的文件信息:" + detuyun.getFileInfo(filePath));
    System.out.println();

    ...

// 判断是否存在文件信息
    if (isEmpty(fileType) && isEmpty(fileSize) && isEmpty(fileDate)) {
        return null;
    }

    Map<String, String> mp = new HashMap<String, String>();
    mp.put("type", fileType);
    mp.put("size", fileSize);
    mp.put("date", fileDate);

    return mp;

(8)获取空间使用状况
    long usage = detuyun.getBucketUsage();
    System.out.println("空间总使用量:" + usage + "kb");
    System.out.println();

返回的结果为空间使用量,单位 kb。

4.3 异常处理

当API请求发生错误时,SDK将抛出异常,具体错误代码请参考 标准API错误代码表

根据返回HTTP CODE的不同,SDK将抛出以下异常:

  • DetuYunAuthorizationException 401,授权错误
  • DetuYunForbiddenException 403,权限错误
  • DetuYunNotFoundException 404,文件或目录不存在
  • DetuYunNotAcceptableException 406, 目录错误
  • DetuYunServiceUnavailable 503,系统错误

未包含在以上异常中的错误,将统一抛出 DetuYunException 异常。

为了真确处理API请求中可能出现的异常,建议将API操作放在try{...}catch(Exception $e){…} 块中

5. Node.js SDK

Node.js SDK[下载]

该Node.js SDK 适用于Node.js 0.4.7及其以上版本,基于得图云存储官方API构建。 若您的服务端是一个基于 Node.js 编写的网络程序,使用此 SDK , 能让您以非常便捷地方式将数据安全地存储到得图云云存储上。 以便让您应用的终端用户进行高速上传和下载,同时也使得您的服务端更加轻盈。

5.1 应用接入

获取Access Key 和 Secret Key

要接入得图云存储,您需要拥有一对有效的 Access Key 和 Secret Key 用来进行签名认证。可以通过如下步骤获得:

  1. 登录得图云开发者自助平台,查看 Access Key 和 Secret Key 。

5.2 使用说明

(1)初始化DetuYun
var DetuYun = function (bucketname, username, password) {
    _bucketname = bucketname;
    _username = username;
    _password = md5(password);
}

参数bucketname为空间名称,username为Access Key,password为Access Secret。

示例代码如下:

var detuyun = new DetuYun("buckname", "username", "password");

(2)上传文件
DetuYun.prototype.writeFile = function (file, data, autoMkdir, callback, opts){
    _autoMkdir = autoMkdir;

    httpAction('PUT', file, data, null, function(err, res){
        if (!err)
            callback(err, res.body);
        else
            callback(err);
    }, opts);
}

参数file为文件路径(包含文件名),data为文件内容,auotoMkdir表示是否自动创建父级目录,callback表示回调函数,opts为可选参数,opts.header可用于指定额外的http header。opts`参数可以设置的值还包括:

  • CONTENT_TYPE
  • CONTENT_MD5
  • X_GMKERL_THUMBNAIL
  • X_GMKERL_TYPE
  • X_GMKERL_VALUE
  • X_GMKERL_QUALITY

参数的具体使用方法,请参考 标准API上传文件

DetuYun.prototype.getWritedFileInfo = function(key){
    if (!_tmpInfo[key]) return null;
    return _tmpInfo[key];
}

文件上传成功后,可以获取上传文件后的信息,仅图片空间有返回数据,参数key为信息字段名,包括 :

x-DetuYun-width
x-DetuYun-height
x-DetuYun-frames
x-DetuYun-file-type

示例代码

//上传文件
var path = './Hydrangeas.jpg';
var file = fs.readFileSync(path);
detuyun.writeFile('/test.jpg', file, false, testCallback);
detuyun.writeFile('/test/test.jpg', '12323231', true, testCallback);

文件空间上传成功后返回True,如果上传失败,则会抛出异常。

(3)下载文件
DetuYun.prototype.readFile = function (file, output_file, callback) {
    httpAction('GET', file, null, output_file, function(err, res){
        if (!err)
            callback(err, res.body);
        else
            callback(err);
    });
}

参数file为文件路径(包含文件名),output_file为输出文件的路径(默认为null,结果返回文件内容,如设置output_file,将返回 truefalse)。`

示例代码如下:

detuyun.readFile('/test3.jpg', './test3.jpg', function(){});

直接获取文件时,返回文件内容,使用数据流形式获取时,成功返回True。 如果获取文件失败,则抛出异常。

(4)创建目录
DetuYun.prototype.mkDir = function (path, autoMkdir, callback) {
    _autoMkdir = autoMkdir;
    httpAction('PUT', path, null, null, function(err, res){
        if (!err)
            callback(err, res.body);
        else
            callback(err);
    }, { header: { folder: true } });
}

目录路径必须以斜杠 / 结尾,创建成功返回 True,否则抛出异常。

示例代码如下:

detuyun.mkDir('/test1', true, testCallback);

(5)删除目录或者文件

删除文件

DetuYun.prototype.deleteFile = function (file, callback){
    httpAction('DELETE', file, null, null, function(err, res){
        if (!err)
            callback(err, res.body);
        else
            callback(err);
    });
}

删除目录

DetuYun.prototype.rmDir = function (path, callback){
    httpAction('DELETE', path, null, null, function(err, res){
        if (!err)
            callback(err, res.body);
        else
            callback(err);
    });
}

删除成功返回True,否则抛出异常。注意删除目录时,必须保证目录为空 ,否则也会抛出异常。

示例代码如下

//删除文件
detuyun.deleteFile('/test.jpg', testCallback);
//删除目录
detuyun.rmDir('/test1', testCallback);

(6)获取目录文件列表
DetuYun.prototype.readDir = function (path, callback){
    callback = typeof callback == 'function' ? callback : function() {};
    httpAction('GET', path, null, null, function(err, data) {
        if (!err) {
            var dirs = data.body.split("\n");
            var result = [];

            for (var i = 0; i < dirs.length; i++) {
                var dir = dirs[i];
                var attrs = dir.split("\t");
                dir = {
                    name: attrs[0],
                    type: attrs[1],
                    size: attrs[2],
                    time: attrs[3],
                    filetype: attrs[4]
                }
                result.push(dir);
            }

            callback(err, result);
        }
        else {
            callback(err);
        }
    });
}

获取目录文件以及子目录列表。需要获取根目录列表是,使用 data.body.split("\n") ,或直接表用方法不传递参数。目录获取失败则抛出异常。

示例代码如下:

//获取目录文件列表
detuyun.readDir('/', testCallback);

(7)获取文件信息
DetuYun.prototype.getFileInfo = function(file, callback){
    httpAction('HEAD', file, null, null, function(err, res){
        if (!err) {
            var fileinfo = res.headers['x-detuyun-file'].split('\t');
            callback(err, {
                'name':fileinfo[0], 
                'type': fileinfo[1],
                'size': fileinfo[2],
                'date': fileinfo[3]
            });
        }
        else {
            callback(err);
        }
    });
}

获取文件信息时通过Tab键分隔获取相应内容,返回结果为一个数组。

示例代码:

//获取文件信息
detuyun.getFileInfo('/test1.jpg', testCallback);

返回的结果为空间使用量,单位 kb。

5.3 异常处理

当API请求发生错误时,SDK将抛出异常,具体错误代码请参考 标准API错误代码表

根据返回HTTP CODE的不同,SDK将抛出以下异常:

  • DetuYunAuthorizationException 401,授权错误
  • DetuYunForbiddenException 403,权限错误
  • DetuYunNotFoundException 404,文件或目录不存在
  • DetuYunNotAcceptableException 406, 目录错误
  • DetuYunServiceUnavailable 503,系统错误

未包含在以上异常中的错误,将统一抛出 DetuYunException 异常。

6. Android SDK

Android SDK[下载]

Android SDK 基于得图云表单API构建。在开发者的 Android App 工程项目中使用此 SDK 能够非常方便地将 Android 系统里边的文件快速直传到得图云存储。

6.1 应用接入

获取Access Key 和 Secret Key

要接入得图云存储,您需要拥有一对有效的 Access Key 和 Secret Key 用来进行签名认证。可以通过如下步骤获得:

  1. 登录得图云开发者自助平台,查看 Access Key 和 Secret Key 。

6.2 使用说明

(1)设置初始参数
private static final String TEST_API_KEY = "fhx442gh1n1qmeuqyvmtf5nt2uk482";
private static final String BUCKET = "abcdd";                   
private static final long EXPIRATION = System.currentTimeMillis()/1000 + 1000 * 5 * 10;     
private static final String SOURCE_FILE = Environment.getExternalStorageDirectory().getAbsolutePath()+ File.separator + "sample.jpg";

参数TEST_API_KEY为测试使用的表单api验证密钥,BUCKET为存储空间名称,EXPIRATION为过期时间,必须大于当前时间,SOURCE_FILE为来源文件。

(2)设置上传参数
String SAVE_KEY = "faith196";//File.separator + "test" + File.separator + System.currentTimeMillis()+".jpg";
HashMap<String, Object> map = new HashMap<String, Object>();
map.put("save_name", "/{year}/{mon}/{random}{.suffix}");
map.put("content_length_range", "0,1024000");
map.put("image_width_range", "100,1024000");
map.put("image_height_range", "100,1024000");
String policy = DetuYunUtils.makePolicy(SAVE_KEY, EXPIRATION, BUCKET,map);
  • SAVE_KEY表示设置服务器上保存文件的目录和文件名,如果服务器上同目录下已经有同名文件会被自动覆盖的。
  • save_name表示文件名生成格式,具体请参阅表单API文档
  • content_length_range表示限制文件大小,为可选参数。
  • image_width_range表示限制图片宽度,为可选参数。
  • image_height_range表示限制图片高度,为可选参数。

(3)获取policy参数
String policy = DetuYunUtils.makePolicy(SAVE_KEY, EXPIRATION, BUCKET,map);

获取base64编码后的policy。

(4)Signature 签名
String signature = DetuYunUtils.signature(policy + "&" + TEST_API_KEY);

根据表单api签名密钥对policy进行签名。通常我们建议这一步在用户自己的服务器上进行,并通过http请求取得签名后的结果。

(5)上传文件
HashMap<String, Object> resultMap = Uploader.upload(policy, signature , BUCKET, SOURCE_FILE);
string = DetuYunUtils.getResultString(resultMap);

将要存储的图片上传到对应的bucket中去。当文件上传成功时,会试图跳转到浏览器访问已经上传的资源。如果失败,会toast提示。

(6)并发特性

此 Android SDK 不是线程安全的,请勿在没有保护的情况下跨线程使用。

6.3 异常处理

通常只有code和message信息。但在上传时候还会传递其他错误信息,供开发者使用,具体请参考表单API错误列表

  • DetuYunException(20, "miss param access_key") 验证密钥未初始化
  • DetuYunException(20, "miss param expiration") 过期时间未初始化
  • DetuYunException(20, "miss param bucket") 空间名称未初始化
  • DetuYunException(21, e.getMessage()) 获取信息错误

未包含在以上异常中的错误,将统一抛出 DetuYunException 异常。

7. IOS SDK

IOS SDK[下载]

得图云IOS SDK 基于得图云表单API构建。在开发者的 IOS App 工程项目中使用此 SDK 能够非常方便地将 Android 系统里边的文件快速直传到得图云存储。

7.1 应用接入

获取Access Key 和 Secret Key

要接入得图云存储,您需要拥有一对有效的 Access Key 和 Secret Key 用来进行签名认证。可以通过如下步骤获得:

  1. 登录得图云开发者自助平台,查看 Access Key 和 Secret Key 。

7.2 使用说明

(1)设置初始参数
define DEFAULT_BUCKET @"abcdd"
define DEFAULT_KEY @"faith196"
define DEFAULT_PASSCODE @"fhx442gh1n1qmeuqyvmtf5nt2uk482"
define DEFAULT_EXPIRES_IN 600

参数DEFAULT_BUCKET为空间名称,DEFAULT_KEY为Access Key,DEFAULT_PASSCODE为Access Secret,即表单API功能的密钥,您可以在得图云后台首页的AccessKey管理页面获取。

(2)初始化DetuYun
DetuYun *uy = [[DetuYun alloc] init];

(3)上传文件

文件上传方式有3种:

第一种 根据 UIImage 上传

UIImage * image = [UIImage imageNamed:@"sample.jpg"];
[uy uploadFile:image saveKey:[self getSaveKey]];

第二种 根据 文件路径 上传

NSString* resourcePath = [[NSBundle mainBundle] resourcePath];
NSString* filePath = [resourcePath stringByAppendingPathComponent:@"fileTest.file"];
[uy uploadFile:filePath saveKey:[self getSaveKey]];

第三种 根据 NSDate 上传

NSData * fileData = [NSData dataWithContentsOfFile:filePath];
[uy uploadFile:fileData saveKey:[self getSaveKey]];

参数说明:

  • image: 传入的图片 (当以此类型传入图片时,都会转成PNG数据,需要其他格式请先转成NSData传入 或者 传入文件路径)
  • NSString: 本地文件路径
  • NSData: 文件数据
  • saveKey:要保存到得图云空间的具体地址,由以下方式生成
    • 方式1 由开发者生成saveKey

      NSDate *d = [NSDate date]; return [NSString stringWithFormat:@"/%d/%d/%.0f.jpg",
      [self getYear:d],[self getMonth:d],[[NSDate date] timeIntervalSince1970]]; * 方式2 由服务器生成saveKey return [NSString stringWithFormat:@"/{year}/{mon}/{filename}{.suffix}"];

(5)回调函数
上传成功回调
 uy.successBlocker = ^(id data){};

回调中的参数:

  • data: 成功后服务器返回的信息
上传失败回调
uy.failBlocker = ^(NSError * error){};

回调中的参数:

  • error :失败后返回的错误信息
上传进度度回调
uy.progressBlocker = ^(CGFloat percent,long long requestDidSendBytes){};

回调中的参数:

  • percent: 上传进度的百分比
  • requestDidSendBytes: 已经发送的数据量

7.3 异常处理

错误代码详见表单API错误列表

8. C#表单SDK

C#表单SDK[下载]

此 SDK 适用于 .net framework 4.0及其以上版本,基于得图云存储HTTP REST API接口 构建。使用此 SDK 构建您的网络应用程序,能让您以非常便捷地方式将数据安全地存储到得图云存储上。无论您的网络应用是一个网站程序,还是包括从云端(服务端程序)到终端(手持设备应用)的架构的服务或应用,通过得图云存储及其 SDK,都能让您应用程序的终端用户高速上传和下载,同时也让您的服务端更加轻盈。

8.1 应用接入

获取Access Key 和 Secret Key

要接入得图云存储,您需要拥有一对有效的 Access Key 和 Secret Key 用来进行签名认证。可以通过如下步骤获得:

  1. 登录得图云开发者自助平台,查看 Access Key 和 Secret Key 。

8.2 使用说明

(1)设置初始参数
string bucket = "abcdd"; 
string form_api_key = "faith196";
string form_api_secret = "fhx442gh1n1qmeuqyvmtf5nt2uk482";

参数bucket为空间名称,form_api_key为Access Key,form_api_key为Access Secret,即表单API功能的密钥,您可以在得图云管理后台首页的AccessKey管理页面获取。

(2)上传文件

表单文件上传到得图云存储时,需要告知该文件需要怎么处理,以及最终的保存路径等。所以表单在上传文件的同时,可以挑选我们提供的可选参数,自由搭配出符合自身业务逻辑的参数集,做成 policy 并传递给得图云存储。 policy 内容可以通过以下三个步骤获得:

  • 自由挑选所需的参数,做成参数集

  • 将 key-value 的参数集转换成 json 格式的字符串

  • 将 json 格式的字符串(无换行)进行 base64 处理

options.Add("bucket",bucket);
options.Add("access_key","faith196");
options.Add("expiration", (DateTime.UtcNow - new DateTime(1970, 1, 1, 0, 0, 0)).TotalSeconds + 600);/// 授权过期时间
options.Add("save_name","/{year}/{mon}/{random}{.suffix}"); 
   ...
string policy = System.Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes(optionsJson));

参数expiration表示授权过期时间,save_name表示文件名生成格式,具体请参阅表单API文档的 Policy详解

(3)Signature 签名

回调中的所有信息均为 UTF_8 编码,签名验证的时候需要注意编码是否一致。

string sign = GetMD5(policy + "&" + form_api_secret);

参数form_api_secret为表单 API 验证密匙,可访问得图云管理后台的AccessKey管理页面获取。客户端在文件上传时,需要使用“表单 API 验证密匙”,计算出一个唯一的签名值,并将该值传递到得图云存储。得图云服务器在接收到请求的第一时间里,在服务器端以同样的计算方式计算出签名值,用来验证当前的请求是否有效。若传递过来的签名值与得图云服务端计算的签名值不匹配,则视为错误请求并返回“签名错误”的消息。

(4)同步回调

如果没有设置 return-url 同步回调参数,那么得图云存储处理完上传操作后,将把结果信息返回输出到 body 中;如果设置了 return-url 同步回调参数,那么得图云存储处理完上传操作后,将会使用 http 302 的方式自动跳转到用户指定的 URL。

options.Add("return_url","http://api.detuyun.com/sdk/php-form-sdk/return.php");

页面跳转型回调地址。URL 中包括:codemessageurltimesign(或 non-sign) 、image-widthimage-heightimage-framesimage-type 参数。

(5)异步回调

如果设置了 notify-url 异步回调参数,那么得图云存储处理完上传操作后,服务端将通过 POST 的方式把上传结果回调到用户所指定的URL,

options.Add("notify_url","http://api.detuyun.com/sdk/php-form-sdk/notify.php");

服务端异步回调地址, 请注意该地址必须公网可以正常访问。回调地址中包括:codemessageurltimesign(或 non-sign) 、image-widthimage-heightimage-framesimage-typ

8.3 异常处理

当API请求发生错误时,SDK将抛出异常,具体错误代码请参考 表单API错误代码表

根据返回HTTP CODE的不同,SDK将抛出以下异常:

  • DetuYunAuthorizationException 401,授权错误
  • DetuYunForbiddenException 403,权限错误
  • DetuYunNotFoundException 404,文件或目录不存在
  • DetuYunNotAcceptableException 406, 目录错误
  • DetuYunServiceUnavailable 503,系统错误

未包含在以上异常中的错误,将统一抛出 DetuYunException 异常。

9. PHP表单SDK

PHP表单SDK[下载]

此 SDK 适用于 PHP 5.1.0 及其以上版本。基于得图云存储HTTP REST API接口 构建。使用此 SDK 构建您的网络应用程序,能让您以非常便捷地方式将数据安全地存储到得图云存储上。无论您的网络应用是一个网站程序,还是包括从云端(服务端程序)到终端(手持设备应用)的架构的服务或应用,通过得图云存储及其 SDK,都能让您应用程序的终端用户高速上传和下载,同时也让您的服务端更加轻盈。

9.1 应用接入

获取Access Key 和 Secret Key

要接入得图云存储,您需要拥有一对有效的 Access Key 和 Secret Key 用来进行签名认证。可以通过如下步骤获得:

登录得图云开发者自助平台,查看 Access Key 和 Secret Key 。

9.2 使用说明

(1)设置初始参数
$bucket = 'abcdd'; 
$form_api_key = "faith196";
$form_api_secret = 'fhx442gh1n1qmeuqyvmtf5nt2uk482';

参数bucket为空间名称,form_api_key为Access Key,form_api_key为Access Secret,即表单API功能的密钥,您可以在得图云管理后台首页的AccessKey管理页面获取。

(2)上传文件

表单文件上传到得图云存储时,需要告知该文件需要怎么处理,以及最终的保存路径等。所以表单在上传文件的同时,可以挑选我们提供的可选参数,自由搭配出符合自身业务逻辑的参数集,做成 policy 并传递给得图云存储。 policy 内容可以通过以下三个步骤获得:

  • 自由挑选所需的参数,做成参数集

  • 将 key-value 的参数集转换成 json 格式的字符串

  • 将 json 格式的字符串(无换行)进行 base64 处理

$options = array();
$options['bucket'] = $bucket; 
$options["access_key"]="faith196";
$options['expiration'] = time()+600; 
$options['save_name'] = '/{year}/{mon}/{random}{.suffix}'; 
   ...
$policy = base64_encode(json_encode($options));

参数expiration表示授权过期时间,save_name表示文件名生成格式,具体请参阅表单API文档的 Policy详解

(3)Signature 签名

回调中的所有信息均为 UTF_8 编码,签名验证的时候需要注意编码是否一致。

$sign = md5($policy.'&'.$form_api_secret);

参数form_api_secret为表单 API 验证密匙,可访问得图云管理后台的AccessKey管理页面获取。客户端在文件上传时,需要使用“表单 API 验证密匙”,计算出一个唯一的签名值,并将该值传递到得图云存储。得图云服务器在接收到请求的第一时间里,在服务器端以同样的计算方式计算出签名值,用来验证当前的请求是否有效。若传递过来的签名值与得图云服务端计算的签名值不匹配,则视为错误请求并返回“签名错误”的消息。

(4) 同步回调

如果没有设置 return-url 同步回调参数,那么得图云存储处理完上传操作后,将把结果信息返回输出到 body 中;如果设置了 return-url 同步回调参数,那么得图云存储处理完上传操作后,将会使用 http 302 的方式自动跳转到用户指定的 URL。

$options['return_url'] = 'http://api.detuyun.com/sdk/php-form-sdk/return.php';

页面跳转型回调地址。URL 中包括:codemessageurltimesign(或 non-sign) 、image-widthimage-heightimage-framesimage-type 参数。

(5) 异步回调

如果设置了 notify-url 异步回调参数,那么得图云存储处理完上传操作后,服务端将通过 POST 的方式把上传结果回调到用户所指定的URL,

$options['notify_url'] = 'http://api.detuyun.com/sdk/php-form-sdk/notify.php';

服务端异步回调地址, 请注意该地址必须公网可以正常访问。回调地址中包括:codemessageurltimesign(或 non-sign) 、image-widthimage-heightimage-framesimage-typ

9.3 异常处理

当API请求发生错误时,SDK将抛出异常,具体错误代码请参考 表单API错误代码表

根据返回HTTP CODE的不同,SDK将抛出以下异常:

  • DetuYunAuthorizationException 401,授权错误
  • DetuYunForbiddenException 403,权限错误
  • DetuYunNotFoundException 404,文件或目录不存在
  • DetuYunNotAcceptableException 406, 目录错误
  • DetuYunServiceUnavailable 503,系统错误

未包含在以上异常中的错误,将统一抛出 DetuYunException 异常。