青云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

    1. 将所有以“ 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’
    2. 将上一步得到的所有 HTTP 请求头按照字典升序排列
    3. 删除请求头和内容之间分隔符两端出现的任何空格。例如 ’X-QS-Date: Wed,
      10 Dec 2014 17:20:31 GMT’ 转换成 ’x-qs-date:Wed, 10 Dec 2014
      17:20:31 GMT’
    4. 将所有的头和内容用 ’n’ 分隔符分隔拼成最后的 CanonicalizedHeaders 。

    构建 CanonicalizedResource

    1. 将字符串初始化为格式 /<bucket-name>/<object-name>,例如
      /mybucket/an-object,如果没有 object name 则为 /<bucket-name>
    2. 若请求的资源包括子资源(sub_resource),那么将所有的子资源按照字典序,从小到大排列并以
      & 为分隔符生成子资源字符串。在 CanonicalizedResource
      字符串尾添加"?<sub_resource>"
    3. 如果请求包含查询字符串(query string)则将查询参数 key
      按照字母顺序排列,并用 & 连接,拼接到字符串的最后。

    计算签名

    1. 将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)
    
    1. 将签名进行 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_idqy_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 文档


登录后回复
 

与 青云QingCloud 社区 的连接断开,我们正在尝试重连,请耐心等待