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

Storage: 概述

Tue, 17 Aug 2021 10:08:56 +0900

QingStor 对象存储服务旨在为用户提供稳定可靠，安全易用，空间无限的云存储服务。可用于存储任意类型，任意数量，任意大小的非结构化数据。

需注意的是，QingStor 对象存储支持的单个对象最大为 50T。

本文将详细介绍 QingStor 对象存储提供的 API，以及指导用户如何使用该 API。

总览

QingStor 对象存储服务提供的 API 符合 REST (Representational State Transfer) 风格所定义的语义，即：通过 URL 指定想要访问的资源，并使用标准的 HTTP 方法定义对资源的操作方式。

API 列表

Storage: 公共字段

Wed, 25 Nov 2020 10:08:56 +0900

请求头字段 (Request Header)

Host

指定所请求资源的云服务器名及端口。在 HTTP/1.1 中为必填字段，可以为空值。HTTP/1.0 中为可选字段。详情可参考 RFC 文档。

Authorization

认证所需信息。详情可参考 RFC 文档。

Date

客户端请求发送时的时间。格式由 RFC 822 定义，如：

Date: Tue, 15 Nov 1994 08:12:31 GMT

详情可参考 RFC 文档。

Content-Length

请求的内容长度，以字节为单位。详情可参考 RFC 文档。

Content-Type

请求实体的 MIME 类型。总长度不可超过 255 个字符，且应该符合 RFC 文档的规范。若客户端未指定 Content-Type 或值为空，服务端将按 application/octet-stream 处理。详情可参考 RFC 文档。

Content-MD5

请求实体的 MD5 校验值，用来验证数据的完整性。详情可参考 RFC 文档。

Expect

用来确认服务端是否支持特定行为。当 Expect 的值为 100-continue 时，客户端在发送请求实体前，等待服务器的确认，若服务器拒绝该请求，则请求实体将不会被发送。详情可参考 RFC 文档。

Range

用于指定请求的内容范围。取值可为以下三类，目前不支持 rfc2616 中定义的按逗号分隔的多段 Range：

bytes=start_offset-stop_offset 将返回从 start_offset 开始，至 stop_offset 的数据，单位为字节，包含 stop_offset 所对应的字节。如 bytes=0-0，将返回第一个字节的数据。
bytes=start_offset- 将返回从 start_offset 开始之后的数据，单位为字节，包含 start_offset 所对应的字节。
bytes=-suffix_length 将返回文件末尾长度为 suffix_length 的数据。若 suffix_length 大于文件长度，那么将返回整个文件。

若指定了 Range 头字段，那么成功的情况下 HTTP 返回码为 206，若参数有误或 start_offset 超出文件边界的情况下返回 416 错误。详情可参考 RFC 文档。

响应头字段 (Response Header)

Content-Length

服务端返回的消息实体的传输长度，以字节为单位。详情可参考 RFC 文档。

Content-Type

服务端返回的消息实体的 MIME 类型。仅支持 application/json 格式。详情可参考 RFC 文档。

Connection

标识连接是否已关闭，有效值为 keep-alive 和 close。详情可参考 RFC 文档。

Date

服务端返回响应时的日期和时间。格式由 RFC 822 定义，如：

Date: Tue, 15 Nov 1994 08:12:31 GMT

详情可参考 RFC 文档。

ETag

对于通过 PUT Object 上传的对象，该值由 QingStor 服务端生成，用于标识 Object 的内容是否已被更新。需要注意的是，这里提到的 Object 内容，不包括元数据。

对于通过 Multipart Upload 上传的对象，该值由调用 Complete Multipart Upload 接口时，请求头中的 ETag 来设置。若 ETag 值未被设置，QingStor 服务端，将会计算 ETag 值，并保存在 QingStor 的服务端。

详情可参考 RFC 文档。

Server

Web服务器软件信息，固定为 QingStor。详情可参考 RFC 文档。

x-qs-request-id

服务端会为每个请求生成并返回一个唯一标示。用户提交工单时如果能附带此 ID 将有助于 QingStor 对象存储的研发团队定位问题。

Content-Range

当请求中附带了 Range 头字段时，响应中的 Content-Range 头说明了实际返回的数据在文件中的位置。格式为：

bytes start_offset-stop_offset/file_size

如一个长度为500字节的文件，在请求中有 Range: bytes=0-0 的时候，响应中附带 Content-Range: bytes 0-0/500。详情可参考 RFC 文档。

x-qs-content-copy-range

当请求中附带了 x-qs-copy-range 头字段时，响应中的 x-qs-content-copy-range 头说明了实际返回的数据在文件中的位置。格式为：

bytes start_offset-stop_offset/file_size

如一个长度为500字节的文件，在请求中有 x-qs-copy-range: bytes=0-0 的时候，响应中附带 x-qs-content-copy-range: bytes 0-0/500

Storage: 对象元数据

Fri, 28 Feb 2020 10:08:56 +0900

QingStor 对象存储定义对象元数据是附属于对象的数据结构，不能脱离于对象而独立存在。

对象元数据包括标准 HTTP 头与自定义元数据。用户在创建对象时，可以在请求头中添加元数据信息。当用户在获取对象时，QingStor 对象存储服务端会返回请求头中添加的元数据信息。

QingStor 对象存储服务端也支持用户对元数据的修改。其中可供修改的元数据包括 Cache-Control，Cache-Disposition，Content-Encoding，Content-Type 以及 Expires 等 5 个标准 HTTP 头和用户自定义的元数据。

注意事项

QingStor 对象存储支持用户对元数据的增加与修改。匿名用户不支持该操作，用户需拥有该 Object 所在 Bucket 的读写权限。
当用户复制源对象到目标对象时，默认情况下，QingStor 对象存储会将源对象的元数据复制给目标对象。
当用户移动源对象到目标对象时，目标对象将保留源对象的元数据。
当用户删除对象时，该对象的元数据将被删除。

可修改的元数据

支持修改的对象元数据包括如下标准 HTTP 头与自定义元数据。详细说明如下：

标准 HTTP 头

QingStor 对象存储支持修改的标准 HTTP 头为：

名称	类型	说明	是否必须
Cache-Control	String	指定请求和响应遵循的缓存机制。了解更多信息见 RFC2616#14.9。	否
Cache-Disposition	String	指定对象的访问形式。 - inline：直接在浏览器中打开对象。 - attachment：将对象下载到本地。 - 了解更多信息见 RFC2616#19.5。	否
Content-Encoding	String	指定对象的内容编码类型。了解更多信息见 RFC2616#14.11。	否
Content-Type	String	指定请求实体的MIME类型。了解更多信息见 RFC2616#14.17。	否
Expires	String	响应过期的日期和时间。了解更多信息见 RFC2616#14.21。	否

除以上字段外，其他标准 HTTP 头不支持修改。其他标准 HTTP 头参考公共请求头。

自定义元数据

QingStor 对象存储支持用户自定义元数据，也支持用户修改这部分元数据信息。自定义元数据是指前缀为 x-qs-meta- 的键值对。QingStor 对象存储对自定义元数据的大小及有效字符均有限制。详细说明如下：

有效字符集：

自定义元数据中的 key 只能由英文字母、数字、连接符 -、下划线 _ 以及英文句号 . 组成。
自定义元数据中的 key 的长度不能超过 512 字节，且前缀 x-qs-meta- 不包括在 key 的长度计算范围内。
自定义元数据中的 value 只能由 Printable ASCII 字符组成。
自定义元数据中的 value 若带有 Non-printable ASCII 或 Non-ASCII 字符，用户可以使用 rfc2047 或者 percent encoding 来对其进行编码。也可以选择其他编码方式，只要编码后的字符集是 Printable ASCII 字符即可。
自定义元数据总大小不能超过 2KB。
由于 HTTP 头字段不区分大小写，所以自定义元数据的 key 也不区分大小写。

创建元数据

根据前文说明，我们知道对象元数据不能脱离于对象而独立存在。因此当创建对象的时候，相应的该对象的元数据也跟随创建。

支持该操作的 API 如下：

API	说明
PutObject	当向 Bucket 上传一个对象时，可以指定可修改的元数据一节中定义的请求头来创建可供修改的对象元数据。
PostObject	当通过 HTML 表单的方式上传一个对象时，可以使用可修改的元数据一节中定义的请求头来创建可供修改的对象元数据。
InitiateMultipartUpload	当初始化一个分段上传时，可以使用可修改的元数据一节中定义的请求头来创建可供修改的对象元数据。

获取元数据

用户可通过下载对象或获取对象信息的方式来获取该对象携带的元数据信息。支持该操作的 API 如下：

API	说明
GetObject	下载对象时，QingStor 对象存储服务端会返回该对象创建时所包含的元数据信息。
HeadObject	获取对象元数据时，QingStor 对象存储服务端会返回该对象创建时所包含的元数据信息。

复制修改元数据

用户可通过复制对象的方式，来复制或修改对象元数据。当用户调用如下 API 复制对象时，默认将源对象的元数据复制到目标对象：

API	说明
PutObject - Copy	当复制一个源对象到目标对象时，默认将源对象的元数据信息复制至目标对象

复制源对象的元数据

复制源对象到目标对象，此时会默认将源对象的元数据信息复制至目标对象。无需添加额外的消息头。

更新目标对象的元数据

复制对象时，可在消息头中指定可修改的元数据一节中定义的请求头来更新目标对象的元数据。此外，还需添加如下头字段，并将其设置为 replace。此时源对象的元数据信息不变，目标对象的元数据根据请求头中的设定而更新。

头字段	类型	说明
x-qs-metadata-directive	String	此选项用来修改元数据。有效值为 `copy` 或 `replace` 。默认值为 `copy`。 copy：复制源对象的元数据。 replace：表示修改对象的元数据

修改源对象的元数据

用户通过调用复制对象 API，并指定如下头字段，且将其设置为 replace，即可完成修改源对象的元数据操作。可修改的元数据参考前文内容。

头字段	类型	说明
x-qs-metadata-directive	String	此选项用来修改元数据。有效值为 `copy` 或 `replace` 。默认值为 `copy`。 copy：复制源对象的元数据。 replace：表示修改对象的元数据

移动元数据

用户可通过移动对象的方式来移动该对象携带的元数据信息。支持该操作的 API 如下：

API	说明
PutObject - Move	当移动一个源对象到目标对象时，源对象的元数据信息将保留。

示例

修改对象的元数据

创建一个命名为 copy_to_self 的对象，并附带元数据：x-qs-meta-id: 0 和 Cache-Control: no-cache。

请求服务端：

PUT /copy_to_self HTTP/1.1
Host: mybucket.pek3a.qingstor.com
Date: Thu, 05 Jul 2018 11:01:40 GMT
Cache-Control: no-cache
x-qs-meta-id: 0
Authorization: <authorization string>

服务端返回:

HTTP/1.1 201 CREATED
Server: QingStor
Date: Thu, 05 Jul 2018 11:01:40 GMT
x-qs-request-id: <x-qs-request-id>

调用 API：PUT Object COPY 将对象 copy_to_self 的元数据修改为： x-qs-meta-id: 1 与 Cache-Control: max-age=31536000。并添加头字段：x-qs-metadata-directive: replace。

请求服务端：

PUT /copy_to_self HTTP/1.1
Host: mybucket.pek3a.qingstor.com
Date: Thu, 05 Jul 2018 11:01:40 GMT
Cache-Control: max-age=31536000
x-qs-metadata-directive: replace
x-qs-copy-source: /mybucket/copy_to_self
x-qs-meta-id: 1
Authorization: <authorization string>

服务端返回：

HTTP/1.1 201 CREATED
Server: QingStor
Date: Thu, 05 Jul 2018 11:01:40 GMT
x-qs-request-id: <x-qs-request-id>

调用 API：HEAD Object 验证对象的元数据修改成功。

请求服务端：

HEAD /copy_to_self HTTP/1.1
Host: mybucket.pek3a.qingstor.com
Date: Thu, 05 Jul 2018 11:01:40 GMT
Authorization: <authorization string>

服务端返回：

HTTP/1.1 200 OK
Server: QingStor
Date: Thu, 05 Jul 2018 11:01:40 GMT
Cache-Control: max-age=31536000
x-qs-meta-id: 1
x-qs-request-id: <x-qs-request-id>

复制对象, 复制源对象的元数据

创建一个命名为 source_object 的对象，并附带元数据：x-qs-meta-id: 0 和 Cache-Control: no-cache。

请求服务端：

PUT /source_object HTTP/1.1
Host: mybucket.pek3a.qingstor.com
Date: Thu, 05 Jul 2018 11:01:40 GMT
Cache-Control: no-cache
x-qs-meta-id: 0
Authorization: <authorization string>

服务端返回:

HTTP/1.1 201 CREATED
Server: QingStor
Date: Thu, 05 Jul 2018 11:01:40 GMT
x-qs-request-id: <x-qs-request-id>

调用 API：PUT Object COPY 复制源对象 source_object 到目标对象 dest_object。复制 source_object 的元数据到 dest_object 为默认操作，故，这里可以省略请求头 x-qs-metadata-directive。

请求服务端：

PUT /dest_object HTTP/1.1
Host: mybucket.pek3a.qingstor.com
Date: Thu, 05 Jul 2018 11:01:40 GMT
x-qs-copy-source: /mybucket/source_object
Authorization: <authorization string>

服务端返回：

HTTP/1.1 201 CREATED
Server: QingStor
Date: Thu, 05 Jul 2018 11:01:40 GMT
x-qs-request-id: <x-qs-request-id>

调用 API：HEAD Object 验证目标对象 dest_object 的元数据与源对象 source_object 的元数据相同。

请求服务端：

HEAD /dest_object HTTP/1.1
Host: mybucket.pek3a.qingstor.com
Date: Thu, 05 Jul 2018 11:01:40 GMT
Authorization: <authorization string>

服务端返回：

HTTP/1.1 200 OK
Server: QingStor
Date: Thu, 05 Jul 2018 11:01:40 GMT
Cache-Control: no-cache
x-qs-meta-id: 0
x-qs-request-id: <x-qs-request-id>

复制对象, 在请求头中指定元数据

创建一个命名为 source_object 的对象，并附带元数据：x-qs-meta-id: 0 和 Cache-Control: no-cache。

请求服务端：

PUT /source_object HTTP/1.1
Host: mybucket.pek3a.qingstor.com
Date: Thu, 05 Jul 2018 11:01:40 GMT
Cache-Control: no-cache
x-qs-meta-id: 0
Authorization: <authorization string>

服务端返回:

HTTP/1.1 201 CREATED
Server: QingStor
Date: Thu, 05 Jul 2018 11:01:40 GMT
x-qs-request-id: <x-qs-request-id>

调用 API：PUT Object COPY 复制源对象 source_object 到目标对象 dest_object，并在请求头中指定元数据：x-qs-meta-id: 1, Cache-Control: max-age=31536000。此时需增加请求头字段：x-qs-metadata-directive : replace。

请求服务端：

PUT /dest_object HTTP/1.1
Host: mybucket.pek3a.qingstor.com
Date: Thu, 05 Jul 2018 11:01:40 GMT
Cache-Control: max-age=31536000
x-qs-copy-source: /mybucket/source_object
x-qs-meta-id: 1
Authorization: <authorization string>

服务端返回：

HTTP/1.1 201 CREATED
Server: QingStor
Date: Thu, 05 Jul 2018 11:01:40 GMT
x-qs-request-id: <x-qs-request-id>

调用 API：HEAD Object 验证目标对象 dest_object 的元数据与上一步请求头中的一致。

请求服务端：

HEAD /dest_object HTTP/1.1
Host: mybucket.pek3a.qingstor.com
Date: Thu, 05 Jul 2018 11:01:40 GMT
Authorization: <authorization string>

服务端返回：

HTTP/1.1 200 OK
Server: QingStor
Date: Thu, 05 Jul 2018 11:01:40 GMT
Cache-Control: max-age=31536000
x-qs-meta-id: 1
x-qs-request-id: <x-qs-request-id>

Storage: 错误信息

Fri, 28 Feb 2020 10:08:56 +0900

在请求返回的结果中，消息头中的 HTTP 状态码：Status Code，会表明请求处理完成后的状态，它符合 HTTP 规范所规定的语义。当错误发生时，请求返回的消息体会以 json 格式返回具体的错误信息。

错误码列表

错误代码	错误描述	HTTP 状态码
invalid_access_key_id	请求中的 Access Key 不正确或不存在	401
invalid_range	请求头中的 `Range` 不符合规则。具体规则可参考公共字段中 Range 的定义	416
request_expired	请求头中 `Date` 或 `x-qs-date` 与服务端本地时间差大于 15 分钟	403
signature_not_matched	请求中的签名不匹配	401
invalid_argument	请求中存在非法的参数值	400
bad_digest	请求头中携带的 `Content-MD5` 与服务端根据实际接收到的数据所计算出的 `MD5` 值不匹配	400
permission_denied	没有权限执行此次请求	403
bucket_already_exists	创建 Bucket时，Bucket 已存在	409
bucket_not_exists	访问的 Bucket 不存在	404
object_not_exists	访问的 Object 不存在	404
invalid_bucket_name	创建 Bucket 时，指定的 Bucket 名称不符合规则	400
too_many_buckets	创建 Bucket 时，超出限额。可通过工单提高额度	403
bucket_not_empty	删除非空的 Bucket	409
bucket_not_active	访问的 Bucket 状态不为活跃状态	403
lease_not_ready	Bucket 租赁信息未准备好	403
method_not_allowed	请求中指定的 `method` 不被允许	405
invalid_request	请求中的消息体不符合规定	400
invalid_location	请求头中携带的区域信息不存在	400
max_requests_exceeded	创建和删除 Bucket 的请求过于频繁	400
precondition_failed	请求的 Header 中某些先决条件不满足	412
invalid_object_state	当前 Object 状态不支持此次操作	400
invalid_object_name	Object 名称不符合规则	400
entity_too_small	分段上传时，Object 的分段大小小于 4M	400
entity_too_large	单个 Object 上传和使用分段上传时，Object 的大小或一个分段的大小大于 5G	400
max_parts_exceeded	分段上传时，分段数量超过最大分段量数 1000	400
upload_not_exists	分段上传时，请求中携带的 `upload id` 不存在	400
account_problem	账号异常	403
delinquent_account	账号欠费	402
invalid_json	请求消息体的 json 格式错误	400
access_denied	请求被拒绝	400
incomplete_body	请求消息体不完整	400
form_policy_violated	表单内容与策略不相符	400
cname_error	CNAME 设置错误	400
too_many_objects	操作包含的 Object 数量过多	400
fetch_in_process	调用 Fetch Object API 时，有相同源链接的 Fetch 请求正在进行中，或被动触发的外部镜像功能正在抓取该源链接对应的文件	409
metadata_too_large	自定义元数据总大小超过限制 2 KB 或键的长度，不含前缀 `x-qs-meta-`，超过 512 字节	400
fetch_throttled	服务端正在处理过多的抓取请求。包括 Fetch 请求从源链接抓取或外部镜像从源站抓取	429
internal_error	QingStor 对象存储系统内部错误，请稍后重试	500
service_unavailable	QingStor 对象存储系统临时不可用，请稍后重试	503
upstream_failed	无法与 Fetch 请求的源链接或者外部镜像的源站建立链接，或源站服务器返回 200，3xx，404 范围之外的错误代码，或链接中断	503

说明

分段上传时，QingStor 对象存储对 Object 的一个分段大小做出了限制。最小为 4M，最大为 5G。
单个 Object 上传时，QingStor 对象存储对其上限做出了限制，最大为 5G。
自定义元数据是指所有前缀为 x-qs-meta- 的键值对。计算自定义元数据大小时，不含前缀 x-qs-meta-。

错误返回格式

当错误发生时，请求返回的消息体会以 json 格式返回具体的错误信息。如下所示：

{
  "code": "bad_request",
  "message": "Invalid argument(s) or invalid argument value(s)",
  "request_id": "aa08cf7a43f611e5",
  "url": "http://docs.qingcloud.com/qingstor/api/error_code.html"
}

各字段说明

参数名	解释
code	错误码
message	详细错误信息
request_id	服务端为该次错误请求生成的唯一标示。QingStor 对象存储研发通过该 ID，能更快定位问题。
url	指向相关帮助文档

Storage: Bucket API

Fri, 28 Feb 2020 10:08:56 +0900

Storage: Object API

Wed, 25 Nov 2020 10:08:56 +0900

Storage: Service API

Wed, 25 Nov 2020 10:08:56 +0900

Storage: API 使用示例

Wed, 25 Nov 2020 10:08:56 +0900