Image Server 使用帮助

Image Server API 接口

1. HTTP REST API

1.1 API签名认证

签名格式
 Authorization: DetuYun Demo_Access_Key:signature

字段 说明
Authorization http header 键值
DetuYun 固定字符串,与 username 之间以空格间隔
Demo_Access_Key 分配的 Demo_Access_Key
signature 签名内容

签名内容生成方式
md5( URI & DATE & md5(PASSWORD))
字段 说明
& 字符串连接符:前后不要有空格,上面的计算式中的空格是为了阅读方便特意添加
URI 请求路径,必须符合http 协议标准:包含中文名称或特殊字符的文件名(或目录),需进行 urlencode 处理
DATE 请求日期,格式:Wed, 24 Aug 2011 09:13:05 GMT (RFC 1123)。请确保该时间与世界时间一致,否则签名将失败
PASSWORD 空间的操作员密码
请求方法
> // GET 请求方法。 注:GET 和 HEAD 请求没有 Content-Length header

> GET /demobucket/ HTTP/1.1
> Host: s.detuyun.com
> Authorization: DetuYun Demo_Access_Key:97295347384af91dc2b9d7374dd0821d
> Date: Thu, 11 Jul 2013 05:34:12 GMT

> // PUT 请求方法。注:PUT 和 POST 请求需要传递 Content-Length header

> PUT /demobucket/a.txt HTTP/1.1
> Host: s.detuyun.com
> Authorization: DetuYun Demo_Access_Key:97295347384af91dc2b9d7374dd0821d
> Date: Thu, 11 Jul 2013 05:34:12 GMT
> Content-Length: 26
代码示例(PHP)
<?php

        // demobucket为空间名
        $uri = '/demobucket/';

        $process = curl_init('http://s.detuyun.com'.$uri);

        // 取得世界时间。得到的日期格式如:Thu, 11 Jul 2013 05:34:12 GMT
        $date = gmdate('D, d M Y H:i:s \G\M\T');

        $sign = md5("{$uri}&{$date}&".md5("Secret Key"));

        // 设置表头参数:Demo_Access_Key为操作员名称
        curl_setopt($process, CURLOPT_HTTPHEADER, array(
            "Expect:", 
            "Date: ".$date, // header 中传递的时间需要与签名时的时间保持一致
            "Authorization: DetuYun Demo_Access_Key:".$sign
        ));
        curl_setopt($process, CURLOPT_HEADER, 1);
        curl_setopt($process, CURLOPT_TIMEOUT, 60);
        curl_setopt($process, CURLOPT_RETURNTRANSFER, 1);

        var_dump(curl_exec($process));
        var_dump(curl_getinfo($process, CURLINFO_HTTP_CODE));

        curl_close($process);
    ?>
<hr style="margin-top:40px"/>

1.2 标准API接口

上传文件

上传说明
  • 上传文件的同时可设置其他可选参数,比如文件MD5校验以及图片处理参数

  • 图片类空间上传图片成功后,将返回图片的基本信息

  • 图片类空间无法上传非图片类文件

请求方法
> PUT /demobucket/a.txt HTTP/1.1
> Authorization: DetuYun Demo_Access_Key:WEQRASDFEWERWE33A54A
> Host: s.detuyun.com
> Content-Length: 26

...文件内容...
请求参数

"标准请求头"之外,无需其他请求头参数

返回内容

成功时:

> HTTP/1.1 200 OK

// 文件类空间上传文件成功后返回内容为空

// 图片类空间上传图片成功之后返回以下响应头
> x-detuyun-width: 50
> x-detuyun-height: 50
> x-detuyun-frames: 1
> x-detuyun-type: image/jpeg

失败时:

> HTTP/1.1 401
> x-detuyun-error: Not accept, Not accept file

其他响应头请参阅"标准响应头"

详细的得图云错误代码请参阅标准API错误代码表

代码示例(PHP)
<?php
        // 保存文件到 demobucket 空间的根目录下
        $process = curl_init('http://s.detuyun.com/demobucket/a.txt');

        // 上传操作
        curl_setopt($process, CURLOPT_PUT, 1);
        curl_setopt($process, CURLOPT_USERPWD, "Demo_Access_Key:Secret Key");
        curl_setopt($process, CURLOPT_HEADER, 1);
        curl_setopt($process, CURLOPT_TIMEOUT, 60);

        // 本地待上传的文件
        $local_file_path = "/tmp/sample.txt";
        $datas = fopen($local_file_path,'r'); 
        fseek($datas, 0, SEEK_END);
        $file_length = ftell($datas);
        fseek($datas, 0);

        // 设置待上传的内容
        curl_setopt($process, CURLOPT_INFILE, $datas);

        // 设置待上传的长度
        curl_setopt($process, CURLOPT_INFILESIZE, $file_length);

        // 设置自动创建父级目录
        curl_setopt($process, CURLOPT_HTTPHEADER, array("Expect:", "mkdir: true"));
        curl_setopt($process, CURLOPT_RETURNTRANSFER, 1);

        var_dump(curl_exec($process));
        var_dump(curl_getinfo($process, CURLINFO_HTTP_CODE));

        curl_close($process);
        fclose($datas);
?>

下载文件

请求方法
> GET /demobucket/a.txt HTTP/1.1
> Authorization: DetuYun Demo_Access_Key:WEQRASDFEWERWE33A54A
> Host: s.detuyun.com
请求参数

"标准请求头"之外,无需其他请求头参数

返回内容

成功时:

> HTTP/1.1 200 OK

demodata // 文件内容

失败时:

> HTTP/1.1 404 
> x-detuyun-error: Not accept,Not found

其他响应头请参阅"标准响应头"

详细的得图云错误代码请参阅标准API错误代码表

代码示例(PHP)
 <?php
        // 下载 demobucket 空间根目录下的 a.txt 文件
        $process = curl_init('http://s.detuyun.com/demobucket/a.txt');

        curl_setopt($process, CURLOPT_USERPWD, "Demo_Access_Key:Secret Key");
        curl_setopt($process, CURLOPT_HEADER, 1);
        curl_setopt($process, CURLOPT_TIMEOUT, 60);
        curl_setopt($process, CURLOPT_RETURNTRANSFER, 1);

        var_dump(curl_exec($process));
        var_dump(curl_getinfo($process, CURLINFO_HTTP_CODE));

        curl_close($process);
?>

获取文件信息

请求方法
> HEAD /demobucket/a.txt HTTP/1.1
> Authorization: DetuYun Demo_Access_Key:WEQRASDFEWERWE33A54A
> Host: s.detuyun.com
请求参数

"标准请求头"之外,无需其他请求头参数

返回内容

成功时:

> HTTP/1.1 200 OK
> x-detuyun-file: name  type    size    date        // 文件名 文件返回"file",文件夹返回"folder"     文件大小 文件创建时间

失败时:

> HTTP/1.1 404 
> x-detuyun-error: Not accept,Not found

其他响应头请参阅"标准响应头"

详细的得图云错误代码请参阅标准API错误代码表

代码示例(PHP)
<?php
        // 获取 demobucket 空间根目录下的 a.txt 文件的基本信息
        $process = curl_init('http://s.detuyun.com/demobucket/a.txt');

        curl_setopt($process, CURLOPT_CUSTOMREQUEST, 'HEAD');
        curl_setopt($process, CURLOPT_USERPWD, "Demo_Access_Key:Secret Key");
        curl_setopt($process, CURLOPT_HEADER, 1);
        curl_setopt($process, CURLOPT_TIMEOUT, 60);
        curl_setopt($process, CURLOPT_RETURNTRANSFER, 1);

        // 只获取 header
        curl_setopt($process, CURLOPT_HEADER, 1); 
        curl_setopt($process, CURLOPT_NOBODY, true);

        var_dump(curl_exec($process));
        var_dump(curl_getinfo($process, CURLINFO_HTTP_CODE));

        curl_close($process);
?>

删除文件

请求方法
> DELETE /demobucket/a.txt HTTP/1.1
> Authorization: DetuYun Demo_Access_Key:WEQRASDFEWERWE33A54A
> Host: s.detuyun.com
请求参数

"标准请求头"之外,无需其他请求头参数

返回内容

成功时:

> HTTP/1.1 200 OK

失败时:

> HTTP/1.1 404 
> x-detuyun-error: Not accept,Not found

其他响应头请参阅"标准响应头"

详细的得图云错误代码请参阅标准API错误代码表

代码示例(PHP)
<?php
        // 删除 demobucket 空间根目录下的 a.txt 文件
        $process = curl_init('http://s.detuyun.com/demobucket/a.txt');

        // 删除请求
        curl_setopt($process, CURLOPT_CUSTOMREQUEST, 'DELETE');
        curl_setopt($process, CURLOPT_USERPWD, "Demo_Access_Key:Secret Key");
        curl_setopt($process, CURLOPT_HEADER, 1);
        curl_setopt($process, CURLOPT_TIMEOUT, 60);
        curl_setopt($process, CURLOPT_RETURNTRANSFER, 1);

        var_dump(curl_exec($process));
        var_dump(curl_getinfo($process, CURLINFO_HTTP_CODE));

        curl_close($process);
?>

创建目录

请求方法
> POST /demobucket/dir/ HTTP/1.1
>Authorization: DetuYun Demo_Access_Key:97295347384af91dc2b9d7374dd0821d
> Host: s.detuyun.com
> Content-Length:0
> Folder: true
请求参数

"标准请求头"之外,还有以下请求头参数

请求头 是否必须 参数值 说明
folder true 标识当前请求为“创建目录”
mkdir true / false 是否要自动创建不存在的父级目录。最多允许创建 10 级目录

返回内容

成功时:

> HTTP/1.1 200 OK

失败时:

> HTTP/1.1 404 
> x-detuyun-error: Not accept,Not found

其他响应头请参阅"标准响应头"

详细的得图云错误代码请参阅标准API错误代码表

代码示例(PHP)
 <?php
       // 在 demobucket 空间根目录下创建一个 dir 的目录
       $process = curl_init('http://s.detuyun.com/demobucket/dir/');

       curl_setopt($process, CURLOPT_POST, 1);
       curl_setopt($process, CURLOPT_POSTFIELDS, '');

       // 设置需要创建目录
       curl_setopt($process, CURLOPT_HTTPHEADER, array( 'Expect:', 'folder: true'));

       curl_setopt($process, CURLOPT_USERPWD, "Demo_Access_Key:Secret Key");
       curl_setopt($process, CURLOPT_HEADER, 1);
       curl_setopt($process, CURLOPT_TIMEOUT, 60);
       curl_setopt($process, CURLOPT_RETURNTRANSFER, 1);

       var_dump(curl_exec($process));
       var_dump(curl_getinfo($process, CURLINFO_HTTP_CODE));

       curl_close($process);
?>

删除目录

请求方法
> DELETE /demobucket/dir/ HTTP/1.1
>Authorization: DetuYun Demo_Access_Key:97295347384af91dc2b9d7374dd0821d
> Host: s.detuyun.com
请求参数

"标准请求头"之外,无需其他请求头参数

返回内容

成功时:

> HTTP/1.1 200 OK

失败时:

> HTTP/1.1 404 
> x-detuyun-error: Not accept,Not found

其他响应头请参阅"标准响应头"

详细的得图云错误代码请参阅标准API错误代码表

代码示例(PHP)
<?php
     // 删除 demobucket 空间根目录下的 dir 目录
     $process = curl_init('http://s.detuyun.com/demobucket/dir/');

     // 删除目录请求
     curl_setopt($process, CURLOPT_CUSTOMREQUEST, 'DELETE');
     curl_setopt($process, CURLOPT_USERPWD, "Demo_Access_Key:Secret Key");
     curl_setopt($process, CURLOPT_HEADER, 1);
     curl_setopt($process, CURLOPT_TIMEOUT, 60);
     curl_setopt($process, CURLOPT_RETURNTRANSFER, 1);

     var_dump(curl_exec($process));
     var_dump(curl_getinfo($process, CURLINFO_HTTP_CODE));

     curl_close($process);
?>

获取目录文件列表

请求方法
> GET /demobucket/ HTTP/1.1
>Authorization: DetuYun Demo_Access_Key:97295347384af91dc2b9d7374dd0821d
> Host: s.detuyun.com
请求参数

"标准请求头"之外,无需其他请求头参数

返回内容

成功时:

> HTTP/1.1 200 OK

// 文件之间以"\n"分隔,属性之间以"\t"分隔
demo.jpg\tN\t11383\t1306130450\timage.jpg\ndemo\tF\t14738423\t1306130450\t  // body 内容

解析后(目录大小表示当前目录下的文件大小,不含子目录):

文件/目录名 类型 大小 最后修改时间 定义文件类型
demo.jpg N (文件) 11383 1306130450 image/jpeg
demo F (目录) 14738423 1306130450 |
失败时:

> HTTP/1.1 404 
> x-detuyun-error: Not accept,Not found

其他响应头请参阅"标准响应头"

详细的得图云错误代码请参阅 标准API错误代码表

代码示例(PHP)
<?php
        // 获取 demobucket 空间根目录下的文件列表
        $process = curl_init('http://s.detuyun.com/demobucket/');

        curl_setopt($process, CURLOPT_USERPWD, "Demo_Access_Key:Secret Key");
        curl_setopt($process, CURLOPT_HEADER, 1);
        curl_setopt($process, CURLOPT_TIMEOUT, 60);
        curl_setopt($process, CURLOPT_RETURNTRANSFER, 1);

        var_dump(curl_exec($process));
        var_dump(curl_getinfo($process, CURLINFO_HTTP_CODE));

        curl_close($process);
?>

获取空间使用情况

请求方法
> GET /demobucket/?usage HTTP/1.1
>Authorization: DetuYun Demo_Access_Key:97295347384af91dc2b9d7374dd0821d
> Host: s.detuyun.com
请求参数

"标准请求头"之外,无需其他请求头参数

返回内容

成功时:

> HTTP/1.1 200 OK

> x-detuyun-used: 1639920 // 空间的使用量,单位为 kb

失败时:

> HTTP/1.1 404 
> x-detuyun-error: Not accept,Not found

其他响应头请参阅"标准响应头"

详细的得图云错误代码请参阅标准API错误代码表

代码示例(PHP)
<?php
        // 获取 demobucket 空间的使用情况
        $process = curl_init('http://s.detuyun.com/demobucket/?usage');

        curl_setopt($process, CURLOPT_USERPWD, "Demo_Access_Key:Secret Key");
        curl_setopt($process, CURLOPT_HEADER, 1);
        curl_setopt($process, CURLOPT_TIMEOUT, 60);
        curl_setopt($process, CURLOPT_RETURNTRANSFER, 1);

        var_dump(curl_exec($process));
        var_dump(curl_getinfo($process, CURLINFO_HTTP_CODE));

        curl_close($process);
?>

1.3图片处理接口

上传图片时,允许使用以下图片处理接口直接对上传的图片进行处理。需要注意三点:

  1. 图片处理接口只是在上传文件接口的基础上,添加了图片处理参数而已;
  2. 上传图片并传递图片处理参数时,最终将只保存处理后的图片,原图不保存

图片缩略
请求方法
> PUT /demobucket/pic.jpg HTTP/1.1
>Authorization: DetuYun Demo_Access_Key:97295347384af91dc2b9d7374dd0821d
> Host: s.detuyun.com
> Content-Length:21001
> x-gmkerl-type:fix_width
> x-gmkerl-value:200
> x-gmkerl-unsharp:true

  ...图片文件内容...
请求参数

其他上传参数请参阅"标准请求头"上传文件接口,以下只对图片缩略相关的参数进行说明

请求头 参数值 说明
x-gmkerl-type

1. fix_width: 限定宽度,高度自适应

2. fix_height: 限定高度,宽度自适应

3. fix_width_or_height: 限定宽度和高度,宽高不足时不缩放

4. fix_both: 固定宽度和高度,宽高不足时强行缩放

缩略类型

必须搭配 x-gmkerl-value 使用

x-gmkerl-value

fix_width_or_height/fix_both:widthxheight(如 200x150)

其他缩略类型:数字(如 150)

缩略类型对应的参数值,单位为像素

必须搭配 x-gmkerl-type 使用

x-gmkerl-quality 1~100 图片压缩质量,默认 95
返回内容

成功时:

> HTTP/1.1 200 OK

// 文件类空间上传文件成功后返回内容为空

// 图片类空间上传图片成功之后返回以下响应头
> x-detuyun-width: 250       // 图片宽度
> x-detuyun-height: 190      // 图片高度
> x-detuyun-frames: 1        // 图片帧数
> x-detuyun-file-type: image/jpeg  // 图片类型

失败时:

> HTTP/1.1 401
> x-detuyun-error: Not accept,Not found

其他响应头请参阅"标准响应头"

详细的得图云错误代码请参阅标准API错误代码表

代码示例(PHP)

<?php // 保存图片到 demobucket 空间的根目录下,且保存名称为 pic.jpg $process = curl_init('http://s.detuyun.com/demobucket/pic.jpg');

        // 上传操作
        curl_setopt($process, CURLOPT_PUT, 1);
        curl_setopt($process, CURLOPT_USERPWD, "Demo_Access_Key:Secret Key");
        curl_setopt($process, CURLOPT_HEADER, 1);
        curl_setopt($process, CURLOPT_TIMEOUT, 60);

        // 本地待上传的图片文件
        $local_file_path = "/tmp/sample.jpg";
        $datas = fopen($local_file_path,'r'); 
        fseek($datas, 0, SEEK_END);
        $file_length = ftell($datas);
        fseek($datas, 0);

        // 设置待上传图片的内容
        curl_setopt($process, CURLOPT_INFILE, $datas);

        // 设置待上传图片的长度
        curl_setopt($process, CURLOPT_INFILESIZE, $file_length);

        // 设置缩略参数:限定上传图片最大宽度为 250px,高度自适应,并锐化处理
        curl_setopt($process, CURLOPT_HTTPHEADER, array(
                        'x-gmkerl-type: fix_width',
                        'x-gmkerl-value: 250',
                        'x-gmkerl-unsharp: true',
                ));

        var_dump(curl_exec($process));
        var_dump(curl_getinfo($process, CURLINFO_HTTP_CODE));

        curl_close($process);
        fclose($datas);
?>
示例效果

原图:670x500

生成的缩略图:250x190

1.4 标准请求头

"得图云签名认证" 方式发起任何 HTTP REST API 请求,都必须包含以下公共请求头。

请求头 说明
Authorization 授权:用于验证请求合法性的认证信息,比如 `Authorization: DetuYun UserName:Signature`。 详细规范请参阅 RFC 2616
Host

得图云 API 的接入地址,现提供:

s.detuyun.com

Date 标准的格林尼治标准时间,且必须为`GMT`格式。 比如 `Date: Wed, 24 Aug 2011 07:33:47 GMT`
Content-Length 请求内容长度,但不包括Headers部分。 若发起的是 PUT、POST 等上传请求时,则必须设置该参数。详细规范请参阅 RFC 2616

1.5 标准响应头

发起任何 HTTP REST API 请求后,返回的 Response 都包含如下公共响应头。

响应头 说明
Connection 标明客户端和服务器端之间的链接状态。有效值包括 keep-alive / close
Content-Type 响应返回内容的类型。详细规范请参阅 RFC 2616

1.6 标准API错误代码表

HTTP状态码 返回代码 含义
200 OK 操作成功
400 Bad Request 错误请求(如 URL 缺少空间名)
400 Not accept,The number of Bucket is too large 空间数量过大
400 Not accept, Bucket has already existed 空间已存在
400 Not accept, Bucket does not exist 空间不存在
401 Sign error 签名错误
401 Need Date Header 发起的请求缺少 Date 头信息
401 Not accept,Need Authorization header 发起的请求缺少Authorization头信息
401 Not accept,Authorization format error 授权信息格式错误
401 Not accept,Secret key does not exist 密钥不存在
401 Not accept,Account does not exist 账号不存在
401 Not accept,Account is closed 账号已关闭
401 Not accept,Signature error 签名错误
403 Not accept file 不可接受的类型。
403 Not accept, Bucket is not empty 空间不为空
403 Not accept,Document folder not exists or Document folder is not empty 文件夹不存在或文件夹不为空
403 Not accept,File does not exist 文件不存在
404 Not Found 获取文件或目录不存在;上传文件或目录时上级目录不存在
503 System Error 系统错误
503 System Error ... Please retry 系统错误...请重试

2. 表单API接口

2.1 表单API接口简介

表单 API 功能允许用户直接上传文件到得图云存储,而不需要通过客户服务器进行中转,从而为客户网站提供了便捷的解决方案,极大的降低了服务器成本。

普通表单流程如下:

得图云存储表单流程如下:

对比两种流程方式,得图云存储表单功能具有以下几点优势:

(1)避免了客户服务器的文件中转,减少了不必要的流量、带宽和客户服务器开销

(2)得图云存储自动选择最近最快的节点接收客户端上传的文件,文件上传速度更快

(3)客户服务端无需开发多余的业务代码,减少开发和测试成本,提高开发效率

该功能支持多客户端浏览器、客户端软件、手机 APP 等。

2.2 Policy 内容详解

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

policy 内容可以通过以下三个步骤获得:

(1)自由挑选所需的参数,做成参数集

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

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

如:

$options = array();
$options['bucket'] = $bucket; /// 空间名
$options["access_key"]="faith196";
$options['expiration'] = time()+600; /// 授权过期时间
$options['save_name'] = '/{year}/{mon}/{random}{.suffix}'; /// 文件名生成格式,请参阅 API 文档
    ...

$policy = base64_encode(json_encode($options));

注:policy 必须是 UTF-8 编码格式,且不包含换行符,否则可能无法通过签名验证。

可选参数

参数说明可选性备注
bucket空间名必须用户在得图云存储上创建的空间名,文件将保存在该空间下
access_keyaccess key必须用户在得图云存储AccessKey工具中产生
expiration请求的过期时间必须(UNIX TIME)当前上传请求授权的过期时间,单位为“秒”
save_name最终的保存路径必须如: /dir/filename,可以使用占位符,具体请参阅注1
content_length_range文件大小限制可选格式:最小值,最大值,如 102400,1024000 单位:Bytes 含义:仅允许上传 100Kb~1Mb 的文件
image_height_range图片高度限制可选格式:最小值,最大值,如 0,1024 单位:像素 含义:仅允许上传高度在 0~1024px 范围的图片文件 注意:非图片文件使用该参数时,将直接返回“不是图片”的错误
image_width_range图片宽度限制可选格式:最小值,最大值,如 0,1024 单位:像素 含义:仅允许上传宽度在 0~1024px 范围的图片文件 注意:非图片文件使用该参数时,将直接返回“不是图片”的错误
notify_url异步回调 url可选表单上传完成后,云存储服务端主动把上传结果 POST 到该 URL 需要确保公网可以正常访问该 URL,具体请参阅“回调规则”
return_url同步跳转 url可选表单上传完成后,使用 http 302 的方式跳转到该 URL,具体请参阅“回调规则”
content_md5文件校验码可选根据上传文件的内容进行 md5 校验后得到的数值 如 202cb962ac59075b964b07152d234b70 如果得图云服务器对上传文件计算的 md5 值与该值不一致, 则直接返回"Content-md5 error"错误

2.3 Signature 签名

为了确保文件上传的有效性和安全性,避免其他用户的恶意攻击,得图云存储为每个空间分配了一个全局唯一的“表单 API 验证密匙”(form_api_secret)。

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

签名方式

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

参数说明

  • policy:策略内容,具体请参阅"Policy 内容详解"z
  • &:参数间的拼接符,纯字符串内容
  • form_api_secret:表单 API 验证密匙,可访问得图云管理后台的AccessKey管理页面获取

2.4 回调规则

1.如果没有设置 return-url 同步回调参数,那么得图云存储处理完上传操作后,将把结果信息返回输出到 body 中。

2.如果设置了 return-url 同步回调参数,那么得图云存储处理完上传操作后,将会使用 http 302 的方式自动跳转到用户指定的 URL。

如:

http://localhost/form-test/return.php?code=200&x-detuyun-width=1024&x-detuyun-height=768&x-detuyun-size=826&x-detuyun_type=image%2Fjpeg&x-detuyun-frames=1&x-detuyun-filepath=abcdd%2F2013%2F11%2Ftywymjtqddbz9cdc.jpg&msg=OK&url=http%3A%2F%2Fabcdd.img.detuyun.cn%2F2013%2F11%2Ftywymjtqddbz9cdc.jpg&time=1383619265&sign=aa11eab4c3b45c201061a1334a427db4

URL 中包括:codemessageurltimesign(或 non-sign) 、image-widthimage-heightimage-framesimage-type 参数。

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

如:

POST http://localhost/form-test/notify.php
code=200&x-detuyun-width=1024&x-detuyun-height=768&x-detuyun-size=826&x-detuyun_type=image%2Fjpeg&x-detuyun-frames=1&x-detuyun-filepath=abcdd%2F2013%2F11%2Ftywymjtqddbz9cdc.jpg&msg=OK&url=http%3A%2F%2Fabcdd.img.detuyun.cn%2F2013%2F11%2Ftywymjtqddbz9cdc.jpg&time=1383619265&sign=aa11eab4c3b45c201061a1334a427db4

回调地址中包括:codemessageurltimesign(或 non-sign) 、image-widthimage-heightimage-framesimage-typ

2.5 代码示例(PHP)

<?php
/// (回调中的所有信息均为 UTF_8 编码,签名验证的时候需要注意编码是否一致)
$bucket = 'abcdd'; /// 空间名
$form_api_key = "faith196";///
$form_api_secret = 'fhx442gh1n1qmeuqyvmtf5nt2uk482'; /// 表单 API 功能的密匙(请访问得图云管理后台的空间管理页面获取)

$options = array();
$options['bucket'] = $bucket; /// 空间名
$options["access_key"]="faith196";
$options['expiration'] = time()+600; /// 授权过期时间
$options['save_name'] = '/{year}/{mon}/{random}{.suffix}'; /// 文件名生成格式,请参阅 API 文档
$options['content_length_range'] = '0,1024000'; /// 限制文件大小,可选
$options['image_width_range'] = '100,1024000'; /// 限制图片宽度,可选
$options['image_height_range'] = '100,1024000'; /// 限制图片高度,可选
$options['return_url'] = 'http://api.detuyun.com/sdk/php-form-sdk/return.php'; /// 页面跳转型回调地址
$options['notify_url'] = 'http://api.detuyun.com/sdk/php-form-sdk/notify.php'; /// 服务端异步回调地址, 请注意该地址必须公网可以正常访问

$policy = base64_encode(json_encode($options));
$sign = md5($policy.'&'.$form_api_secret); /// 表单 API 功能的密匙(请访问得图云管理后台的空间管理页面获取)

?>
<form action="http://api.detuyun.com/" method="post" enctype="Multipart/form-data">
    <input type="hidden" name="postdata" value="<?php echo $policy?>">
    <input type="hidden" name="signature" value="<?php echo $sign?>">
    <input type="file" name="file">
    <input type="submit">
</form>

请求

Request URL:http://api.detuyun.com/
Request Method:POST
Status Code:200 OK
Request Headersview source
Accept:text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Charset:GBK,utf-8;q=0.7,*;q=0.3
Accept-Encoding:gzip,deflate,sdch
Accept-Language:zh-CN,zh;q=0.8
Cache-Control:max-age=0
Connection:keep-alive
Content-Length:880196
Content-Type:multipart/form-data; boundary=----WebKitFormBoundarytslZD62le3BZYuUN
Host:api.detuyun.com
Origin:http://api.detuyun.com
Referer:http://api.detuyun.com/sdk/php-form-sdk/index.php
User-Agent:Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.4 (KHTML, like Gecko) Chrome/22.0.1229.92 Safari/537.4
Request Payload
------WebKitFormBoundarytslZD62le3BZYuUN
Content-Disposition: form-data; name="postdata"

eyJidWNrZXQiOiJhYmNkZCIsImFjY2Vzc19rZXkiOiJmYWl0aDE5NiIsImV4cGlyYXRpb24iOjEzODM2MTkzNTgsInNhdmVfbmFtZSI6Ilwve3llYXJ9XC97bW9ufVwve3JhbmRvbX17LnN1ZmZpeH0iLCJjb250ZW50X2xlbmd0aF9yYW5nZSI6IjAsMTAyNDAwMCIsImltYWdlX3dpZHRoX3JhbmdlIjoiMTAwLDEwMjQwMDAiLCJpbWFnZV9oZWlnaHRfcmFuZ2UiOiIxMDAsMTAyNDAwMCIsIm5vdGlmeV91cmwiOiJodHRwOlwvXC9hcGkuZGV0dXl1bi5jb21cL3Nka1wvcGhwLWZvcm0tc2RrXC9ub3RpZnkucGhwIn0=
------WebKitFormBoundarytslZD62le3BZYuUN
Content-Disposition: form-data; name="signature"

9b5266fd313da4520b4f19ce536aa678
------WebKitFormBoundarytslZD62le3BZYuUN
Content-Disposition: form-data; name="file"; filename="Chrysanthemum.jpg"
Content-Type: image/jpeg


------WebKitFormBoundarytslZD62le3BZYuUN--
Response Headersview source
Connection:Keep-Alive
Content-Length:310
Content-Type:text/html
Date:Tue, 05 Nov 2013 02:32:41 GMT
Keep-Alive:timeout=5, max=98
Server:Apache/2.2.22 (Win32) PHP/5.4.3
X-Powered-By:PHP/5.4.3

响应

code=200&x-detuyun-width=1024&x-detuyun-height=768&x-detuyun-size=826&x-detuyun_type=image%2Fjpeg&x-detuyun-frames=1&x-detuyun-filepath=abcdd%2F2013%2F11%2Ftywymjtqddbz9cdc.jpg&msg=OK&url=http%3A%2F%2Fabcdd.img.detuyun.cn%2F2013%2F11%2Ftywymjtqddbz9cdc.jpg&time=1383619265&sign=aa11eab4c3b45c201061a1334a427db4

示例效果

原图:670x500

生成的缩略图:250x190

2.6 表单API错误代码表

HTTP 状态码返回代码含义
200OK文件上传成功
400Not accept, No file data没有文件数据
400Not accept, Access_key is nullAccess_key为空
400Not accept, Authorize has expired授权已到期
400Not accept, Expiration is null授权期限为空
400Not accept, Save_name is null保存路径为空
400Not accept, Bucket is null空间名参数为空
400Form parameter is invalid请求参数不合法
400Not accept, Miss signature缺少 signature 参数
400Not accept, Miss postdata缺少 postdata 参数
403Not accept, File size too small文件过小
403Not accept, File size is too large文件过大
403Not accept, Unrecognized file type文件类型不识别
403Not accept, Not accept, Bucket does not exist空间不存在
403Not accept,Account is closed账号已关闭
403Not accept,Account does not exist账号不存在
403Not accept,Signature is error签名错误,可能是表单签名密匙不正确
403Not accept,Secret key does not exist密钥不存在
403Not accept, Image width is too small图片宽度太小
403Not accept, Image width is too large图片宽度太大
403Not accept, Image height is too small图片高度太小
403Not accept, Image height is too large图片高度太大
503System Error ... Please retry系统错误,请重试