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

bucket、path

<> 包含的内容，是需要用户填写的内容，填写时，把 <> 去掉。

bucket，云存储服务的名称；path，文件/文件夹的路径。

Authorization

认证鉴权，详见签名认证。

上传文件

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

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 的常见应用案例。
如果原文件是一张图片，除了通过文件密码进行访问外，还可以通过图片处理进行访问。
如果原文件是一张图片，文件密钥应避免与缩略图版本冲突，如果冲突，文件密钥的优先级大于缩略图版本。

并行式断点续传

适用于大文件上传和弱网环境上传，通过并行的传输数据块，更快的把文件传输到云端。弱网环境可以通过减少并行传输的块，控制速度。

名称概念

上传阶段：分为 initiate(初始化), upload(数据传输), complete(结束)三个阶段，各阶段依次进行，使用X-Upyun-Multi-Stage 参数表示。
文件分块：数据传输时，把文件切分成小块进行上传，分块大小为1M的整数倍，默认1M，最大50M，最后一个分块例外。
任务标识：初始化时，由服务端生成；数据传输时，标识分块属于那个任务，使用 X-Upyun-Multi-Uuid 参数表示。
分块序号：连接分块组成文件的序号，序号从 0 开始，第一个分块是 0，第二个分块是 1，以此类推，使用 X-Upyun-Part-Id 参数表示。
上传清理：未上传完成的文件会保存 24 小时，超时后，自动删除。
其它：并行式断点续传的图片不支持进行预处理。

初始化

初始化一个并行式断点续传任务，服务端返回任务标识。

请求信息

PUT /<bucket>/<path_to_file>

参数	必选	类型	说明
X-Upyun-Multi-Disorder	是	String	值为 `true`, 表示并行式断点续传
X-Upyun-Multi-Stage	是	String	值为 `initiate`
X-Upyun-Multi-Length	是	String	待上传文件的大小，单位 Byte
Content-Length	是	String	请求的内容长度
Content-MD5	否	String	请求的 MD5 值，需要服务端进行 MD5 校验请填写，等效于签名认证中的 `Content-MD5`
X-Upyun-Multi-Part-Size	否	String	`1M`整数倍，默认`1M`，最大`50M`，单位 Byte
X-Upyun-Multi-Type	否	String	待上传文件的 MIME 类型，默认 `application/octet-stream`，建议自行设置
X-Upyun-Meta-X	否	String	给文件添加的元信息，详见 Metadata
X-Upyun-Meta-Ttl	否	String	指定文件的生存时间，过期后自动删除，单位天，最大支持 180 天

响应信息

成功，返回 204 状态码，响应参数包括：

参数	类型	说明
X-Upyun-Multi-Uuid	String	任务标识

失败，返回出错信息，具体请参阅「API 错误码表」。

举例

curl -v http://v0.api.upyun.com/upyun/test.mp4 -X PUT \
-H "Authorization: UPYUN <Operator>:<Signature>" \
-H 'X-Upyun-Multi-Disorder: true' \
-H 'X-Upyun-Multi-Stage: initiate'  \
-H 'X-Upyun-Multi-Type: video/mp4' \
-H 'X-Upyun-Multi-Length: 34402774934'  \
-H 'Content-Length: 0'

< HTTP/1.1 204 No Content
< X-Upyun-Multi-Uuid: a1029397-fa1b-40b1-ad80-0b21814e24a9

数据传输

把文件切分成分块大小，并行传输各个分块。某个分块传输失败，直接重传该分块。

请求信息

PUT /<bucket>/<path_to_file>

参数	必选	类型	说明
X-Upyun-Multi-Stage	是	String	值为 `upload`
X-Upyun-Multi-Uuid	是	String	任务标识，初始化时生成
X-Upyun-Part-Id	是	String	分块序号，序号从 0 开始
Content-Length	是	String	请求的内容长度
Content-MD5	否	String	请求的 MD5 值，需要服务端进行 MD5 校验请填写，等效于签名认证中的 `Content-MD5`

响应信息

成功，返回 204 状态码，响应参数包括：

参数	类型	说明
X-Upyun-Multi-Uuid	String	任务标识

失败，返回出错信息，具体请参阅「API 错误码表」。

举例

curl -v http://v0.api.upyun.com/upyun/test.mp4 -X PUT \
-H "Authorization: UPYUN <Operator>:<Signature>" \
-H 'X-Upyun-Multi-Stage: upload'  \
-H 'X-Upyun-Multi-Uuid: a1029397-fa1b-40b1-ad80-0b21814e24a9' \
-H 'X-Upyun-Part-Id: 0'  \
-H 'Content-Length: 1048576' \
-d '<视频数据>'

< HTTP/1.1 204 No Content
< X-Upyun-Multi-Uuid: a1029397-fa1b-40b1-ad80-0b21814e24a9

结束

结束一个并行式断点续传任务。

请求信息

PUT /<bucket>/<path_to_file>

参数	必选	类型	说明
X-Upyun-Multi-Stage	是	String	值为 `complete`
X-Upyun-Multi-Uuid	是	String	任务标识
Content-Length	是	String	请求的内容长度
Content-MD5	否	String	请求的 MD5 值，需要服务端进行 MD5 校验请填写，等效于签名认证中的 `Content-MD5`

响应信息

成功，如果返回 204 状态码，表示之前有同名文件现在被覆盖；如果返回 201 状态码，表示文件上传成功，并且文件名是第一次出现。响应参数包括：

参数	类型	说明
X-Upyun-Multi-Uuid	String	任务标识
X-Upyun-Multi-Type	String	文件的 MIME 类型
X-Upyun-Multi-Length	String	文件的大小，单位 Byte

失败，返回出错信息，具体请参阅「API 错误码表」。

举例

curl -v http://v0.api.upyun.com/upyun/test.mp4 -X PUT \
-H "Authorization: UPYUN <Operator>:<Signature>" \
-H 'X-Upyun-Multi-Stage: complete'  \
-H 'X-Upyun-Multi-Uuid: a1029397-fa1b-40b1-ad80-0b21814e24a9' \
-H 'Content-Length: 0'

< HTTP/1.1 204 No Content
< X-Upyun-Multi-Length: 34402774934
< X-Upyun-Multi-Type: video/mp4
< X-Upyun-Multi-Uuid: a1029397-fa1b-40b1-ad80-0b21814e24a9

串行式断点续传

适用于弱网环境上传文件，针对上传带宽小、传输时间过长、传输过程容易中断等情况，把文件切分成小块，一块一块的进行传输，提高传输的稳定性和成功率。

名称概念

上传阶段：分为 initiate(初始化), upload(数据传输), complete(结束)三个阶段，各阶段依次进行，使用X-Upyun-Multi-Stage 参数表示。
文件分块：数据传输时，把文件切分成小块进行上传，分块大小是1M的整数倍，默认1M，最大50M，最后一个分块例外。
任务标识：初始化时，由服务端生成；数据传输时，标识分块属于那个任务，使用 X-Upyun-Multi-Uuid 参数表示。
分块序号：连接分块组成文件的序号，由服务端生成，通过 X-Upyun-Next-Part-Id 参数返回；数据传输时，使用 X-Upyun-Part-Id 参数表示。
上传清理：未上传完成的文件会保存 24 小时，超时后，自动删除。
其它：串行式断点续传的图片不支持进行预处理。

初始化

初始化一个串行式断点续传任务，服务端返回任务标识和第一个分块序号。

请求信息

PUT /<bucket>/<path_to_file>

参数	必选	类型	说明
X-Upyun-Multi-Stage	是	String	值为 `initiate`
X-Upyun-Multi-Length	是	String	待上传文件的大小，单位 Byte
Content-Length	是	String	请求的内容长度
Content-MD5	否	String	请求的 MD5 值，需要服务端进行 MD5 校验请填写，等效于签名认证中的 `Content-MD5`
X-Upyun-Multi-Part-Size	否	String	`1M`整数倍，默认`1M`，最大`50M`，单位 Byte
X-Upyun-Multi-Type	否	String	待上传文件的 MIME 类型，默认 `application/octet-stream`，建议自行设置
X-Upyun-Meta-X	否	String	给文件添加的元信息，详见 Metadata
X-Upyun-Meta-Ttl	否	String	指定文件的生存时间，过期后自动删除，单位天，最大支持 180 天

响应信息

成功，返回 204 状态码，响应参数包括：

参数	类型	说明
X-Upyun-Multi-Uuid	String	任务标识
X-Upyun-Next-Part-Id	String	第一个分块序号，值为 `0`

失败，返回出错信息，具体请参阅「API 错误码表」。

举例

curl -v http://v0.api.upyun.com/upyun/test.txt -X PUT \
-H "Authorization: UPYUN <Operator>:<Signature>" \
-H 'X-Upyun-Multi-Stage: initiate'  \
-H 'X-Upyun-Multi-Type: text/plain' \
-H 'X-Upyun-Multi-Length: 3027657'  \
-H 'Content-Length: 0'

< HTTP/1.1 204 No Content
< X-Upyun-Next-Part-Id: 0
< X-Upyun-Multi-Uuid: a1029397-fa1b-40b1-ad80-0b21814e24a9

数据传输

把文件切分成分块大小（最后一个分块列外）,一块一块进行传输。某个分块传输失败，重传该分块。

请求信息

PUT /<bucket>/<path_to_file>

参数	必选	类型	说明
X-Upyun-Multi-Stage	是	String	值为 `upload`
X-Upyun-Multi-Uuid	是	String	任务标识
X-Upyun-Part-Id	是	String	分块序号，必须等于服务端返回参数 `X-Upyun-Next-Part-Id` 的值
Content-Length	是	String	请求的内容长度
Content-MD5	否	String	请求的 MD5 值，需要服务端进行 MD5 校验请填写，等效于签名认证中的 `Content-MD5`

响应信息

成功，返回 204 状态码，响应参数包括：

参数	类型	说明
X-Upyun-Multi-Uuid	String	任务标识
X-Upyun-Next-Part-Id	String	下一个分块序号。当全部分块都传输完毕时，值为 `-1`

失败，返回出错信息，具体请参阅「API 错误码表」。

举例

curl -v http://v0.api.upyun.com/upyun/test.txt -X PUT \
-H "Authorization: UPYUN <Operator>:<Signature>" \
-H 'X-Upyun-Multi-Stage: upload'  \
-H 'X-Upyun-Multi-Uuid: a1029397-fa1b-40b1-ad80-0b21814e24a9' \
-H 'X-Upyun-Part-Id: 0'  \
-H 'Content-Length: 1048576' \
-d '<文本数据>'

< HTTP/1.1 204 No Content
< X-Upyun-Multi-Uuid: a1029397-fa1b-40b1-ad80-0b21814e24a9
< X-Upyun-Next-Part-Id: 1

结束

结束一个串行式断点续传任务。

请求信息

PUT /<bucket>/<path_to_file>

参数	必选	类型	说明
X-Upyun-Multi-Stage	是	String	值为 `complete`
X-Upyun-Multi-Uuid	是	String	任务标识
Content-Length	是	String	请求的内容长度
Content-MD5	否	String	请求的 MD5 值，需要服务端进行 MD5 校验请填写，等效于签名认证中的 `Content-MD5`

响应信息

成功，如果返回 204 状态码，表示之前有同名文件现在被覆盖；如果返回 201 状态码，表示文件上传成功，并且文件名是第一次出现。响应参数包括：

参数	类型	说明
X-Upyun-Multi-Uuid	String	任务标识
X-Upyun-Multi-Type	String	文件的 MIME 类型
X-Upyun-Multi-Length	String	文件的大小，单位 Byte

失败，返回出错信息，具体请参阅「API 错误码表」。

举例

curl -v http://v0.api.upyun.com/upyun/test.txt -X PUT \
-H "Authorization: UPYUN <Operator>:<Signature>" \
-H 'X-Upyun-Multi-Stage: complete'  \
-H 'X-Upyun-Multi-Uuid: a1029397-fa1b-40b1-ad80-0b21814e24a9' \
-H 'Content-Length: 0'

< HTTP/1.1 204 No Content
< X-Upyun-Multi-Length: 3027657
< X-Upyun-Multi-Type: text/plain
< X-Upyun-Multi-Uuid: a1029397-fa1b-40b1-ad80-0b21814e24a9

两种断点续传的区别

并行式断点续传强调上传的速度，众多分块并行上传，客户端通过调整并行传输的分块数量，控制上传的速率。
串行式断点续传强调上传的稳定，逐个分片逐个分片的传输，保证传输的成功率。

复制文件

同 bucket 下复制文件。它只能操作文件，不能操作文件夹。

请求信息

PUT /<bucket>/<save_as_file>

参数	必选	类型	说明
X-Upyun-Copy-Source	是	String	源文件地址，格式 `/<bucket>/<source_to_file>`
Content-Length	是	String	请求的内容长度为0
X-Upyun-Metadata-Directive	否	String	处理源文件的元信息，默认 `copy(复制)`，详见 Metadata
Content-MD5	否	String	请求的 MD5 值，需要服务端进行 MD5 校验请填写，等效于签名认证中的 `Content-MD5`

响应信息

成功，返回 200 状态码。
失败，返回出错信息，具体请参阅「API 错误码表」。

举例

curl -X PUT \
    http://v0.api.upyun.com/upyun/source.jpg \
    -H "Authorization: UPYUN <Operator>:<Signature>" \
    -H 'X-Upyun-Copy-Source: /upyun/foo/source.jpg' \
    -H "Content-Length: 0"

< HTTP/1.1 200 OK
< Content-Type: application/octet-stream
< Content-Length: 0

移动文件

同 bucket 下移动文件，可以进行文件重命名、文件移动。它只能操作文件，不能操作文件夹。

请求信息

PUT /<bucket>/<save_as_file>

参数	必选	类型	说明
X-Upyun-Move-Source	是	String	需要移动的文件地址，格式 `/<bucket>/<source_to_file>`
X-Upyun-Metadata-Directive	否	String	处理移动文件的元信息，默认 `copy(复制)`，详见 Metadata
Content-Length	是	String	请求的内容长度为0
Content-MD5	否	String	请求的 MD5 值，需要服务端进行 MD5 校验请填写，等效于签名认证中的 `Content-MD5`

响应信息

成功，返回 200 状态码。
失败，返回出错信息，具体请参阅「API 错误码表」。

举例

curl -X PUT \
    http://v0.api.upyun.com/upyun/newdir/source.jpg \
    -H "Authorization: UPYUN <Operator>:<Signature>" \
    -H 'X-Upyun-Move-Source:  /upyun/foo/source.jpg' \
    -H "Content-Length: 0"

< HTTP/1.1 200 OK
< Content-Type: application/octet-stream
< content-length: 0

注

移动文件不会触发文件的自动刷新，需要手动刷新需要移动文件的 URL。

下载文件

GET /<bucket>/<path_to_file>

响应信息

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

删除文件

DELETE /<bucket>/<path_to_file>

响应信息

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

创建目录

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\t0\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": 0,
        "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

如有疑问请联系我们

这篇文章有帮助吗?

Yes No

请求方法

上传文件

并行式断点续传

名称概念

初始化

数据传输

结束

串行式断点续传

名称概念

初始化

数据传输

结束

两种断点续传的区别

复制文件

移动文件

下载文件

删除文件

创建目录

删除目录

获取文件信息

获取目录文件列表

获取服务使用量

Metadata

添加 Metadata

修改 Metadata

常见应用案例

签名认证（旧）

图片预处理（旧）

这篇文章有帮助吗?

相关文章