REST API

基于 RESTful 架构的 API,您可以使用任何编程语言发送 HTTP/HTTPS 请求与云存储通信。特别地,文中请求参数均通过 HTTP/HTTPS 请求头以 Key: Value 的形式传递。


请求方法

curl -X GET \
    http://v0.api.upyun.com/<bucket>/<path> \
    -H "Authorization: UPYUN <Operator>:<Signature>" \
    -H "Date: <Wed, 29 Oct 2014 11:26:58 GMT>"\
    -H "Content-MD5: <Content-MD5>"\
    # 其他可选参数...

基本域名

认证鉴权

详见签名认证


上传文件

把文件上传至又拍云存储。在上传图片文件时,可以设置预处理参数,图片会处理后再保存。

PUT /<bucket>/path/to/file

上传参数

参数 必选 类型 说明
Date String 请求日期时间,GMT 格式字符串 (RFC 1123),如 Wed, 29 Oct 2014 02:26:58 GMT
Content-Length String 请求内容长度
Content-MD5 String 上传文件的 MD5 值,如果请求中文件太大计算 MD5 不方便,可以为空
Content-Type String 文件类型,默认使用文件扩展名作为文件类型
Content-Secret String 文件密钥,用于保护文件,防止文件被直接访问,见 Content-Secret 参数说明
x-upyun-meta-x String 文件元信息,见 Metadata
x-upyun-meta-ttl Integer 文件元信息, 指定文件的生存时间,单位天,最大支持180天,见 Metadata
x-gmkerl-thumb String 图片预处理参数,见上传预处理(同步)

响应信息

> HTTP/1.1 200 OK
> x-upyun-width: 50
> x-upyun-height: 50
> x-upyun-file-type: JPEG
> x-upyun-frames: 1

Content-Secret 参数说明


断点续传

在上传大文件或移动端上传文件时,因为网络质量、传输时间过长等原因造成上传失败,可以使用断点续传。特别地,断点续传上传的图片不支持预处理。特别地,断点续传上传的文件不能使用其他上传方式覆盖,如果需要覆盖,须先删除文件。

名称概念


初始化断点续传

PUT /<bucket>/path/to/file

请求参数

参数 必选 类型 说明
Content-Length String 请求内容长度
x-upyun-multi-stage String 值为 initiate, 表示初始化上传任务
x-upyun-multi-length String 待上传文件大小,整型,单位 Byte
x-upyun-multi-type String 待上传文件的 MIME 类型,默认 application/octet-stream,建议自行设置
x-upyun-meta-x String 用于额外指定文件的元信息,详见 Metadata
x-upyun-meta-ttl Integer 文件元信息, 指定文件的生存时间,单位天,最大支持180天,见 Metadata

响应信息

初始化断点续传成功返回 204 状态码, 包括以下响应参数:

参数 类型 说明
x-upyun-multi-uuid String 本次上传任务的标识
x-upyun-next-part-id String 下一个分块序号。因为是初始化阶段,所以值为 0

上传失败时返回相应的出错信息,具体请参阅「API 错误码表」。


续传数据

PUT /<bucket>/path/to/file

请求参数

参数 必选 类型 说明
Content-Length String 请求内容长度
x-upyun-multi-stage String 值为 upload, 表示开始上传文件数据
x-upyun-multi-uuid String 本次上传任务的标识,是初始化断点续传任务时响应信息中的 x-upyun-multi-uuid
x-upyun-part-id String 指定此次分片的唯一 ID,应严格等于上一次请求返回的 x-upyun-next-part-id
Content-MD5 String 所上传分块的 MD5 值,等效于签名认证中的 Content-MD5

响应信息

断点续传此分块成功返回 204 状态码, 包括以下响应参数:

参数 类型 说明
x-upyun-multi-uuid String 本次上传任务的标识
x-upyun-next-part-id String 下一个分块序号。若全部分块都已经传完,则该响应头值为 -1

上传失败时返回相应的出错信息,具体请参阅「API 错误码表」。


结束断点续传

PUT /<bucket>/path/to/file

请求参数

参数 必选 类型 说明
Content-Length String 请求内容长度
x-upyun-multi-stage String 值为 complete, 表示完成断点续传任务
x-upyun-multi-uuid String 本次上传任务的标识,是初始化断点续传任务时响应信息中的 x-upyun-multi-uuid
Content-MD5 String 请求的 MD5 值,等效于签名认证中的 Content-MD5
x-upyun-multi-md5 String 整个文件的 MD5 值,用于服务端校验

响应信息

结束断点续传成功,如果返回 204 状态码,表示文件覆盖同名文件;如果返回 201 状态码,表示文件是新文件。

响应信息还包括以下响应参数:

参数 类型 说明
x-upyun-multi-uuid String 本次上传任务的标识
x-upyun-multi-type String 本次上传文件的 MIME 类型
x-upyun-multi-length String 本次上传文件大小,整型,单位 Byte

上传失败时返回相应的出错信息,具体请参阅「API 错误码表」。


下载文件

GET /<bucket>/path/to/file

响应信息


删除文件

DELETE /<bucket>/path/to/file

请求参数

参数 必选 说明
x-upyun-async true 表示进行异步删除,不设置表示同步删除(默认)

响应信息


创建目录

POST /<bucket>/path/to/folder

请求参数

参数 必选 说明
folder 值为 true

响应信息


删除目录

DELETE /<bucket>/path/to/folder

响应信息


获取文件信息

HEAD /<bucket>/path/to/file

响应信息


获取目录文件列表

GET /<bucket>/path/to/folder

分页参数

如果目录中文件数量过多,为了更友好的获取文件信息,可以分页获取:

参数 必选 类型 说明
x-list-iter string 分页开始位置,通过x-upyun-list-iter 响应头返回,所以第一次请求不需要填写
x-list-limit string 获取的文件数量,默认 100,最大 10000
x-list-order string ascdesc,按时间升序或降序排列。默认 asc

响应信息

例如:

> HTTP/1.1 200 OK
> x-upyun-list-iter: c2Rmc2Rsamdvc2pnb3dlam9pd2Vmd2Z3Zg==
foo.jpg\tN\t4237\t1415096225\nbar\tF\t423404\t1415096260

获取服务使用量

GET /<bucket>/?usage

响应信息


Metadata

下载文件时,在响应头里返回文件的所有元数据。

添加 Metadata

上传文件时,如果在请求头里带上以 x-upyun-meta- 开头的参数,那么该参数会作为文件的元数据存储到云存储。例如:

curl -d 'abc' \
    http://v0.api.upyun.com/<bucket>/abc.txt \
    -H "Authorization: UPYUN <Operator>:<Signature>" \
    -H "Date: <Wed, 30 Oct 2016 11:26:58 GMT>"\
    -H "x-upyun-meta-foo: Bar"\
    -H "x-upyun-meta-a: 2"

文件 abc.txt 会增加 x-upyun-meta-foo: barx-upyun-meta-a: 2 这两个元信息。


修改 Metadata

PATCH /<bucket>/path/to/file?metadata=<option>

option 的取值如下:

option 说明
merge(默认 合并文件元信息,如果是相同的元信息,将被新上传的值替换
replace 替换文件元信息为新上传的文件元信息
delete 删除文件元信息

响应信息

举例

例 1:合并元信息,metadata=merge

curl -d 'abc' http://v0.api.upyun.com/<bucket>/abc.txt \
    -H "Authorization: Basic b3BlcmF0b3I6cGFzc3dvcmQ=" \
    -H "x-upyun-meta-a: 1"

curl -XPATCH http://v0.api.upyun.com/<bucket>/abc.txt?metadata=merge \
    -H "Authorization: Basic b3BlcmF0b3I6cGFzc3dvcmQ=" \
    -H "x-upyun-meta-a: 2" \
    -H "x-upyun-meta-b: 3"

文件 abc.txt 的元信息是:

x-upyun-meta-a: 2
x-upyun-meta-b: 3

例 2:替换元信息,metadata=replace

curl -d 'abc' http://v0.api.upyun.com/<bucket>/abc.txt \
    -H "Authorization: Basic b3BlcmF0b3I6cGFzc3dvcmQ=" \
    -H "x-upyun-meta-a: 1" \
    -H "x-upyun-meta-b: 2"

curl -XPATCH http://v0.api.upyun.com/<bucket>/abc.txt?metadata=replace \
    -H "Authorization: Basic b3BlcmF0b3I6cGFzc3dvcmQ=" \
    -H "x-upyun-meta-a: 3" \
    -H "x-upyun-meta-c: 4"

文件 abc.txt 的元信息为:

x-upyun-meta-a: 3
x-upyun-meta-c: 4

例 3:删除元信息,metadata=delete

curl -d 'abc' http://v0.api.upyun.com/<bucket>/abc.txt \
    -H "Authorization: Basic b3BlcmF0b3I6cGFzc3dvcmQ=" \
    -H "x-upyun-meta-a: 1" \
    -H "x-upyun-meta-b: 2"

curl -XPATCH http://v0.api.upyun.com/<bucket>/abc.txt?metadata=delete \
    -H "Authorization: Basic b3BlcmF0b3I6cGFzc3dvcmQ=" \
    -H "x-upyun-meta-a: true"

文件 abc.txt 的元信息为:

x-upyun-meta-b: 2

常见应用案例

例 1:修改 Metadata 默认不更新文件的 Last-Modified,如果需要更新,在参数中指定 update_last_modified=true

curl -XPATCH http://v0.api.upyun.com/<bucket>/abc.txt?metadata=replace&update_last_modified=true \
    -H "Authorization: Basic b3BlcmF0b3I6cGFzc3dvcmQ=" \
    -H "x-upyun-meta-a: 3" \
    -H "x-upyun-meta-c: 4"

例 2:Content-Secret 是被存储为 x-upyun-meta-secret 元信息,如果需要修改或删除,可以对 x-upyun-meta-secret 进行操作:

curl -XPATCH http://v0.api.upyun.com/<bucket>/abc.txt?metadata=delete \
    -H "Authorization: Basic b3BlcmF0b3I6cGFzc3dvcmQ=" \
    -H "x-upyun-meta-secret: upyun520"

签名认证(旧)

签名格式

Authorization: UpYun <operator>:<signature>

签名(signature)算法

签名所需的相关信息如下表:

所需信息 说明
METHOD 请求方式,如:GET、POST、PUT、HEAD 等
PATH 请求路径,需 URL 编码处理 (RFC 1738)
DATE 请求日期,GMT 格式字符串 (RFC 1123)
CONTENT_LENGTH 请求内容长度,除 GET 等无实体请求外,需和请求头部的 Content-Length 一致
PASSWORD 服务的操作员的密码

PASSWORD md5 之后(我们暂且将其记作 PASSWORD_MD5),上表所注的其他信息以 & 字符进行拼接(按表格从上至下的顺序)即(METHOD&PATH&DATE&CONTENT-LENGTH&PASSWORD_MD5),并将所得字符串进行 MD5 加密,即得我们所需的 签名(signature)

例如

请求方式为 GET,URI 为 bucket 服务的子目录 /sub,请求时间为 Wed, 29 Oct 2014 02:26:58 GMT,因为是 GET,所以 CONTENT-LENGTH0,假设该服务有一个授权操作员名为 upyun,该操作员密码为 password(密码 md5 后为 5f4dcc3b5aa765d61d8327deb882cf99),那么:

签名(signature)即是对字符串 GET&/bucket/sub&Wed, 29 Oct 2014 02:26:58 GMT&0&5f4dcc3b5aa765d61d8327deb882cf99 计算 MD5 所得,即:03db45e2904663c5c9305a9c6ed62af3,因此,只需在请求头部加上如下字段即可:

Authorization: UpYun upyun:03db45e2904663c5c9305a9c6ed62af3

图片预处理(旧)

参数 必选 说明
x-gmkerl-extract-color-count 主题色提取的颜色数量,默认 256
x-gmkerl-extract-format 主题色提取格式,默认 hex
x-gmkerl-thumbnail 缩略图版本名称,可搭配其他 x-gmkerl-* 参数使用
x-gmkerl-type 缩略类型,见 x-gmkerl-type 可选值列表
x-gmkerl-value 缩略类型对应的参数值,见 x-gmkerl-value 值说明
x-gmkerl-quality 压缩质量,默认 95
x-gmkerl-unsharp 是否锐化,默认锐化
x-gmkerl-rotate 图片旋转(顺时针),可选值:auto(0, 360]。详见旋转
x-gmkerl-crop 图片裁剪,格式:<w>x<h>a<x>a<y>。详见裁剪
x-gmkerl-exif-switch 是否保留 EXIF 信息,默认不保留
仅在搭配 x-gmkerl-cropx-gmkerl-typex-gmkerl-thumbnail 时有效
x-gmkerl-watermark-text 文字水印内容,必须经过 urlencode 处理
x-gmkerl-watermark-font 文字水印字体,默认 simsun,见 x-gmkerl-watermark-font 可选值列表
x-gmkerl-watermark-size 文字水印字体大小,正整数,单位像素,默认 32
x-gmkerl-watermark-align 水印对齐方式,默认 top,left,见 x-gmkerl-watermark-align 值说明
x-gmkerl-watermark-margin 水印边距,格式 x,y,既 水平边距,垂直边距,单位像素,默认 20,20
x-gmkerl-watermark-opacity 水印透明度,取值范围 0 ~ 100 的整数,默认 0
x-gmkerl-watermark-color 文字水印颜色,RGB 值,默认 #000000
x-gmkerl-watermark-border 文字水印边框,默认无边框,见 x-gmkerl-watermark-border 值说明

x-gmkerl-type 可选值列表

含义
fix_width 限定宽度,高度自适应
fix_height 限定高度,宽度自适应
fix_width_or_height 限定宽度和高度,宽高不足时不缩放
fix_both 固定宽度和高度,宽高不足时强行缩放
fix_max 限定最长边,短边自适应
fix_min 限定最短边,长边自适应
fix_scale 等比例缩放(1-1000)

x-gmkerl-value 值说明

x-gmkerl-watermark-font 可选值列表

x-gmkerl-watermark-align 值说明

格式 valign,halign,既 垂直对齐,水平对齐valignhalign 可选值:

x-gmkerl-watermark-border 值说明


如有疑问请 联系我们