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
文件设置 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 小时，超过后，文件会被删除。
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
例 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）算法
签名所需的相关信息如下表：
将 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-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-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
如有疑问请 联系我们