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>"\
    # 其他可选参数...

基本域名

智能选路（推荐）：v0.api.upyun.com
电信线路：v1.api.upyun.com
联通（网通）线路：v2.api.upyun.com
移动（铁通）线路：v3.api.upyun.com

认证鉴权

详见签名认证。

上传文件¶

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

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	图片预处理参数，见上传预处理（同步）

响应信息

上传成功：返回 200，当上传文件是图片且设置 x-gmkerl-xxx 时，包含图片基本信息（包括图片宽、高、格式、帧数），例如：

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

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

Content-Secret 参数说明

文件设置 Content-Secret 后，文件将不能被直接访问，若需访问，需要在 URL 后加上「间隔标识符」和「文件密钥」。如：间隔符为 !，Content-Secret 为 abc，图片访问方式为： https://p.upyun.com/docs/cloud/secret.jpg!abc。
间隔标识符 用于分隔文件 URL 和文件密钥，有 3 种可选，分别是：!（感叹号/默认值）、-（中划线）和 _（下划线），可登录又拍云控制台，在「服务」 > 「功能配置」 > 「云处理」中设置。
删除或修改 Content-Secret，见 Metadata 的常见应用案例。
如果原文件是一张图片，除了通过文件密码进行访问外，还可以通过图片处理进行访问。
如果原文件是一张图片，文件密钥应避免与缩略图版本冲突，如果冲突，文件密钥的优先级大于缩略图版本。

断点续传¶

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

名称概念¶

文件分块：直接切分二进制文件成小块。分块大小固定为 1M。最后一个分块除外。
上传阶段：使用 x-upyun-multi-stage 参数来指示断点续传的阶段。分为以下三个阶段: initate(上传初始化), upload(上传中), complete(上传结束)。各阶段依次进行。
分片序号：使用 x-upyun-part-id 参数来指示当前的分片序号，序号从 0 起算。
顺序上传：对于同一个断点续传任务，只支持顺序上传。
上传标识：使用 x-upyun-multi-uuid 参数来唯一标识一次上传任务, 类型为字符串, 长度为 36 位。
上传清理：断点续传未完成的文件，会保存 24 小时，超过后，文件会被删除。

初始化断点续传¶

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

响应信息

下载成功：返回 200，HTTP body 中返回文件内容。
下载失败：返回相应的出错信息，具体请参阅「API 错误码表」。

删除文件¶

DELETE /<bucket>/path/to/file

请求参数

参数	必选	说明
x-upyun-async	否	`true` 表示进行异步删除，不设置表示同步删除（默认）

响应信息

删除成功：返回 200。
删除失败：返回相应的出错信息，具体请参阅「API 错误码表」。

注

同步删除有频率限制，批量删除请在请求头里加上 x-upyun-async: true 进行异步删除（无频率限制）。
异步删除请求成功，返回 200，但删除操作会延期执行。

创建目录¶

POST /<bucket>/path/to/folder

请求参数

参数	必选	说明
folder	是	值为 `true`

响应信息

创建成功：返回 200。
创建失败：返回相应的出错信息，具体请参阅「API 错误码表」。

删除目录¶

DELETE /<bucket>/path/to/folder

响应信息

删除成功：返回 200。
删除失败：返回相应的出错信息，具体请参阅「API 错误码表」。

注

只允许删除空的目录，非空目录需要先删除里面的文件，否则删除请求会被拒绝。

获取文件信息¶

HEAD /<bucket>/path/to/file

响应信息

获取成功：返回 200，返回头信息如下所示：

参数说明

x-upyun-file-type 文件为 file，文件夹为 folder

x-upyun-file-size 文件大小

x-upyun-file-date 文件创建时间

Content-Md5 文件的 MD5 值
获取失败：返回相应的出错信息，具体请参阅「API 错误码表」。

参数	说明
x-upyun-file-type	文件为 `file`，文件夹为 `folder`
x-upyun-file-size	文件大小
x-upyun-file-date	文件创建时间
Content-Md5	文件的 MD5 值

获取目录文件列表¶

GET /<bucket>/path/to/folder

分页参数

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

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

响应信息

获取成功：返回 200。
获取失败：返回相应的出错信息，具体请参阅「API 错误码表」。

例如：

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

x-upyun-list-iter 返回下一次分页开始位置。它由一串 Base64 编码的随机数组成，当它是 g2gCZAAEbmV4dGQAA2VvZg 时，表示最后一个分页。
HTTP body 为各个文件/目录的信息，文件/目录之间以 \n 分隔，属性按「文件\t类型\t大小\t最后修改时间」排列，类型可选值：N 表示文件，F 表示目录。

若设置了Accept: application/json请求头则返回:

{
    "files": [{
        "type": "image/jpeg",
        "length": 4237,
        "name": "foo.jpg",
        "last_modified": 1415096225
    }, {
        "type": "folder",
        "length": 423404,
        "name": "bar",
        "last_modified": 1415096260
    }],
    "iter": "c2Rmc2Rsamdvc2pnb3dlam9pd2Vmd2Z3Zg=="
}

获取服务使用量¶

GET /<bucket>/?usage

响应信息

获取成功：返回 200。HTTP body 内容为服务的使用量（单位为Byte）。
获取失败：返回相应的出错信息，具体请参阅「API 错误码表」。

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: bar 和 x-upyun-meta-a: 2 这两个元信息。

修改 Metadata¶

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

option 的取值如下：

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

响应信息

修改成功：返回 200。
修改失败：返回相应的出错信息，具体请参阅「API 错误码表」。

举例

例 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）

注

签名的有效期为 30 分钟。如果超过 30 分钟，则需重新生成签名。
GET，DELETE 操作的 CONTENT_LENGTH 为 0。

例如

请求方式为 GET，URI 为 bucket 服务的子目录 /sub，请求时间为 Wed, 29 Oct 2014 02:26:58 GMT，因为是 GET，所以 CONTENT-LENGTH 为 0，假设该服务有一个授权操作员名为 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-crop`、`x-gmkerl-type`、`x-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-type 指定为 fix_width_or_height 或 fix_both 时，x-gmkerl-value 值的格式为 <width>x<height>，如 480x576。
当 x-gmkerl-type 为其他的类型，x-gmkerl-value 值只需要指定单个数字，如 100，意思为高和/或宽为 100。

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

simsun：宋体(simsun)
simhei：黑体 (simhei)
simkai：楷体 (simkai)
simli：隶书 (simli)
simyou：幼圆 (simyou)
simfang：仿宋 (simfang)

x-gmkerl-watermark-align 值说明

格式 valign,halign，既 垂直对齐,水平对齐，valign、halign 可选值：

垂直对齐：top，middle，bottom；
水平对齐：left，center，right。

x-gmkerl-watermark-border 值说明

格式 rgba， RGB 表示边框的颜色，a 表示边框的透明度，如 #cccccccc

如有疑问请联系我们