青云QingCloud 对象存储相关帖子汇总
-
-
概述
青云对象存储服务(QingCloud Object Storage
Service,亦称QingStor)旨在为用户提供
稳定可靠,安全易用,空间无限的云存储服务。可存储任意类型,任意数量,任意大小
(单个对象最大至50T)的非结构化数据。本指南将介绍如何使用青云对象存储服务的API。总览
青云对象存储服务的 API 符合 REST (Representational State Transfer)
风格所定义的 语义,通过 URL 指定想要访问的资源,使用标准的 HTTP
方法(GET, PUT, DELETE, HEAD, POST)定义对资源的操作方式。基本概念
Zone
区域。和青云QingCloud一样,青云对象存储服务支持多区域部署。您可以在不同区域创建
存储空间(Bucket)。Service
对象存储服务的顶层命名空间,在该命名空间下,每一个用户可以创建多个存储空间
(Bucket)。存储存储名称在该命名空间下全局唯一。Bucket
用户申请的存储空间。创建存储空间时须选择区域。
Bucket 命名规范:
: - 遵守 DNS 命名规则。
- 长度在 6 ~ 63 之间。
- 只能包含 小写字母,数字和连接字符-
。
- 开头和结尾只能是小写字母或数字。
- 不能是有效 IP 地址。Object
用户操作的基本数据单元。PUT方法上传的 Object 允许最大 5GB;
分段(Multipart) 上传的 Object 最大可达 50TB。Object 命名规范:
- 长度须在 1-1023 字节之间
- 第一个字符不能是反斜杠(/)
- 须用 UTF-8 编码
地址构成
每个 Object 的访问地址有如下两种风格:
Virtual-host Style -
http://<bucket-name>.<zone-id>.qingstor.com/<object-name>Path Style -
http://<zone-id>.qingstor.com/<bucket-name>/<object-name>其中
<zone-id>
代表存储空间创建时选择的区域,目前对象存储开放的区域有:Name Zone ID URL Example 北京3区-A pek3a http://mybucket.pek3a.qingstor.com/myobject
-
公共字段
这里列出公共的 HTTP 头字段
请求头字段 (Request Header)
Header Name Description Host 指定所请求资源的主机名及端口。在HTTP/1.1中为必填字段,可以为空置。HTTP/1.0中为可选字段。http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.23 Authorization 认证所需信息。 http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.8 Date 请求发送时的时间。格式由RFC 822定义,如: Date: Tue, 15 Nov 1994 08:12:31 GMT http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.18 Content-Length 请求的内容长度,以字节为单位。 Content-Type 请求实体的MIME类型。总长度不可超过255个字符,且应该符合rfc文档的规范。若客户端未指定Content-Type或值为空, 服务端将按application/oct-stream处理。http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.13 Content-MD5 请求实体的MD5校验值,用来验证数据的完整性。http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.15 Expect 有效值:100-continue 用来确认服务端是否支持特定行为。当Expect的值为100-continue时,客户端在 发送请求实体前,等待服务器的确认,若服务器拒绝该请求,则请求实体将不会被发送。 http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.20 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 大于文件长度,那么返回整个文件。目前不支持rfc2616中定义的按逗号分隔的多段Range。如果指定了 Range 头字段,那么成功的情况下http返回码为 206 (Partial Content),参数有误或 start_offset 超出文件边界的情况下返回 416 (invalid_range_heander) 错误。 https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35 响应头字段 (Response Header)
Header Name Description Content-Length 服务端返回的消息实体的传输长度,以字节为单位 http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.13 Content-Type 服务端返回的消息实体的MIME类型。初期将只支持”application/json“格式. http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17 Connection 连接是否以关闭,有效值为“keep-alive”和“close” http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.10 Date 服务端返回(Response)时的日期和时间。格式由RFC 822定义,如: Date: Tue, 15 Nov 1994 08:12:31 GMT http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.18 ETag 对于通过 PUT object 上传的对象,该值由服务端生成,标志Object的内容(不包括Metadata)是否已被更新。对于通过 multipart upload 上传的对象,该值由调用 complete multipart upload 接口时,请求头中的 ETag 来设置。 http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.19 Server Web服务器软件信息,固定为“QingStor” http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.38 X-QS-Request-ID 服务端会为每个请求生成并返回一个唯一标示,提交工单时如果能附带此 ID 将有助于我们定位问题 Content-Range 当请求中附带了 Range 头字段时,返回中的 Content-Range 头说明了实际返回的数据在文件中的位置。格式为: bytes start_offset-stop_offset/file_size 如一个长度为500字节的文件,在请求中有 Range: bytes=0-0 的时候,返回中附带 Content-Range: bytes 0-0/500
-
错误信息
在请求返回的结果中,HTTP 状态码(status code)会表明处理完成后的状态,它符合 HTTP 规范所规定的语义。除此以外,当错误发生时,消息体以 json 格式返回具体的错误信息。
错误码
错误码列表:
错误代码 错误描述 HTTP 状态码 invalid_authorization_header 当签名不存在或格式错误时,返回此错误。 401 invalid_access_key_id 当 access key 不正确或不存在时,返回此错误。 401 user_suspended 当用户被禁用时,返回此错误。 403 missing_date_header 当 Header 中既缺少 Date 又没有 X-QC-Date 时,返回此错误。 400 invalid_date_header 当 Header 中的 Date 或 X-QC-Date 格式非法时,返回此错误。(正确格式如 Fri, 11 Sep 2015 23:37:14 ) 400 invalid_content_type_header 当请求头 Content-Type 不符合规则时,返回此错误,具体规则可参考 请求头字段 (Request Header) 中 Content-Type 的定义。 400 invalid_range_header 当请求头 Range 不符合规则时,返回此错误,具体规则可参考 请求头字段 (Request Header) 中 Range 的定义。 416 expired_signature 当请求的签名过期时,返回此错误。 401 signature_not_match 当请求的签名不匹配时,返回此错误 401 missing_argument 当请求中的参数缺失时,返回此错误。 400 invalid_argument 当请求中的参数值非法时,返回此错误。 400 permission_denied 当没有权限执行此次请求时,返回此错误。 403 bucket_suspended 当访问的 bucket 是暂停状态时,返回此错误。 403 bucket_already_exists 当创建的 bucket 已存在时,返回此错误。 409 bucket_not_exists 当访问的 bucket 不存在时,返回此错误。 404 object_not_exists 当访问的 object 不存在时,返回此错误。 404 invalid_bucket_name 当创建的 bucket 名称非法时,返回此错误。 400 too_many_buckets 当你创建的 bucket 超出限额时,返回此错误。(可通过工单提高额度) 403 bucket_not_empty 当删除一个非空的 bucket 时,返回此错误。 409 bucket_not_active 当访问的 bucket 不是活跃状态时,返回此错误。 403 lease_not_ready 当 bucket 租赁信息未准备好时,返回此错误。 403 invalid_method 当请求的 method 不被允许时,返回此错误。 405 invalid_request_body 当请求中的消息体非法时,返回此错误。 400 invalid_location 请求的区域不存在时,返回次错误。 400 max_requests_exceeded 当请求创建和删除 bucket 过于频繁时,返回该错误。 400 precondition_failed 当请求的 Header 中某些先决条件不满足时,返回此错误。 412 invalid_object_state 当 object 目前的状态不能接收此次操作时,返回此错误。 400 invalid_object_name 当 object 名称不符合规定时,返回此错误。 400 object_part_too_small 当分块上传 object 时分块的大小低于『最小块限制』时,返回此错误。目前最小块限制是 4M 。 400 object_too_large 当 object 数据超出最大限制时,返回此错误。目前最大限制是 5G 。 400 max_object_parts_exceeded 当分块上传 object 时,分块数量过多超出系统最大分块数量,则返回此错误。 目前最大分块数量是 1000 。 400 invalid_upload_id 若 upload id 非法时,返回此错误。 400 invalid_part_number 当分块上传 object 时,若分块索引超出范围时,返回此错误。 400 internal_error 对象存储系统内部错误,返回此错误,请稍后重试。 500 service_unavailable 对象存储系统临时不可用时,返回此错误,请稍后重试。 503 返回格式
错误信息的返回格式。
参数名 解释 code 错误码 message 详细错误信息 url 指向相关帮助文档 错误返回示例:
{ code: "bad_request", message: "Invalid argument(s) or invalid argument value(s)", url: "http://docs.qingcloud.com/object_storage/api/bucket/get.html", }
-
签名验证
获取 Access Key
对象存储通过使用 Access Key
对称加密的方法来验证请求者的身份。如果用户想以个人身份请求对象存储服务,首先需要拥有一对
Access key,包括 Access Key ID 和 Secret Access Key,其中 Secret Access
Key 在签名的时候会用到,需要保密。Access Key 申请在控制台左侧导航栏 API 密钥 -> 创建
构建签名串
构建 StringToSign
string_to_sign = Verb + "\n" + Content-MD5 + "\n" + Content-Type + "\n" + Date + "\n" + CanonicalizedHeaders + "\n" + CanonicalizedResource
- Verb 是 HTTP Method,包括 GET PUT DELETE OPTIONS 等
- Content-MD5 表示请求内容数据的 MD5
值,需要和请求头里的字段值保持一致,如果请求头没有这个参数,可以保留空白行 - Content-Type
表示请求内容的类型,需要和请求头里的字段值保持一致,如果请求头没有这个参数,可以保留空白行 - Date 表示此次请求的时间,需要是 HTTP 规范的 GMT 格式
- CanonicalizedHeaders 是请求头中以 X-QS- 开头的字段
- CanonicalizedResource 是请求访问的资源
签名串示例:
PUT\n 4gJE4saaMU4BqNR0kLY+lw==\n image/jpeg\n Wed, 10 Dec 2014 17:20:31 GMT\n /mybucket/photo.jpeg
构建 CanonicalizedHeaders
- 将所有以“ X-QS- ”为前缀的 HTTP 请求头的名字转换成小写字母。例如
’X-QS-Date: Wed, 10 Dec 2014 17:20:31 GMT’ 转换成 ’x-qs-date: Wed,
10 Dec 2014 17:20:31 GMT’ - 将上一步得到的所有 HTTP 请求头按照字典升序排列
- 删除请求头和内容之间分隔符两端出现的任何空格。例如 ’X-QS-Date: Wed,
10 Dec 2014 17:20:31 GMT’ 转换成 ’x-qs-date:Wed, 10 Dec 2014
17:20:31 GMT’ - 将所有的头和内容用 ’n’ 分隔符分隔拼成最后的 CanonicalizedHeaders 。
构建 CanonicalizedResource
- 将字符串初始化为格式 /<bucket-name>/<object-name>,例如
/mybucket/an-object,如果没有 object name 则为 /<bucket-name> - 若请求的资源包括子资源(sub_resource),那么将所有的子资源按照字典序,从小到大排列并以
& 为分隔符生成子资源字符串。在 CanonicalizedResource
字符串尾添加"?<sub_resource>" - 如果请求包含查询字符串(query string)则将查询参数 key
按照字母顺序排列,并用 & 连接,拼接到字符串的最后。
计算签名
- 将API密钥的私钥(secret_access_key)作为 key,生成被签名串的
HMAC-SHA256 签名:
import hmac from hashlib import sha256 h = hmac.new(secret_access_key, digestmod=sha256) h.update(string_to_sign)
- 将签名进行 Base64 编码:
import base64 sign = base64.b64encode(h.digest()).strip()
添加签名
添加 HTTP 请求头:
Authorization: QS-HMAC-SHA256 <access_key_id>:<signature>
请求头范例:
Authorization: QS-HMAC-SHA256 PLLZOBTTZXGBNOWUFHZZ:tuXu/KcggHWPAfEmraUHDwEUdiIPSXVRsO+T2rxomBQ=
-
Service API
GET Service
获取请求者名下的所有存储空间列表(Bucket list)。 不支持匿名请求,请先注册青云账号并创建 Access Key 后才能调用此 API 。
Request Syntax
GET / HTTP/1.1 Host: pek3a.qingstor.com Date: <date> Authorization: <authorization-string>
Request Parameters
没有请求参数
Request Headers
参见公共请求头
Request Elements
没有请求消息体
Response Headers
参见公共响应头
Response Elements
Name Type Description name String 存储空间的名称 owner String 存储空间的所有者 common_prefixes String 如果请求中指定了 delimiter 参数 , 则响应中包含该元素,用来标明那些以 delimiter 结尾,并有共同前缀的对象名称的集合。 Example
Example Request
GET / HTTP/1.1 Host: pek3a.qingstor.com Date: Sun, 16 Aug 2015 09:05:00 GMT Authorization: authorization string
Example Response
HTTP/1.1 200 OK Server: QingStor Date: Sun, 16 Aug 2015 09:05:00 GMT Content-Length: 7987 Connection: close Request-ID: aa08cf7a43f611e5886952542e6ce14b { "count": 2, "buckets": [ { "location": "pek3a", "name": "osier0", "urls": [ "http://osier0.qingstor.com", "http://osier0.pek3a.qingstor.com", "http://pek3a.qingstor.com/osier0" ], "created": "2015-07-11T04:45:57Z" }, { "location": "pek3a", "name": "osier1", "urls": [ "http://osier1.qingstor.com", "http://osier1.pek3a.qingstor.com", "http://pek3a.qingstor.com/osier1" ], "created": "2015-07-12T09:40:32Z" } ] }
-
Bucket API
GET Bucket (List Objects)
获取存储空间(bucket)下面的对象(object)列表,可指定返回的结果集长度, 但长度不能超出 200 。
此 API 需要调用者对 bucket 有读权限。
注解 获取存储空间列表请见 GET Service
Request Syntax
GET / HTTP/1.1 Host: <bucket-name>.pek3a.qingstor.com Date: <date> Authorization: <authorization-string>
Request Parameters
Parameter name Type Description Required prefix String 限定返回的 object key 必须以 prefix 作为前缀 No delimiter Char 是一个用于对 Object 名字进行分组的字符。所有名字包含指定的前缀且第一次出现 delimiter 字符之间的 object 作为一组元素 No marker String 设定结果从 marker 之后按字母排序的第一个开始返回 No limit Integer 限定此次返回 object 的最大数 No Request Headers
参见公共请求头
Request Elements
没有请求消息体
Response Headers
参见公共响应头
Response Elements
Name Type Description name String 存储空间的名称 owner String 存储空间的所有者 common_prefixes String 如果请求中指定了 delimiter 参数 , 则响应中包含该元素,用来标明那些以 delimiter 结尾,并有共同前缀的对象名称的集合。 prefix String 如果请求中指定了 prefix 参数 , 则响应中包含该元素。 marker String 如果请求中指定了 marker 参数 , 则响应中包含该元素。 items Array 匹配的对象元信息列表。 Example
Example Request
GET / HTTP/1.1 Host: mybucket.pek3a.qingstor.com Date: Sun, 16 Aug 2015 09:05:00 GMT Authorization: <authorization-string>
Example Response
HTTP/1.1 200 OK Server: QingStor Date: Sun, 16 Aug 2015 09:05:00 GMT Content-Length: 7987 Connection: close Request-ID: aa08cf7a43f611e5886952542e6ce14b { "name": "music", "owner": "Osier Yang", "prefix": "music/", "marker": "10.APE", "limit": 10, "delimiter": "/", "common_prefixes": [ "music/folk/zhangzhi", "music/folk/wild_children", ], "items": [ { "key":"hello.ape", "ETag": "bf1d737a4d46a19f3bced6905cc8b902", "size": "4096", "mime_type": "text/jepg", "created": "2014-08-29T01:06:16.000Z", "modified": "2014-08-29T01:06:26.000Z", }, ] }
带过滤条件的例子:
Example Request
GET /?prefix=S&marker=Simon HTTP/1.1 Host: mybucket.pek3a.qingstor.com Date: Sun, 16 Aug 2015 09:05:00 GMT Authorization: authorization string
Example Response
HTTP/1.1 200 OK Server: QingStor Date: Sun, 16 Aug 2015 09:05:00 GMT Content-Length: 7987 Connection: close Request-ID: aa08cf7a43f611e5886952542e6ce14b { "name": "music", "owner": "Osier Yang", "prefix": "S", "marker": "Simon", "limit": 10, "delimiter": "/", "common_prefixes": [ "music/folk/zhangzhi", "music/folk/wild_children", ], "items": [ { "key":"Samantha", "ETag": "bf1d737a4d46a19f3bced6905cc8b902", "size": "1024", "mime_type": "text/jepg", "created": "2014-08-29T01:06:16.000Z", "modified": "2014-08-29T01:06:26.000Z", }, ] }
PUT Bucket
创建一个新的存储空间,创建成功后,空间的 owner 就是 API 调用者。
存储空间的名称有一定的要求:
- 遵守 DNS 命名规则。
- 长度在 6 ~ 63 之间。
- 只能包含 小写字母,数字和连接字符
-
。 - 只能以小写字母或数字开头或结尾。
- 不能是有效 IP 地址。
如下面的是合法名称:
- [√] mybucket
- [√] my-bucket
下面的是非法名称:
- [X] Invalid Bucket
- [X] .mybucket
- [X] mybucket-
- [X] my_bucket
note
匿名无法调用此 API ,请先注册青云并创建 Access Key 。
Request Syntax ::
PUT / HTTP/1.1 Host:<bucket-name>.pek3a.qingstor.com Date: <date> Authorization:<authorization-string>
Request Parameters
没有请求参数
Request Headers
参见公共请求头 <object-storage-common-request-header>
Request Elements
没有请求消息体
Request Elements
没有请求消息体
Response Headers
参见公共响应头 <object-storage-common-response-header>
Example
Example Request
PUT / HTTP/1.1 Host: mybucket.pek3a.qingstor.com Date: Sun, 16 Aug 2015 09:05:00 GMT Authorization: authorization string
Example Response
HTTP/1.1 200 OK Server: QingStor Date: Sun, 16 Aug 2015 09:05:00 GMT Content-Length: 0 Connection: close Request-ID: aa08cf7a43f611e5886952542e6ce14b
DELETE Bucket
删除 URI 中指定的存储空间。存储空间需要为空,且是活跃状态才可以被删除。
即要先删除其中的对象,后删除存储空间,删除对象可参见
object-storage-api-delete-object 。Request Syntax ::
DELETE / HTTP/1.1 Host:<bucket-name>.pek3a.qingstor.com Date: <date> Authorization:<authorization-string>
Request Parameters
没有请求参数
Request Headers
参见公共请求头 <object-storage-common-request-header>
Request Elements
没有请求消息体
Response Headers
参见公共响应头 <object-storage-common-response-header>
Example
Example Request
DELETE / HTTP/1.1 Host: mybucket.pek3a.qingstor.com Date: Sun, 16 Aug 2015 09:05:00 GMT Authorization: authorization string
Example Response
HTTP/1.1 204 NoContent Server: QingStor Date: Sun, 16 Aug 2015 09:05:00 GMT Content-Length: 0 Connection: close Request-ID: aa08cf7a43f611e5886952542e6ce14b
HEAD Bucket
判断一个存储空间是否存在,以及是否有权限访问这个空间。
如果可访问,会返回 200 ,否则会返回 404 或 403 。Request Syntax ::
HEAD / HTTP/1.1 Host: <bucket-name>.pek3a.qingstor.com Date: <date> Authorization:<authorization-string>
Request Parameters
没有请求参数
Request Headers
参见公共请求头 <object-storage-common-request-header>
Request Elements
没有请求消息体
Request Elements
没有请求消息体
Response Headers
参见公共响应头 <object-storage-common-response-header>
Example
Example Request
HEAD / HTTP/1.1 Host: mybucket.pek3a.qingstor.com Date: Sun, 16 Aug 2015 09:05:00 GMT Authorization: authorization string
Example Response
HTTP/1.1 200 OK Server: QingStor Date: Sun, 16 Aug 2015 09:05:00 GMT Content-Length: 0 Connection: close Request-ID: aa08cf7a43f611e5886952542e6ce14b
GET Bucket Statistics
获取存储空间的元数据。 只有存储空间的所有者才能调用此 API 。
Request Syntax
GET /?stats HTTP/1.1 Host: <bucket-name>.pek3a.qingstor.com Date: <date> Authorization: <authorization-string>
Request Parameters
没有请求参数
Request Headers
参见公共请求头
Request Elements
没有请求消息体
Response Headers
参见公共响应头
Response Elements
Name Type Description count Integer 存储空间存储的对象数量 size Integer 存储空间存储的对象总大小 location String 存储空间所在区域(zone)名称 created Date 存储空间的创建时间 status Enum 存储空间的状态,枚举值:active, suspended Example
Example Request
GET / HTTP/1.1 Host: mybucket.pek3a.qingstor.com/?stats Date: Sun, 16 Aug 2015 09:05:00 GMT Authorization: authorization string
Example Response
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 Request-ID: aa08cf7a43f611e5886952542e6ce14b { "count": 89, "status": "active", "name": "mybucket", "created": "2015-07-22T02:23:04.000Z", "url": "http://mybucket.pek3a.qingstor.com", "location": "zw", "size": 151597 }
GET Bucket ACL
获取存储空间的访问控制信息 (ACL: Access Control List), 只有存储空间的所有者才能获取 ACL 。
设置 ACL 请参见 PUT Bucket ACL 。
Request Syntax
GET /?acl HTTP/1.1 Host: <bucket-name>.pek3a.qingstor.com Date: <date> Authorization: <authorization-string>
Request Parameters
没有请求参数
Request Headers
参见公共请求头
Request Elements
没有请求消息体
Request Elements
没有请求消息体
Response Headers
参见公共响应头
Response Elements
Name Type Description owner String 存储空间的所有者 grantee String 授权者,id 可以是青云用户 ID,或者星号 *,代表匿名用户 permission Enum 访问权限,枚举值:READ / WRITE / FULL_CONTROL Example
Example Request
GET / HTTP/1.1 Host: mybucket.pek3a.qingstor.com/?acl Date: Sun, 16 Aug 2015 09:05:00 GMT Authorization: authorization string
Example Response
HTTP/1.1 200 OK Server: QingStor Date: Sun, 16 Aug 2015 09:05:00 GMT Content-Length: 0 Connection: close Request-ID: aa08cf7a43f611e5886952542e6ce14b { "owner": { "id": "usr-niWZfGCe", "name": "" }, "acl": [ { "grantee": { "id": "QS_ACL_EVERYONE", "name": "" }, "permission": "READ" }, { "grantee": { "id": "usr-1mvNCzZu", "name": "s3" }, "permission": "FULL_CONTROL" } ] }
PUT Bucket ACL
设置存储空间的访问控制,只有存储空间的所有者才能设置 ACL 。
获取 ACL 请参见 GET Bucket ACL 。
Request Syntax
PUT /?acl HTTP/1.1 Host: <bucket-name>.pek3a.qingstor.com Date: <date> Authorization: <authorization-string> { <user>: <grantee>, }
Request Parameters
没有请求参数
Request Headers
参见公共请求头
Request Elements
Name Type Description (user_id) String user_id 可为青云用户 ID 或表示匿名的特殊字符串 “QS_ACL_EVERYONE” , 属性值为 READ / WRITE / FULL_CONTROL Request Elements
没有请求消息体
Response Headers
参见公共响应头
Example
Example Request
PUT / HTTP/1.1 Host: mybucket.pek3a.qingstor.com/?acl Date: Sun, 16 Aug 2015 09:05:00 GMT Content-Length: 43 Authorization: authorization string { "QS_ACL_EVERYONE": "READ", "usr-niWZfGCe": "FULL_CONTROL", }
Example Response
HTTP/1.1 200 OK Server: QingStor Date: Sun, 16 Aug 2015 09:05:00 GMT Content-Length: 0 Connection: close Request-ID: aa08cf7a43f611e5886952542e6ce14b
-
Object API
GET Object
用于获取指定对象,此操作要求请求者对存储空间拥有可读权限。
注解 如果存储空间被设置为对匿名用户可读,则请求不需要携带认证信息。然而如果携带了认证信息,但是认证用户不拥有该存储空间的可读权限,则请求该接口会返回权限错误。
Request Syntax
GET /<object-name> HTTP/1.1 Host: <bucket-name>.pek3a.qingstor.com Date: <date> Authorization: <authorization-string> Range: bytes=<byte-range>
Request Parameters
没有请求参数
Request Headers
参见公共请求头
Header Name Type Description Required Range String 下载对象的某个字节区间,详情可见:http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35 当附加该请求头时,处理成功后返回的状态码为 206 Partial Content No If-Modified-Since Date 如果该对象自从指定时间往后被修改过,则正常下载对象,并返回 200 OK;否则返回 304 NOT MODIFIED No If-Unmodified-Since Date 如果该对象自从指定时间往后没有被修改过,则正常下载对象,并返回 200 OK;否则返回 412 PRECONDITION FAILED No If-Match String 如果对象内容的 ETag 值符合给定的值,则正常下载对象,并返回 200 OK;否则返回 412 PRECONDITION FAILED No If-None-Match String 如果对象内容的 ETag 值不同于给定的值,则正常下载对象,并返回 200 OK;否则返回 304 NOT MODIFIED No Request Elements
没有请求消息体
Response Headers
参见公共响应头
Response Elements
对象实体内容
Example
Example Request
GET /myphoto.jpg HTTP/1.1 Host: mybucket.pek3a.qingstor.com Date: Sun, 16 Aug 2015 09:05:00 GMT Authorization: authorization string
Example Response
HTTP/1.1 200 OK Server: QingStor Date: Sun, 16 Aug 2015 09:05:00 GMT Last-Modified: Fri, 14 Aug 2015 09:10:39 GMT Content-Type: image/jpeg Content-Length: 7987 Connection: close Request-ID: aa08cf7a43f611e5886952542e6ce14b [7987 bytes of object data]
PUT Object
用于向存储空间上传一个对象,此操作要求请求者对存储空间拥有可写权限。
注解 如果存储空间被设置为对匿名用户可写,则请求不需要携带认证信息。然而如果携带了认证信息,但是认证用户不拥有该存储空间的可写权限,则请求该接口会返回权限错误。
如果多个上传请求同时写入同一个对象名称(object name),最后一个被处理的请求会覆盖之前上传的对象内容。
如果希望在数据真正上传以前,提前得知该请求是否能被对象存储系统正确接受和处理,可以只发送 HTTP 请求头(不附带请求实体),并在请求头中包含 Expect: 100-continue。此方式主要使用场景是,当上传的对象实体非常庞大,为了提前知道该上传请求是否能被接受和处理(如认证信息是否正确,请求域名是否需要重定向等),减少不必要的数据传输。
Request Syntax
PUT /<object-name> HTTP/1.1 Host: <bucket-name>.pek3a.qingstor.com Date: <date> Authorization: <authorization-string>
Request Parameters
没有请求参数
Request Headers
参见公共请求头
Header Name Type Description Required Content-Length Integer 对象实体的字符数 Yes Content-MD5 String 对象实体的 MD5 值,用于检查对象在传输过程中字符是否出错或被篡改 No Content-Type String 对象的类型 No Expect String 如果请求头附加这个参数,不需要附带 request body,对象存储服务端判断可以接受此请求,则返回 100 CONTINUE No Request Elements
对象实体内容
Response Headers
参见公共响应头
Example
Example Request
PUT /myphoto.jpg HTTP/1.1 Host: mybucket.pek3a.qingstor.com Date: Sun, 16 Aug 2015 09:05:00 GMT Content-Length: 7987 Authorization: authorization string [7987 bytes of object data]
Example Response
HTTP/1.1 200 OK Server: QingStor Date: Sun, 16 Aug 2015 09:05:00 GMT ETag: "0c2f573d81194064b129e940edcefe9b" Content-Length: 0 Connection: close Request-ID: aa08cf7a43f611e5886952542e6ce14b
DELETE Object
用于删除指定对象,此操作要求请求者对存储空间拥有可写权限。
注解 如果存储空间被设置为对匿名用户可写,则请求不需要携带认证信息。然而如果携带了认证信息,但是认证用户不拥有该存储空间的可写权限,则请求该接口会返回权限错误。
Request Syntax
DELETE /<object-name> HTTP/1.1 Host: <bucket-name>.pek3a.qingstor.com Date: <date> Authorization: <authorization-string>
Request Parameters
没有请求参数
Request Headers
参见公共请求头
Request Elements
没有请求消息体
Response Headers
参见公共响应头
Response Elements
没有响应消息体
Example
Example Request
DELETE /myphoto.jpg HTTP/1.1 Host: mybucket.pek3a.qingstor.com Date: Sun, 16 Aug 2015 09:05:00 GMT Authorization: authorization string
Example Response
HTTP/1.1 204 NoContent Server: QingStor Date: Sun, 16 Aug 2015 09:05:00 GMT Content-Length: 0 Connection: close Request-ID: aa08cf7a43f611e5886952542e6ce14b
HEAD Object
只返回对象的元信息,不返回对象内容。此操作要求请求者对存储空间拥有可读权限。
注解 如果存储空间被设置为对匿名用户可读,则请求不需要携带认证信息。然而如果携带了认证信息,但是认证用户不拥有该存储空间的可读权限,则请求该接口会返回权限错误。
如果你只需要获取对象的元信息,或者检查对象是否存在,可使用该接口。
Request Syntax
GET /<object-name> HTTP/1.1 Host: <bucket-name>.pek3a.qingstor.com Date: <date> Authorization: <authorization-string> Range: bytes=<byte-range>
Request Parameters
没有请求参数
Request Elements
没有请求消息体
Request Headers
参见公共请求头
Header Name Type Description Required If-Modified-Since Date 如果该对象自从指定时间往后被修改过,则正常下载对象,并返回 200 OK;否则返回 304 NOT MODIFIED No If-Unmodified-Since Date 如果该对象自从指定时间往后没有被修改过,则正常下载对象,并返回 200 OK;否则返回 412 PRECONDITION FAILED No If-Match String 如果对象内容的 ETag 值符合给定的值,则正常下载对象,并返回 200 OK;否则返回 412 PRECONDITION FAILED No If-None-Match String 如果对象内容的 ETag 值不同于给定的值,则正常下载对象,并返回 200 OK;否则返回 304 NOT MODIFIED No Response Headers
参见公共响应头
Name Type Description Content-Type String 对象类型 Content-Length Integer 对象大小 Last-Modified Date 对象更新时间 ETag String 对象内容的 MD5 值 Response Elements
没有响应消息体
Example
Example Request
HEAD /myphoto.jpg HTTP/1.1 Host: mybucket.pek3a.qingstor.com Date: Sun, 16 Aug 2015 09:05:00 GMT Authorization: authorization string
Example Response
HTTP/1.1 200 OK Server: QingStor Date: Sun, 16 Aug 2015 09:05:00 GMT Last-Modified: Fri, 14 Aug 2015 09:10:39 GMT ETag: "0c2f573d81194064b129e940edcefe9b" Content-Type: image/jpeg Content-Length: 7987 Connection: close Request-ID: aa08cf7a43f611e5886952542e6ce14b
Initiate Multipart Upload
用于初始化一个分段上传,该请求会返回一个Upload ID,后续在上传分段时,在请求参数中附加该 Upload ID,则表明分段属于同一个对象。该请求需要对存储空间有可写权限。
注解 如果存储空间被设置为对匿名用户可写,则请求不需要携带认证信息。然而如果携带了认证信息,但是认证用户不拥有该存储空间的可写权限,则请求该接口会返回权限错误。
Request Syntax
POST /<object-name>?uploads HTTP/1.1 Host: <bucket-name>.pek3a.qingstor.com Date: <date> Authorization: <authorization-string>
Request Parameters
没有请求参数
Request Headers
参见公共请求头
Header Name Type Description Required Content-Type String 对象的类型 No Request Elements
没有请求消息体
Response Headers
参见公共响应头
Response Elements
Name Type Description bucket String 存储空间名称 key String 对象 key upload_id String 分段上传 ID,此 ID 用于后续上传分段时,作为参数使用 Example
Example Request
POST /large-object?uploads HTTP/1.1 Host: mybucket.pek3a.qingstor.com Date: Sun, 16 Aug 2015 13:25:10 GMT Authorization: authorization string
Example Response
HTTP/1.1 200 OK Server: QingStor Date: Sun, 16 Aug 2015 13:25:10 GMT Content-Type: application/json Content-Length: 90 Connection: close Request-ID: 37fed66c441a11e5b95f52542e6ce14b { "upload_id": "4d26b37a469230619604ecdc0e314782", "bucket": "mybucket", "key": "large-object" }
-
CLI 文档
QingStor 命令行工具 (Command Line Interface) 是与青云对象存储服务交互的命令行接口,通过命令行可以完成和使用对象存储 API 一样的操作。QingStor 命令行工具与 QingCloud CLI 集成在一起,安装方法和命令自动补全 参见 QingCloud CLI
Quick Start
使用 qingcloud-cli 必需一个配置文件,配置你自己的
qy_access_key_id
和qy_secret_access_key
以及 zone 。比如:qy_access_key_id: 'QINGCLOUDACCESSKEYID' qy_secret_access_key: 'QINGCLOUDSECRETACCESSKEYEXAMPLE' zone: 'pek3a'
access key 可在 青云控制台 申请。zone 是你的资源所在的节点,可在控制台切换节点的地方查看。
配置文件默认放在
~/.qingcloud/config.yaml
,也可在每次执行命令时以参数 -f /path/to/config 方式来指定,例如:qingcloud qs list-buckets -f '/root/qingcloud_config.yaml'
输入参数
如果只是输入 qingcloud qs -h 列出所有支持的命令, 每个命令都有帮助文档,可以通过 -h 参数打印出来,如:
qingcloud qs get-object -h
qingcloud-cli 的参数需要 int, string 和 list 类型。list 类型的输入方式是多个值之间以空格分隔。如:
qingcloud qs set-bucket-acl -b mybucket -A QS_ACL_EVERYONE,READ usr-wmTc0avW,FULL_CONTROL
命令输出
Command 的返回结果为 JSON 结构。例如 list-objects 的返回结果:
{ "name": "mybucket", "keys": [ { "key": "myphoto.jpg", "size": 67540, "modified": 1456226022, "mime_type": "image/jpeg", "created": "2016-02-23T11:13:42.000Z" }, { "key": "mynote.txt", "size": 11, "modified": 1456298679, "mime_type": "text/plain", "created": "2016-02-24T06:49:23.000Z" } ], "prefix": "", "owner": "qingcloud", "delimiter": "", "limit": 20, "marker": "mynote.txt", "common_prefixes": [] }
命令列表
最新版本 CLI 支持的操作命令
Service
list-buckets 获取存储空间列表
Bucket
create-bucket 创建存储空间
delete-bucket 删除存储空间
head-bucket 检查存储空间是否存在
stats-bucket 获取存储空间头信息
list-objects 获取对象列表
get-bucket-acl 获取存储空间的访问控制规则
set-bucket-acl 设置存储空间的访问控制规则Object
create-object 创建对象
get-object 获取对象
delete-object 删除对象
head-object 获取对象元信息
initiate-multipart 初始化分段上传
upload-multipart 上传分段
list-multipart 获取分段列表
complete-multipart 结束分段上传
abort-multipart 取消分段上传
-
SDK 文档