QingCloud 文档 – 基础操作 - kaiyun官方网站下载手机网页

Storage: PUT Bucket

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

用于创建一个新的 Bucket。创建成功后，该 Bucket 的所有者就是 API 的调用者。匿名用户默认无法调用此 API，请先注册开·云app官方版下载账户并申请 Access Key。

请求语法

PUT / HTTP/1.1
Host: <bucket-name>.<zone-id>.qingstor.com
Date: <date>
Authorization: <authorization-string>

说明

Bucket 名称在 Qingstor 对象存储中是全局唯一的，并且遵守 DNS 规则。
Bucket 的命名规范：由长度为 6 ～ 63 的小写字母、数字、中划线组成的字符串，且以字母或数字开始和结尾。
Bucket 配额可通过工单申请调整。

请求参数

无。

请求头

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

请求体

无。

响应头

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

错误码

错误码	错误描述	HTTP 状态码
OK	成功创建 Bucket	201
bucket_already_exists	创建 Bucket时，Bucket 已存在	409
too_many_buckets	创建 Bucket 时，超出限额。	403

其他错误码可参考错误码列表。

示例

请求示例

PUT / HTTP/1.1
Host: mybucket.pek3a.qingstor.com
Date: Sun, 16 Aug 2015 09:05:00 GMT
Authorization: authorization string

响应示例

HTTP/1.1 201 CREATED
Server: QingStor
Date: Sun, 16 Aug 2015 09:05:00 GMT
Content-Length: 0
Connection: close
x-qs-request-id: aa08cf7a43f611e5886952542e6ce14b

SDK

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

Storage: HEAD Bucket

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

用于判断一个 Bucket 是否存在，以及用户是否有权限访问这个 Bucket。匿名用户默认无法调用此 API，请先注册开·云app官方版下载账户并申请 Access Key。

请求语法

HEAD / HTTP/1.1
Host: <bucket-name>.<zone-id>.qingstor.com
Date: <date>
Authorization: <authorization-string>

请求参数

无。

请求头

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

请求体

无。

响应头

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

错误码

错误码	错误描述	HTTP 状态码
OK	Bucket 存在或有权限访问该 Bucket	200

其他错误码可参考错误码列表。

示例

请求示例

HEAD / HTTP/1.1
Host: mybucket.pek3a.qingstor.com
Date: Sun, 16 Aug 2015 09:05:00 GMT
Authorization: authorization string

响应示例

HTTP/1.1 200 OK
Server: QingStor
Date: Sun, 16 Aug 2015 09:05:00 GMT
Content-Length: 0
Connection: close
x-qs-request-id: aa08cf7a43f611e5886952542e6ce14b

SDK

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

Storage: GET Bucket

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

用于获取 Bucket 的对象列表。此 API 需调用者对 Bucket 拥有读权限，匿名用户默认无法调用。

使用限制

调用该接口时，有如下注意事项：

QingStor 对象存储服务端对这个接口的调用频率会加以限制，建议用户的相关应用请勿依赖于该接口的并发调用。
该接口的响应速度，与 Bucket 内对象数目有关。若 Bucket 内对象数目不断增长，为了不影响相关资源的访问速度，QingStor 对象存储建议用户在业务侧自行保存对象名称或将对象名称拼接至需要访问的对象 URL 中。
QingStor 对象存储服务端会对目录归并结果进行缓存。当一个指定的前缀中，文件和子目录被频繁地更改，则缓存的结果，并不能立刻反映新目录的存在。

请求语法

GET / HTTP/1.1
Host: <bucket-name>.<zone-id>.qingstor.com
Date: <date>
Authorization: <authorization-string>

请求参数

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

名称	类型	说明	是否必选
prefix	String	限定返回的对象名（Object Key）前缀	否
delimiter	Char	对对象名（Object Key）进行分组的字符。所有对象名（Object Key）包含指定的前缀且第一次出现 `delimiter` 字符之间的 Object 作为一组元素	否
marker	String	列取的游标。用来实现分页显示效果	No
limit	Integer	限定此次返回 Object 的最大数量，默认值为 100。	No

使用说明

该 API 支持通过分页的方式获取给定前缀下的对象列表。具体操作如下：

传入参数 marker 为本次开始遍历的起始游标，返回以字母为顺序的最后一个对象名称作为 next_marker；
用户再次调用该 API，将上一次返回的 next_marker 的值传入 marker 参数；
返回值 has_more 为 false 时，表示遍历结束；
以此循环调用该 API，即可遍历满足 prefix 条件的所有对象列表。遍历返回结果的顺序为内部存储中的顺序，而非字节序。

参数说明

对象存储没有固定的目录结构，QingStor 对象存储通过 delimiter = '/' 参数来实现目录结构访问。
QingStor 对象存储将给定 prefix 下相同前缀的多个对象合并为一个结果，通过 common_prefixes 返回，以实现目录层级的浏览。
用户无须自行构造或修改 marker 的内容。首次调用时，不指定该参数，后续调用时，传入上一次 Response 返回的 next_marker 的值。
QingStor 对象存储服务端限制该 API 单次调用返回 Object 的最大数量为 100。用户可通过参数 limit 进行调整，设置的参数值若超出服务端限制，QingStor 对象存储服务仅会按照最大值进行处理。
若用户是自行拼接参数，调用该API，则需将 URL 参数进行 URL 编码。

请求头

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

请求体

无。

响应头

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

响应体

成功调用该 API 后，会返回一个 Json 消息体，其各字段说明如下：

名称	类型	说明
name	String	Bucket 的名称
owner	String	Bucket 的所有者
common_prefixes	String	若请求中指定了 `delimiter` 参数，则响应中包含该元素，用以标明那些以 `delimiter` 结尾，并有共同前缀的对象名（Object Key）的集合
prefix	String	若请求中指定了 `prefix` 参数，则响应中包含该元素
next_marker	String	返回这次遍历的游标(长度不固定)
marker	String	当前返回与 `next_marker` 相同，仅为了向前兼容而存在，不建议使用该值
has_more	Boolean	是否还有更多结果在下一页
keys	List	匹配的对象元信息列表
key	String	对象名称
size	Integer	对象大小
etag	Hex	对象内容的唯一标示 (该值会使用双引号括起来)
mime_type	String	对象类型
created	Date	对象创建时间
modified	Int	对象修改时间
encrypted	Boolean	对象是否加密
storage_class	String	对象的存储级别，目前支持的存储级别为 `STANDARD` 和 `STANDARD_IA`

错误码

错误码	错误描述	HTTP 状态码
OK	成功获取 Bucket 对象列表	200

其他错误码可参考错误码列表。

示例

请求示例

GET /?delimiter=/&limit=4 HTTP/1.1
Host: mybucket.pek3a.qingstor.com
Date: Sun, 16 Aug 2015 09:05:00 GMT
Authorization: authorization string

响应示例

HTTP/1.1 200 OK
Server: QingStor
Date: Sun, 16 Aug 2015 09:05:00 GMT
Content-Length: 559
Connection: close
x-qs-request-id: aa08cf7a43f611e5886952542e6ce14b

{
  "name": "mybucket",
  "keys": [
    {
      "created": "2016-08-22T15:03:32.000Z",
      "modified": 1471878212,
      "encrypted": true,
      "storage_class": "STANDARD",
      "etag": "\"4f44b10f5cb83777fea4ef88a3f7b3c4\"",
      "key": "api.txt",
      "mime_type": "text/plain",
      "size": 38970
    },
    {
      "created": "2016-08-22T15:09:52.000Z",
      "modified": 1471878592,
      "encrypted": false,
      "storage_class": "STANDARD_IA",
      "etag": "\"9f1cd921dbb6656c2c9e57f83f73d70e\"",
      "key": "bigtable-osdi06.pdf",
      "mime_type": "application/pdf",
      "size": 221214
    }
  ],
  "prefix": "",
  "owner": {
    "id": "usr-DxWdNcCr",
    "name": "william"
  },
  "delimiter": "/",
  "limit": 4,
  "marker": "",
  "next_marker": "bigtable-osdi06.pdf",
  "has_more": true,
  "common_prefixes": [
    "QCI/",
    "Screenshot/"
  ]
}

SDK

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

Storage: DELETE Bucket

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

该接口用于删除指定的 Bucket。待删除的 Bucket 需为空，且是活跃状态。由于计费系统的要求，Bucket 的创建和删除操作之间，需要相差一分钟以上。

若待删除 Bucket 不为空，需先删除存储于该 Bucket 中的对象，再删除该 Bucket。删除对象可参考 Delete Object。

请求语法

DELETE / HTTP/1.1
Host: <bucket-name>.<zone-id>.qingstor.com
Date: <date>
Authorization: <authorization-string>

请求参数

无。

请求头

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

请求体

无。

响应头

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

错误码

错误码	错误描述	HTTP 状态码
OK	成功删除 Bucket	204
bucket_not_exists	Bucket 不存在	404
bucket_not_empty	Bucket 不为空	409
lease_not_ready	Bucket 计费信息尚未准备好	403

其他错误码可参考错误码列表。

示例

请求示例

DELETE / HTTP/1.1
Host: mybucket.pek3a.qingstor.com
Date: Sun, 16 Aug 2015 09:05:00 GMT
Authorization: authorization string

响应示例

HTTP/1.1 204 NoContent
Server: QingStor
Date: Sun, 16 Aug 2015 09:05:00 GMT
Content-Length: 0
Connection: close
x-qs-request-id: aa08cf7a43f611e5886952542e6ce14b

SDK

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

Storage: Delete Multiple Objects

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

该接口用于从指定的 Bucket 中批量删除对象。此 API 需调用者对 Bucket 拥有写权限，匿名用户默认无法调用该 API。

请求语法

POST /?delete HTTP/1.1
Host: <bucket-name>.<zone-id>.qingstor.com
Date: <date>
Authorization: <authorization-string>
Content-MD5: Dd11y+x5Jegm/fUJ6mOuhg==

{
    "quiet": false,
    "objects": [
        {"key": <key-name-1>},
        {"key": <key-name-2>},
        ...
    ]
}

请求参数

无。

请求头

名称	类型	说明	是否必须
Content-MD5	String	请求体的 md5 值进行 base64 编码。	是

此接口涉及的其他公共请求头，请参见公共请求头。

请求消息体

调用该 API 需携带如请求语法中的 Json 消息体。该消息体各字段说明如下：

名称	类型	说明	是否必须
objects	List	待删除的对象列表。列表元素的格式为: `{"key": <key-name-1>}` 。object key 要求是 UTF8 编码并根据 json 规范来转义。	是
quiet	Bool	静默模式。如果打开，则请求返回的结果中不会包含删除成功的对象列表。默认关闭。	否

响应头

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

响应体

成功调用该 API 后，会返回一个 Json 消息体，其各字段说明如下：

Name	Type	Description
deleted	List	删除成功的对象列表，列表元素的格式为： `{"key": }` 。如果打开静默模式，则本项不会出现在返回结果中。
errors	List	删除失败的对象列表，列表元素的格式为： `{"key": , "code": string, "message": string}`

错误码

错误码	错误描述	HTTP 状态码
OK	成功删除	200

其他错误码可参考错误码列表。

示例

请求示例

POST /?delete HTTP/1.1
Host: mybucket.pek3a.qingstor.com
Date: Sun, 16 Aug 2015 09:05:00 GMT
Authorization: authorization string
Content-MD5: Dd11y+x5Jegm/fUJ6mOuhg==

{
    "quiet": false,
    "objects": [
        {"key": "object_1"}
    ]
}

响应示例

HTTP/1.1 200 OK
Server: QingStor
Date: Sun, 16 Aug 2015 09:05:00 GMT
Content-Length: 71
Connection: close
x-qs-request-id: aa08cf7a43f611e5886952542e6ce14b

{
    "deleted": [
        {"key": "object_1"}
    ],
    "errors": []
}

SDK

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

Storage: GET Bucket Statistics

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

获取 Bucket 的统计信息 (Statistics)。QingStor 对象存储定义只有 Bucket 的所有者才能调用。

请求语法

GET /?stats HTTP/1.1
Host: <bucket-name>.<zone-id>.qingstor.com
Date: <date>
Authorization: <authorization-string>

请求参数

无。

请求头

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

请求体

无。

响应头

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

响应体

成功调用该 API 后，会返回一个 Json 消息体，各返回字段说明如下：

名称	类型	说明
count	Integer	Bucket 内存储的对象数量
size	Integer	Bucket 内存储的对象所占用的空间大小
storage_classes	dict	Bucket 级别。可选值为 `STANDARD` 与 `STANDARD_IA`，即标准存储与低频存储
location	String	Bucket 所在区域，即 Zone ID
created	Date	Bucket 的创建时间
status	Enum	Bucket 的状态。枚举值：active, suspended

说明

storage_classes 为字典类型，对应的值为相应存储类型的统计信息，包括：count, size, billing_size。
标准存储中，上文的 size 和 billing_size 是相等的值；因为低频存储有最小存储计费时间的限制，故低频存储的 billing_size 大于等于上文中的 size。

错误码

错误码	错误描述	HTTP 状态码
OK	操作成功	200

其他错误码可参考错误码列表。

示例

请求示例

GET /?stats HTTP/1.1
Host: mybucket.pek3a.qingstor.com
Date: Sun, 16 Aug 2015 09:05:00 GMT
Authorization: authorization string

响应示例

HTTP/1.1 200 OK
Server: QingStor
Date: Sun, 16 Aug 2015 09:05:00 GMT
Content-Type: application/json
Content-Length: 222
Connection: close
x-qs-request-id: aa08cf7a43f611e5886952542e6ce14b

{
    "count": 10,
    "status": "active",
    "name": "mybucket",
    "created": "2015-07-22T02:23:04.000Z",
    "url": "mybucket.pek3a.qingstor.com",
    "location": "pek3a",
    "storage_classes": {
        "STANDARD": {
            "count": 5,
            "billing_size": 3000,
            "size": 3000
            },
        "STANDARD_IA": {
            "count": 5,
            "billing_size": 3180,
            "size": 3000
            }
        },
    "size": 6000
}

SDK

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

Storage: List Multipart Uploads

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

该接口用于获取 Bucket 内正在进行的分段上传对象的列表。列表按照对象名称的 alphanumeric 顺序从小到大排序。

正在进行的分段上传的对象，是指该对象已经调用 Initiate Multipart 接口开启了分段上传模式，且尚未调用 Complete Multipart 或 Abort Multipart 接口结束分段上传。

若用户只想获取某个对象已经上传的分段，请参考接口：List Multipart

请求语法

GET /?uploads HTTP/1.1
Host: <bucket-name>.<zone-id>.qingstor.com
Date: <date>
Authorization: <authorization-string>

请求参数

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

名称	类型	说明	是否必选
prefix	String	指定返回的分段上传对象名（Object Key）的前缀	否
delimiter	Char	用于给对象名（Object Key）分组的字符。列表返回从指定的前缀开始，至第一次出现该分割字符之间的对象名（Object Key）	否
key_marker	String	用于分页。当前页的起始标记	否
upload_id_marker	String	当前分段 `upload_id` 的起始标记	否
limit	Integer	此次返回的分段对象的最大数量，默认值为 200，最大允许设置 1000	否

说明

用户第一次发送该请求时，key_marker 与 upload_id_marker 均为空。QingStor 对象存储收到请求后，返回字段 next_key_marker 与 next_upload_id_marker。
用户第二次发送该请求时，将返回字段 next_key_marker 与 next_upload_id_marker 依次填入 key_marker 与 upload_id_marker，从而获取列表下一页内容。
若同名对象有多个分段上传，翻页被截断后只显示了一部分，下次翻页可通过 upload_id_marker 参数，获取剩下的分段上传。
用户通过传递 prefix 与 delimiter 参数，指定获取某个目录下面正在进行的分段上传。
该接口只列出未完成的分段上传对象，假设还有一个目录为 Sci-Fi/，但是该目录下没有未完成的分段上传，那么不会列出这个目录。

请求头

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

请求消息体

无。

响应头

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

响应体

成功调用该 API 后，会返回一个 Json 消息体，其各字段说明如下：

名称	类型	说明
name	String	Bucket 名称
prefix	String	请求参数 prefix
delimiter	Char	请求参数 delimiter
marker	String	请求参数 key_marker
limit	Integer	请求参数 limit
next_key_marker	String	本次返回列表里的最后一个 `key` 或 `common prefix`。当已经列取完全部的内容将返回空
next_upload_id_marker	String	如果有多个同名的分段上传，翻页时可能会被截断，该值是本次返回结果里最后一个 `upload id`，用于下一次请求参数 `upload_id_marker` 代表下一页的起始标志
uploads	List	正在进行的分段上传对象列表
common_prefixes	String	如果请求中指定了 `delimiter` 参数，那么将返回所有以 `prefix` 开头到第一个 `delimiter` 之间的分段上传对象名称（Object Key）的集合

错误码

错误码	错误描述	HTTP 状态码
OK	成功获取相应列表	200

其他错误码可参考错误码列表。

示例

请求示例

GET /?uploads&prefix=Movies/&delimiter=/&limit=6 HTTP/1.1
Host: mybucket.pek3a.qingstor.com
Date: Sun, 25 Dec 2016 19:02:00 GMT
Authorization: authorization string

响应示例

HTTP/1.1 200 OK
Server: QingStor
Date: Sun, 25 Dec 2016 19:02:00 GMT
Content-Length: 604
Connection: close
x-qs-request-id: aa08cf7a43f611e5

{
  "name": "mybucket",
  "uploads": [
    {
      "created": "2016-12-25T16:02:05.000Z",
      "key": "Movies/Star-Wars-2015.mp4",
      "upload_id": "44e76b0f5eda308e"
    },
    {
      "created": "2016-12-23T09:15:30.000Z",
      "key": "Movies/The-Godfather-1972.mp4",
      "upload_id": "8c0dc4f83f063d39"
    },
    {
      "created": "2016-12-23T02:17:00.000Z",
      "key": "Movies/The-Matrix-1999.mp4",
      "upload_id": "07ae9cab876a33a3"
    },
    {
      "created": "2016-12-24T09:15:30.000Z",
      "key": "Movies/The-Matrix-1999.mp4",
      "upload_id": "9f58a11f26cce132"
    },
  ],
  "prefix": "Movies/",
  "delimiter": "/",
  "limit": 6,
  "key_marker": "",
  "upload_id_marker": "",
  "next_key_marker": "Sci-Fi/",
  "next_upload_id_marker": "",
  "common_prefixes": [
    "Cartoon/",
    "Love/"
  ]
}

SDK

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