QingCloud 文档 – Object API - kaiyun官方网站下载手机网页

Storage: 基础操作

Mon, 01 Jan 0001 00:00:00 +0000

上传对象：PUT Object
下载对象：GET Object
删除对象：Delete Object
获取对象元数据：HEAD Object
拷贝对象：PUT Object - Copy
移动对象：PUT Object - Move
导入对象：PUT Object - Fetch
查询对象：Options Object

Storage: Append Object

Mon, 01 Jan 0001 00:00:00 +0000

用户可以调用该 API 接口以追加写的方式上传对象到 QingStor 对象存储。通过该接口创建的 Object 类型为 appendable。

使用限制

每次追加写的数据不能超过 5 GB，Object 的总大小不能超过 50 TB；
非 appendable 类型的 Object 不支持被追加写；
appendable 类型的 Object 不支持加密；

请求语法

POST /<object-name>?append&position=<position> HTTP/1.1
Host: <bucket-name>.<zone-id>.qingstor.com
Date: <date>
Authorization: <authorization-string>

请求参数

调用该接口时，可在 URL 中添加如下参数：

名称	类型	说明	是否必选
append	String	表示以追加写的方式上传 Object	是
position	Integer	用于指定追加写的位置。首次调用该接口时，指定该值 0，后续调用该接口追加写时，指定该值为前一次返回结果中的 x-qs-next-append-position 值	是

请求消息头

名称	类型	说明	是否必选
Content-Length	String	本次追加写入的数据的大小。	是
Content-Type	String	Object 类型，首次写入时需指定。	否
Content-MD5	String	本次追加写入的数据的 MD5 值，用于检查数据在传输过程中是否出错或被篡改。	否
x-qs-storage-class	String	指定该对象的存储级别，首次写入时需指定。默认值为 `STANDARD`。可选值为： - `STANDARD` 表示标准存储； - `STANDARD_IA` 表示低频存储。	否

除以上请求头以外，此接口还需要包含 Host、Date 等公共请求头。详细内容可参见公共请求头。

请求消息体

无。

响应头

调用该接口后，QingStor 对象存储会返回如下自定义响应头：

名称	类型	说明	是否必选
x-qs-next-append-position	Interger	即当前 Object 大小。作为下一次追加写请求参数 `position` 的值。	是

除以上响应头以外，其他公共响应头可参考：公共响应头。

错误码

成功则返回 200，失败的返回码参考错误码列表。

示例

请求示例

POST /obj-append?append&position=0 HTTP/1.1
Host: mybucket.pek3a.qingstor.com
Date: Dec, 16 Aug 2019 09:05:00 GMT
Content-Length: 1024
Authorization: authorization string
[1024 bytes of object data]

响应示例

HTTP/1.1 200 OK
Server: QingStor
Date: Dec, 16 Aug 2019 09:05:00 GMT
Content-Length: 0
Connection: close
x-qs-request-id: 3f2cf9ac3168744d
x-qs-next-append-position: 1024

SDK

此接口所对应的各语言 SDK 可参考 SDK 文档。

Storage: Multipart 分段

Mon, 01 Jan 0001 00:00:00 +0000

功能概述

QingStor 对象存储的 Multipart 接口，提供了多个 API 来实现 Object 分段上传。除了支持客户端上传超过 5G 的大文件以外，还能实现客户端的断点续传，分段并发上传等高级特性。

完整的分段上传过程为:

客户端调用 Initiate Multipart Upload 来初始化一个 Object 分段上传。QingStor 对象存储返回该 Object 分段上传的唯一 Upload Id。
客户端根据 Object 内容偏移依次读取文件数据，并为每个分段标上大于等于 0 的整数标识后，调用 Upload Multipart Part 对每个分段进行上传。
客户端使用 List Multipart Parts 来查看指定 Upload Id 对应的已经上传的分段，以便实现断点续传。
在所有分段上传完毕后，客户端调用 Complete Multipart Upload 将指定 Upload Id 对应的分段进行合并并得到完整 Object。

注意事项

在上传分段过程中未完成的分段会增加 Bucket 的空间使用量，所以如果要取消上传过程，需要调用 Abort Multipart Upload 来清除没用的分段数据。
在 Bucket 中所有未完成的分段上传过程，可以通过 List Multipart Uploads 进行查看。
若指定 Upload Id 的同一分段多次上传，则最后一次调用会覆盖之前的上传数据。
若指定的 Bucket 中已存在同名的 Object，QingStor 对象存储会在该 Object 完整上传完成后，替换已有 Object。

并发操作

Multipart API 均为原子调用，能够支持并发。
对同一个 Object 多次调用 Initiate Multipart Upload 得到的 Upload Id 均不同。
对同一个 Object 的不同 Upload Id 的内容，调用 Upload Multipart Part、Complete Multipart Upload 以及 Abort Multipart Upload 均为独立过程，不会相互影响。
客户端可以对同一个 Upload Id 的各个分段使用多线程来上传，提高网络带宽的利用率。
若有多个请求对同一个 Upload Id 的同一个分段序号进行上传，以后传输完成的作为最终结果。

大文件的拷贝

大于 5G 的 Object，QingStor 对象存储不支持直接拷贝。客户端需要为目标位置 Object 调用 Initiate Upload，然后参照 Copy Object Part 并附带 x-qs-copy-range 请求头逐段拷贝数据，最后使用 Complete Multipart Upload 合并得到目标位置 Object。

分段上传限制

使用 Multipart 上传方式有如下几个限制：

每个分段最大为 5GB。
由 Upload Id 唯一标识的一个分段上传过程，最多可以支持的分段数量为 10000。
除最后一个分段不限最小长度以外，其它分段最小为 4MB。
一个 Object 的各个分片长度不要求一样。

因此，在使用 5GB 大小进行分段的时候，10000 个分段能支持上传最大为 50TB 的 Object；在使用最小分段 4MB 进行分段的时候，10000 个分段能支持上传最大 40GB 的 Object。

客户端可以根据实际需求选择分段大小。比如在外网环境，由于公网传输速度是由多种因素决定，其大小可能受到限制，考虑到保证服务端和客户端的交互，QingStor 对象存储建议，此时，客户端可以采用较小的长度来进行分段。

目前管理控制台上传大文件是采用 64MB 来作为分段大小。

Storage: Post Object

Mon, 01 Jan 0001 00:00:00 +0000

若用户需通过 HTML 表单上传的方式向 Bucket 上传一个 Object，可调用该接口。

使用须知

此操作要求请求者对 Bucket 拥有可写权限。
该方式开发难度较小，但是由于浏览器自身的限制，没有断点续传、上传进度等用户友好的功能。因此当文件大于 20M 或多个文件上传时，不建议使用该接口。
若指定的 Bucket 被设置为匿名用户可写，则请求中可不携带用户认证信息
若指定的 Bucket 被设置为匿名用户可写，请求中仍然携带了用户认证信息，则 QingStor 对象存储仍然会对该用户进行认证，当 QingStor 对象存储认证该用户不拥有该 Bucket 的可写权限，该请求返回错误。
若同时有多个上传请求写入同一个对象名称，则最后一个被 QingStor 对象存储处理的请求会覆盖之前上传的对象内容。
HTML 的表单设置如下：
action 为 http://<bucket-name>.<zone-id>.qingstor.com，其中 zone-id 可参考 Zone
method 必须为 POST
enctype 必须为 multipart/form-data
Object key 在表单项中设置。
考虑到不是所有网站都默认使用 UTF-8，若您的网站需要以 GBK 或 Big5 展示，我们支持在 Form 中声明 charset 字段来定义客户端上传的文件名所用编码。QingStor 对象存储服务端在接收到之后，会将其转换为 UTF-8 的格式来存储，以便兼容跨平台的客户端。但由于不是所有字符都能对应到 UTF-8 码表，转换过程仍有可能出现乱码，所以 QingStor 对象存储建议用户最好使用 UTF-8 来作为上传编码。

请求语法

POST / HTTP/1.1
Host: <bucket-name>.<zone-id>.qingstor.com
Content-Type: multipart/form-data; boundary=XXXXXX
Content-Length: length

请求参数

无。

请求消息头

此接口仅包含公共请求头。关于公共请求头的更多信息，请参见公共请求头。

表单项字段

表单字段	类型	描述	是否必须
access_key_id	String	Access Key ID。若该 Bucket 没有公开写权限，或含有 `policy`，则必须指定 `access_key_id`。	否
signature	String	签名认证信息。用 Secret Key 对 base64 编码后的 `policy` 字符串进行 HMAC-SHA256 签名即可。若表单含有 `access_key_id`，则必须设置该字段。	否
content-type	String	指定上传的文件类型，若用户上传的文件类型与本设置不一致，返回错误。	否
charset	String	指定上传的文件名的编码方式。必须与网页开头的 `<meta http-equiv="Content-Type" content="text/html;charset=***">` 中 `charset` 的设置一致。若不指定，QingStor 对象存储默认使用 `UTF-8` 对上传的文件名进行解码。	否
key	String	上传文件的 Object Key。有如下限制： - 不可以使用 `/` 开头。 - 可以为普通字符串，也可以是一个模板。 - 模板可以使用一些内置的变量，例如 `user/tom/${filename}`。	是
policy	String	设置上传文件的访问策略，由多个表单项组成。规则如下： - 将 `file` 之前的，除 `access_key_id`，`policy` 和 `signature` 以外的所有表单项。以 `JSON Object` 的格式，UTF-8 编码后进行组装； - 对以上内容进行 Base64 编码； - 若指定 Bucket 对匿名用户可写，则无需设置该字段。 - 若有不方便签名的表单项，需将其放置在表单项 `file` 的之后。	否
redirect	String	请求结果重定向 URL。重定向跳转时，会在该 URL 后面添加 Query String，包含 `status`，`code`，`message`，`request_id` 四个参数。示例：设置 `redirect` 为 `http://.com/callback`，请求成功后会以状态码 `302` 重定向至: `http://.com/callback?status=201&code=created&message=Object+created&request_id=XXXXXX`	否
file	Binary	待上传的文件，必须作为最后一个有效表单项。位于该项后面的表单项将被丢弃，故，该项后面的表单项不能作为签名的部分。	是
x-qs-storage-class	String	指定该对象的存储级别。默认值为 `STANDARD`，可选值为： - `STANDARD` 表示标准存储。 - `STANDARD_IA` 表示低频存储	否

备注：

若要给对象附带支持可修改的元数据，可在表单项里，添加相关字段。详细内容，可参见可修改的元数据。
表单项 key，若指定为模板，使用内置变量时，如 user/tom/${filename}，其中的 ${filename} 参考内置变量说明。

请求消息体

无。

响应头

此接口仅包含公共响应头。关于公共响应头的更多信息，请参见公共响应头。

错误码

该 API 为幂等操作. 上传成功返回 201; 假如有重定向则返回 302. 失败的返回码参考错误码列表。

示例

Signature 字段示例：

import hmac
import json
from hashlib import sha256
from base64 import b64encode

policy_json = {
    "key": "user/tom/${filename}",
    "redirect": "http://<mydomain>.com/callback",
    "charset": "UTF-8"
}
policy = b64encode(json.dumps(policy_json))
h = hmac.new(YOUR_SECRET_KEY, digestmod=sha256)
h.update(policy)
signature = b64encode(h.digest()).strip()

HTML 上传对象：

<!DOCTYPE html>
<html>
    <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
    <h3>Upload</h3>
    <form action="http://<bucket-name>.pek3a.qingstor.com" method="POST" enctype="multipart/form-data">
        <input type=hidden name="policy" value="eyJrZXkiOiAidXNlci90b20vJHtmaWxlbmFtZX0iLCAicmVkaXJlY3QiOiAiaHR0cDovL215ZG9tYWluLmNvbS9jYWxsYmFjayJ9" />
        <input type=hidden name="access_key_id" value="YYY" />
        <input type=hidden name="signature" value="XXX" />
        <input type=hidden name="key" value="user/tom/${filename}"/>
        <input type=hidden name="charset" value="UTF-8" /> <!-- 该网页为UTF-8 -->
        <input type=hidden name="redirect" value="http://<mydomain>.com/callback"/>
        <input type=file name="file" />
        <input type=submit name="Upload" value="Upload to QingStor" />
    </form>
</html>

Policy 字段示例：

未编码的 JSON 格式 policy 如下:

{"key": "user/tom/${filename}", "redirect": "http://.com/callback"}

对应的 base64 编码后的 policy 为:

eyJrZXkiOiAidXNlci90b20vJHtmaWxlbmFtZX0iLCAicmVkaXJlY3QiOiAiaHR0cDovLzxteWRvbWFpbj4uY29tL2NhbGxiYWNrIn0=

请求示例

POST / HTTP/1.1
Host: .pek3a.qingstor.com
User-Agent: curl/7.30
Content-Type: multipart/form-data; boundary=1234567890
Content-Length: length

--1234567890
Content-Disposition: form-data; name="access_key_id"

YYY
--1234567890
Content-Disposition: form-data; name="policy"

eyJrZXkiOiAidXNlci90b20vJHtmaWxlbmFtZX0iLCAicmVkaXJlY3QiOiAiaHR0cDovLzxteWRvbWFpbj4uY29tL2NhbGxiYWNrIn0=
--1234567890
Content-Disposition: form-data; name="signature"

XXX
--1234567890
Content-Disposition: form-data; name="key"

user/tom/${filename}
--1234567890
Content-Disposition: form-data; name="redirect"

http://.com/callback
--1234567890
Content-Disposition: form-data; name="file"; filename="icon.jpg"
Content-Type: image/jpeg

file_content
--1234567890
Content-Disposition: form-data; name="Upload"

Upload to QingStor
--1234567890--

响应示例

HTTP/1.1 302 Found
Server: QingStor
Date: Sun, 16 Aug 2015 09:05:00 GMT
ETag: "0c2f573d81194064b129e940edcefe9b"
Content-Length: 0
Connection: close
x-qs-request-id: aa08cf7a43f611e5886952542e6ce14b
Location: http://.com/callback?status=201&code=created&message=Object+created&request_id=aa08cf7a43f611e5886952542e6ce14b

SDK

此接口所对应的各语言 SDK 可参考 SDK 文档。

内置变量

名字	描述
filename	用户上传文件的文件名，默认为空。若该文件名中包含有目录，则仅需保留最后一个 `\` 或 `/` 之后的内容

Storage: 数据加密

Mon, 01 Jan 0001 00:00:00 +0000

该 API 接口用于对用户上传的 Object 进行加密处理。QingStor 对象存储支持由用户提供密钥的加密方式，对上传的 Object 进行加密。

注意事项

QingStor 对象存储服务端不保存用户的密钥。

什么是加密

加密过程

客户端自主生成密钥及密钥的 MD5 值，在上传 Object 时，通过加密请求头指定加密算法、密钥、和密钥 MD5 值。
QingStor 对象存储服务端根据用户提供的密钥，自主生成密钥 MD5 值，并将其与用户上传的密钥 MD5 值进行比对，以确认密钥在传输过程中的完整性。
当经过比对后，两者的密钥 MD5 值不一致，QingStor 对象存储返回失败，并丢弃用户上传的 Object。
当经过比对后，两者的密钥 MD5 值一致，QingStor 对象存储服务端对上传的 Object 进行加密。
加密完成后，QingStor 对象存储服务端丢弃用户上传的密钥，仅保存加密算法和密钥 MD5 值。

解密过程

客户端在获取 Object 时，通过加密请求头指定加密算法、密钥、和密钥 MD5 值。密钥须为上传时所指定的加密密钥。
QingStor 对象存储服务端根据用户提供的密钥，自主生成密钥 MD5 值，并将其与用户上传的密钥 MD5 值进行比对，以确认密钥在传输过程中的完整性。
当经过比对后，两者的密钥 MD5 值不一致，QingStor 对象存储返回失败。
当经过比对后，两者的密钥 MD5 值一致，QingStor 对象存储服务端将 Object 用请求头中指定的密钥解密并返回至客户端。

如何使用加密

加密请求头

除公共请求头。外，用户还需在请求头中添加如下头字段，用以指定加密算法、密钥、以及密钥 MD5 值。QingStor 对象存储根据该信息，对上传的 Object 进行加密。

头字段	类型	说明
x-qs-encryption-customer-algorithm	String	指定加密算法。目前仅支持 `AES256`。
x-qs-encryption-customer-key	String	用户提供的密钥。密钥必须进行 Base64 编码处理，对于 `AES256` 的密钥，明文长度必须为 32 字节。
x-qs-encryption-customer-key-MD5	String	用户提供的密钥的 MD5，用于检查密钥在传输过程中的完整性。密钥 MD5 必须进行 Base64 编码处理。

加密响应头

头字段	类型	说明
x-qs-encryption-customer-algorithm	String	加密时所用的加密算法
x-qs-encryption-customer-key-md5	String	加密时所用的密钥的 MD5

GET Object

若用户需从指定的 Bucket，获取之前存储的加密对象，可以使用 GET Object 接口，并携带该加密对象的加密信息。即：加密请求头。

除公共响应头外，QingStor 对象存储服务端还会返回加密响应头。

PUT Object

若用户上传 Object 时需加密，可以使用 PUT Object 接口，并携带加密请求头。

除公共响应头外，QingStor 对象存储服务端还会返回加密响应头。

PUT Object - Copy

用户可使用 PUT Object - Copy 接口拷贝加密 Object。拷贝 Object 的过程可分为：读取源 Object 与写入目标 Object。并且，QingStor 对象存储默认拷贝 Object 时，不会包含源 Object 的加密信息。

因此，用户需提供源加密 Object 的加密信息，用于成功读取源加密 Object。写入目标 Object 时，若用户仍需加密，此时需再次提供加密信息，用于对目标 Object 进行加密。

整个过程，用户需提供两个加密信息：源 Object 的加密信息与目标 Object 的加密信息。目标 Object 的加密信息，就是加密请求头。源 Object 的加密信息，则使用如下请求头字段：

头字段	类型	说明
x-qs-copy-source-encryption-customer-algorithm	String	源对象的加密算法。目前仅支持 `AES256`。
x-qs-copy-source-encryption-customer-key	String	源对象的密钥。密钥必须进行 Base64 编码处理，对于 `AES256` 的密钥，明文长度必须为 32 字节。
x-qs-copy-source-encryption-customer-key-md5	String	源对象的密钥的 MD5。密钥 MD5 必须进行 Base64 编码处理。

PUT Object - Move

若用户需移动指定加密 Object，可以直接使用 GET Object - Move 接口，无需添加额外的头字段。移动后，目标 Object 会保留源 Object 的所有密文和元数据。

HEAD Object

用户如需获取加密对象的元数据，可直接使用 HEAD Object 接口，无需携带加密请求头。若用户需验证加密算法和密钥是否正确，则可以在使用 HEAD Object 接口时，提供加密请求头一节中定义的头字段。

加密分段上传

QingStor 对象存储要求所有分段均使用相同的加密算法与密钥。因此，在初始化分段上传时，QingStor 对象存储会保存密钥的 MD5 用来验证后续上传分段的密钥是否相同。

API	描述
Initiate Multipart Upload	使用加密请求头一节中定义的头字段来初始化一个加密对象的分段上传。
Upload Object Part	上传一个分段时，使用加密请求头一节中定义的加密请求头部，以加密分段。
Copy Object Part	若源对象是加密的，则需要使用 PUT Object - Copy 一节中定义的头字段。若需为目标对象加密，可指定加密请求头一节中定义的头字段。
Complete Multipart Upload	完成加密对象的分段上传，无需提供加密请求头。
Abort Multipart Upload	中止加密对象的分段上传，无需提供加密请求头。

Storage: 图片处理

Mon, 01 Jan 0001 00:00:00 +0000

用户可以调用该 API 接口对存储于 QingStor 对象存储上的图片进行各种基本处理。

目前 QingStor 对象存储支持的图片操作类型有：查看图片信息；对图片进行剪裁，旋转，缩放；给图片添加文字水印，图片水印；将图片另存为，以及对图片进行格式的转换。

详细可参考：

注意事项

QingStor 对象存储目前暂不支持对加密后的图片进行处理
QingStor 对象存储目前可处理的单张图片最大为 10M。

通用格式

请求语法

GET /<object-name>?image&action=<operation:k_v[,k_v][|operation:k_v][,k_v]> HTTP/1.1
Host: <bucket-name>.pek3a.qingstor.com
Date: <date>
Authorization: <authorization-string>

请求参数

调用该接口时，如请求语法中内容所示，URL 中添加有相关参数。各参数字段说明如下：

名称	类型	说明	是否必选
action	String	对图片的一组操作。	是
operation	String	对图片的基本操作。详情请参考前文内容。 - 每个 `operation` 可以有多个键值对作为参数，多个键值对之间使用分隔符 `,` 隔开； - 多个 `operation` 之间使用分隔符 `｜` 隔开。	是
k	Char	`operation` 的参数名	是
v	Integer	`operation` 的参数值	是

请求示例

将图片按照 300*400(px) 进行固定宽高的缩略，并翻转 90 度。请求示例如下：

GET /myphoto.jpg?image&action=resize:w_300,h_400|rotate:a_90 HTTP/1.1
Host: mybucket.pek3a.qingstor.com
Date: Sun, 16 Aug 2015 09:05:00 GMT
Authorization: authorization string

图片格式

不同的图片操作类型，所支持的图片格式也有所区别。详情可参考下表：

操作类型	jpeg	png	webp	tiff	gif	svg	pdf
图片信息	Y	Y	Y	Y	Y	Y	Y
图片裁剪	Y	Y	Y	Y	N	N	N
图片旋转	Y	Y	Y	Y	N	N	N
图片缩放	Y	Y	Y	Y	Y	N	N
文字水印	Y	Y	Y	Y	N	N	N
图片水印	Y	Y	Y	Y	N	N	N
图片另存	Y	Y	Y	Y	Y	Y	Y
图片格式转换	Y	Y	Y	Y	N	N	N