关于Service的操作

得到该账户下所有桶

此GET操作返回请求者拥有的所有Bucket。需要使用AccessKey来验证请求,匿名请求不会返回bucket列表,并且你也无法得到不属于你的bucket的列表。

请求

  • 请求语法

    • 内容

        GET / HTTP/1.1 
        Host:OSS.inspurcloud.com 
        Date: date 
        Authorization: authorization string
      
    • 描述

        Endpoint:参考与region地域的关系 
        SignatureValue:参考签名算法
      
  • 请求参数

  • 非公共请求头

  • 请求体

响应

  • 非公共响应头

  • 响应体

名称 类型 描述
ListAllMyBucketsResult 容器 响应信息容器
子节点:Owner, Buckets
父节点:无
Owner 容器 包含bucket拥有者信息的容器
子节点:ID,DisplayName
父节点:ListAllMyBucketsResult
ID 字符串 Bucket拥有者的用户ID
父节点:ListAllMyBucketsResult.Owner
DisplayName 字符串 Bucket拥有者的名称
父节点:ListAllMyBucketsResult.Owner
Buckets 容器 包含一个或多个bucket的容器
子节点:Bucket
父节点:ListAllMyBucketsResult
Bucket 容器 包含bucket信息的容器
子节点:Name, CreationDate
父节点:ListAllMyBucketsResult.Buckets
Name 字符串 Bucket的名字
父节点:ListAllMyBucketsResult.Buckets.Bucket
CreationDate 时间(格式:yyyy-mm-ddThh:mm:ss.timezone, e.g., 2011-12-01T12:27:13.000Z) bucket的创建日期
父节点:ListAllMyBucketsResult.Buckets.Bucket

示例

  • 请求

      GET / HTTP/1.1
      Host: oss.inspurcloud.com
      Date: Wed, 01 Jan  2014 12:00:00 GMT
      Authorization: authorization string
    
  • 响应

      <?xml version="1.0" encoding="UTF-8"?>
      <ListAllMyBucketsResult>
        <Owner>
          <ID>bcaf1ffd86f461ca5fb16fd081034f</ID>
          <DisplayName>webfile</DisplayName>
        </Owner>
        <Buckets>
          <Bucket>
            <Name>quotes</Name>
            <CreationDate>2014-01-01T16:45:09.000Z</CreationDate>
          </Bucket>
          <Bucket>
            <Name>samples</Name>
            <CreationDate>2014-01-01T16:41:58.000Z</CreationDate>
          </Bucket>
        </Buckets>
      </ListAllMyBucketsResult>
    

    错误码

错误码 描述 状态码 描述
AccessDenied 拒绝访问 403 原因及排除请参看权限问题及排查

关于Bucket操作

获得桶内中所有对象的信息

此 GET 操作可以列出该 Bucket 下的部分或者全部 Object。此 API 调用者需要对 Bucket 有 Read 权限。

请求

  • 请求语法

    • 内容

        GET /  HTTP/1.1
        Host: {BucketName}.{endpoint}
        Date: {date}
        Authorization: {SignatureValue}
      
    • 描述

        Endpoint:参考与region地域的关系
        SignatureValue:参考签名算法
      
  • 请求参数

名称 类型 是否必须 描述
delimiter 字符串 分隔符,用于对一组参数进行分割的字符。默认值: 无
encoding-type 字符串 指明请求OSS与OSS响应使用的编码方式。object key 可以包含任意Unicode字符。然而,XML 1.0解析器无法解析某些字符,如ASCII码中的0到10。对于这些不能被解析的字符可以添加到请求中OSS会在响应中对他们进行编码。默认值: 无有效值: url
marker 字符串 指定列举指定空间中对象的起始位置。OSS按照字母排序方式返回结果,将从给定的 marker 开始返回列表。默认值: 无
max-keys 字符串 设置响应体中返回的最大记录数(最后实际返回可能小于该值)。默认为1000。如果你想要的结果在1000条以后,你可以设定 marker 的值来调整起始位置。默认值: 1000
prefix 字符串 限定响应结果列表使用的前缀,正如你在电脑中使用的文件夹一样。默认值: 无
  • 非公共请求头

  • 请求体

响应

  • 非公共响应头

  • 响应体

名称 类型 描述
ListBucketResult 容器 保存Get Bucket请求结果的容器。
子节点:Name, Prefix, Marker,MaxKeys, Delimiter, IsTruncated, Nextmarker, Contents
Name 字符串 存储桶空间的名称。
父节点: ListBucketResult
Prefix 字符串 该list请求时指定的key前缀父节点: ListBucketResult
Marker 字符串 指定列举指定空间中对象的起始位置。OSS按照字母排序方式返回结果,将从给定的 marker 开始返回列表。
父节点: ListBucketResult
MaxKeys 字符串 响应体中返回的最大记录数。默认为1000。类型: String
父节点: ListBucketResult
IsTruncated 枚举字符串 是否被截断。如果对象列表记录数超过了设定的最大值,那么将会被截断。有效值:true,false
父节点: ListBucketResult
Contents 容器 每一个对象返回的元数据。
父节点: ListBucketResult
Key 字符串 对象的 key。
父节点: ListBucketResult.Contents
LastModified 时间 最后一次被改动的时间和日期。父节点: ListBucketResult.Contents
ETag 字符串 ETag (entity tag) 在每个Object生成的时候被创建,用于标示一个Object的内容。对于PutObject请求创建的Object,ETag值是其内容的MD5值;对于其他方式创建的Object,ETag值是其内容的UUID。ETag值可以用于检查Object内容是否发生变化。不建议用户使用ETag来作为Object内容的MD5校验数据完整性。
父节点: ListBucketResult.Contents
Size 字符串 对象的大小,按字节统计。
父节点: ListBucketResult.Contents
StorageClass 字符串 存储方式,包括: STANDARD
父节点: ListBucketResult.Contents
Owner 字符串 存储桶空间拥有者信息。 子节点: DisplayName, ID
父节点: ListBucketResult.Contents
ID 字符串 对象拥有者的用户ID。
父节点: ListBucketResult.Contents.Owner
DisplayName 字符串 对象的名称。
父节点: ListBucketResult.Contents.Owner
CommonPrefixes 字符串 如果请求中指定了delimiter参数,则在OSS返回的响应中包含CommonPrefixes元素。该元素标明那些以delimiter结尾,并有共同前缀的object名称的集合。例如:指定分隔符为 /,对于notes/summer/a.txt 和 notes/summer/b.xml,其公共前缀为 notes/summer/。
父节点: ListBucketResult
Delimiter 字符串 分隔符,用于对一组参数进行分割的字符。
父节点: ListBucketResult
NextMarker 字符串 当存储桶空间中对象列表记录数超过了最大值,会标记列表被截(IsTruncated=true),同时返回下个记录的位置信息。用户在下次list objects的时候,可以使用该值作为marker参数。注意:当不提供delimiter参数的时候,OSS将不会返回NextMarker,如果IsTruncated为true,则可以使用返回的Contents中的最后一个key作为下次list的marker参数
父节点: ListBucketResult
Encoding-Type 字符串 OSS响应中对对象名称的编码方式。如果请求的参数中指定了encoding-type,那会对返回结果中的Delimiter、Marker、Prefix、NextMarker和Key这些元素进行编码。
父节点: ListBucketResult

示例

  • 请求

      GET / HTTP/1.1
      Host: oss-example.oss-cn-beijing.inspurcloud.com
      Date: Wed, 12 Oct 2009 17:50:00 GMT
      Authorization: authorization string    
    
  • 响应

      <?xml version="1.0" encoding="UTF-8"?>
      <ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
          <Name>oss-example</Name>
          <Prefix/>
          <Marker/>
          <MaxKeys>1000</MaxKeys>
          <IsTruncated>false</IsTruncated>
          <Contents>
              <Key>my-image.jpg</Key>
              <LastModified>2009-10-12T17:50:30.000Z</LastModified>
              <ETag>&quot;fba9dede5f27731c9771645a39863328&quot;</ETag>
              <Size>434234</Size>
              <StorageClass>STANDARD</StorageClass>
              <Owner>
                  <ID>67891234</ID>
                  <DisplayName>user-oss@163.com</DisplayName>
              </Owner>
          </Contents>
          <Contents>
             <Key>my-third-image.jpg</Key>
               <LastModified>2009-10-12T17:50:30.000Z</LastModified>
              <ETag>&quot;1b2cf535f27731c974343645a3985328&quot;</ETag>
              <Size>64994</Size>
              <StorageClass>STANDARD</StorageClass>
              <Owner>
                  <ID>67891234</ID>
                  <DisplayName>user-oss@163.com</DisplayName>
              </Owner>
          </Contents>
      </ListBucketResult>    
    

错误码

错误码 描述 状态码 描述
... ... ... ...

创建存储桶

此PUT操作将为用户创建一个新的存储桶。用户需要是已注册用户,并且使用有效的Access Key ID 验证来发送请求。任何匿名请求都不会被允许创建存储桶空间。用户将成为其创建存储桶的拥有者,拥有者有最高的权限。(命名规则需要在DNS命名规则之上,遵守我们的产品规格)

存储桶名称需要遵循DNS命名规则和惯例,符合DNS标准的存储空间名称使客户能够受益于新功能和操作改进,并支持对存储空间进行虚拟托管类型访问。存储空间只有一种统一的命名方法。符合DNS标准的存储空间名称规则如下:

  • 存储空间名称的长度必须为至少 3 个字符,且不能超过 63 个字符。

  • 存储空间名称必须是一系列的一个或多个标签,标签间可以用连字符(-)连接。存储空间名称可以包含小写字母、数字和连字符(-),且不能包含句点(.)。存储空间名称必须以小写字母或者数字开头和结尾。

  • 存储空间名称不得采用 IP 地址格式(例如,192.168.5.4)。

以下示例是有效存储空间名称:

  • my-bucket

  • mybucket123

  • 123mybucket

以下示例是无效存储空间名称:

  • -mybucket 存储段名称不能以连字符 (-) 开始。

  • mybucket- 存储段名称不能以连字符 (-) 结束。

  • my.bucket 存储段名称不能包含句点(.)。

请求

  • 请求语法

    • 内容

        PUT / HTTP/1.1
        Host: {BucketName}.{endpoint}
        Content-Length: {length}
        Date: {date}
        Authorization: {SignatureValue} 
        <CreateBucketConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
          <LocationConstraint>{BucketRegion}</LocationConstraint>
        </CreateBucketConfiguration>    
      
    • 描述

        Endpoint:参考与region地域的关系
        SignatureValue:参考签名算法
      
  • 请求参数

  • 非公共请求头

名称 类型 是否必须 描述
x-oss-acl 字符串 用于对象的预定义权限。
默认值:private
有效值:private; public-read; public-read-write
(提示)为用户授予权限的功能,在系统设计中,需要考虑,暂时不用实现,
可以参考(x-oss-grant-read、x-oss-grant-write、x-oss-grant-full-control)
  • 请求体
名称 类型 描述
CreateBucketConfiguration 容器 存储桶空间配置信息的容器。
父节点: None
LocationConstraint 字符串 指定存储桶空间将要被创建的地域。
有效值: BEIJING
默认值: BEIJING
父节点: CreateBucketConfiguration

响应

  • 非公共响应头

  • 响应体

示例

  • 请求

      PUT / HTTP/1.1
      Host: oss-example.oss-cn-beijing.inspurcloud.com
      Content-Length:0
      x-oss-acl: private
      Date: Wed, 01 Mar 2006 12:00:00 GMT
      Authorization: authorization string    
    
  • 响应

      HTTP/1.1 200 OK
      Date: Wed, 28 Oct 2009 22:32:00 GMT
      Content-Length: 0
      Connection: close
      Server:                                                                
    

错误码

错误码 描述 状态码 描述
... Bucket已经存在 409 bucket名称是全局唯一的

确认桶是否存在且有权限访问

此 HEAD 操作用于判断某一存储桶空间是否存在,以及用户所拥有的操作它的权限。如果指定存储桶空间存在且用户拥有访问它的权限,将返回 200 OK。否则,将会返回 404 Not Found 或 403 Forbidden 错误。

请求

  • 请求语法

    • 内容

        HEAD / HTTP/1.1
        Host: {BucketName}.{endpoint}
        Date: date
        Authorization: authorization string
      
    • 描述

        Endpoint:参考与region地域的关系
        SignatureValue:参考签名算法
      
  • 请求参数

  • 非公共请求头

  • 请求体

响应

  • 非公共响应头

  • 响应体

示例

  • 请求

      HEAD / HTTP/1.1
      Host: oss-example.oss-cn-beijing.inspurcloud.com
      Date: Wed, 01 Mar 2006 12:00:00 GMT
      Authorization: authorization string
      Connection: Keep-Alive    
    
  • 响应

      HTTP/1.1 200 OK
      x-oss-requestid: dbea4ce4ec23415b9e454ecfa2ec4d9
      Date: Fri, 10 2012 21:34:56 GMT
      Server:     
    

错误码

错误码 描述 状态码 描述
... ... ... ...

删除桶

此DELETE操作将删除URI中给定的存储桶。在删除存储桶前必须保证其中的所有对象均已删除。

请求

  • 请求语法

    • 内容

        DELETE / HTTP/1.1
        Host: {BucketName}.{endpoint}
        Date: {date}
        Authorization: {SignatureValue}    
      
    • 描述

        Endpoint:参考与region地域的关系
        SignatureValue:参考签名算法  
      
  • 请求参数

  • 非公共请求头

  • 请求体

响应

  • 非公共响应头

  • 响应体

示例

  • 请求

      DELECT / HTTP/1.1
      Host: oss-example.oss-cn-beijing.inspurcloud.com
      Date: Wed, 01 Mar 2006 12:00:00 GMT
      Authorization: authorization string    
    
  • 响应

      HTTP/1.1 204 No Content
      Date: Wed, 01 Mar 2006 12:00:00 GMT
      x-oss-requestid: dbea4ce4ec23415b9e454ecfa2ec4d9
      Connection: close
      Server:    
    

错误码

错误码 描述 状态码 描述
... ... ... ...

获取桶的权限

此GET操作返回 bucket 的 ACL(access control list)。 即存储桶的访问权限控制列表。 使用此接口,只有bucket的所有者有权限操作。

请求

  • 请求语法

    • 内容

        GET /?acl HTTP/1.1
        Host: {BucketName}.{endpoint}
        Date: {date}
        Authorization: {SignitureValue}    
      
    • 描述

        Endpoint:参考与region地域的关系
        SignatureValue:参考签名算法
      
  • 请求参数

  • 非公共请求头

  • 请求体

响应

  • 非公共响应头

  • 响应体

名称 类型 描述
AccessControlPolicy 容器 包含了每一个 Grantee 对于某个对象的 ACL 权限设置信息。子节点:AccessControlList 、Owner
AccessControlList 容器 包含 Grant,Grantee,Permission 的容器。子节点:Grant父节点:AccessControlPolicy
Grant 容器 包含被授权者和其权限信息。子节点:Grantee、Permission父节点AccessControlPolicy.AccessControlList
Grantee 字符串 被授权者。父节点:AccessControlPolicy.AccessControlList.Grant
Permission 字符串 指明授予被授权者的权限信息(FULL_CONTROL,READ,WRITE)。父节点:AccessControlPolicy.AccessControlList.Grant
Owner 容器 包含bucket拥有者信息(DisplayName,ID)的容器。子节点:ID、DisplayName父节点:AccessControlPolicy
ID 字符串 Bucket拥有者的用户ID。父节点:AccessControlPolicy.Owner
DisplayName 字符串 Bucket拥有者的名称。父节点:AccessControlPolicy.Owner

示例

  • 请求

      GET /?acl HTTP/1.1 
      Host: oss-example.oss-cn-beijing.inspurcloud.com
      Date: Wed, 01 Mar 2006 12:00:00 GMT
      Authorization: authorization string     
    
  • 响应

      <AccessControlPolicy>
      <Owner>
      <ID>73410125</ID>
      <DisplayName>123@163.com</DisplayName>
      </Owner>
      <AccessControlList>
      <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:type="CanonicalUser">
      <ID>73410125</ID>
      <DisplayName>123@163.com </DisplayName>
      </Grantee>
      <Permission>FULL_CONTROL</Permission>
      </Grant>
      </AccessControlList>
      </AccessControlPolicy>    
    

错误码

错误码 描述 状态码 描述
... ... ... ...

设置桶的权限

此 PUT 操作使用 acl 资源通过访问权限列表为已经存在的存储桶空间设定访问权限。当前只有Bucket的所有者拥有该权限,可以使用下面两种方式来设置对象的权限:

  • 在请求体中指定 ACL。

  • 使用请求头部来设置访问权限。

    注意 : 不能同时使用以上两种方式。

请求

  • 请求语法

    • 内容

        PUT /?acl HTTP/1.1
        Host: {BucketName}.{endpoint}
        Date: {date}
        Authorization: {SignatureValue}    
      
    • 描述

        Endpoint:参考与region地域的关系
        SignatureValue:参考签名算法
      
  • 请求参数

  • 非公共请求头

名称 类型 是否必须 描述
x-oss-acl 字符串 用于对象的预定义权限。
默认值:private
有效值:private; public-read;public-read-write
(提示)为用户授予权限的功能,在系统设计中,需要考虑,暂时不用实现,可以参考(x-oss-grant-read、x-oss-grant-write、x-oss-grant-full-control)
备注:当同时在header中和Body中设置了ACL,最后只有header中的会生效。当同时在header中设置了x-oss-acl和x-oss-grant-*时,后者生效。对于大部分用户,使用x-oss-acl在header中设置预设的ACL就可以满足大部分需求

响应

  • 非公共响应头

  • 响应体

示例

  • 请求

      PUT /?acl HTTP/1.1
      Host: oss-example.oss-cn-beijing.inspurcloud.com
      x-oss-acl:public-read;
      Content-Length: 1660
      Date: Fri, 26 Dec 2014 06:34:32 GMT
      Authorization: authorization string    
    
  • 响应

      HTTP/1.1 200 OK
      Date: Fri, 26 Dec 2014 06:34:32 GMT
      x-oss-requestid: dbea4ce4ec23415b9e454ecfa25ec4d9
      Content-Length: 0
      Server:    
    

错误码

错误码 描述 状态码 描述
... ... ... ...

获取桶所在的地域信息

此 GET 操作将使用 location 来返回存储桶空间的所属地域。 用户在 PUT Bucket 请求中使用 LocationConstraint 来设置存储桶空间的所属地域,此API功能仅限Bucket拥有者调用。

请求

  • 请求语法

    • 内容

        GET / ?location HTTP/1.1
        Host: {BucketName}.{endpoint}
        Date: {date}
        Authorization: {SignatureValue}    
      
    • 描述

        Endpoint:参考与region地域的关系
        SignatureValue:参考签名算法
      
  • 请求参数

  • 非公共请求头

  • 请求体

响应

  • 非公共响应头

  • 响应体

名称 类型 描述
LocationConstraint 字符串 指定用户空间被安置的区域。
有效值:BEIJING

示例

  • 请求

      GET / ?location HTTP/1.1
      Host: oss-example.oss-cn-beijing.inspurcloud.com
      Date: Wed, 12 Oct 2009 17:50:00 GMT
      Authorization: authorization string    
    
  • 响应

      <?xml version="1.0" encoding="UTF-8"?>
      <LocationConstraint xmlns="http://s3.amazonaws.com/doc/2006-03-01/">BEIJING</LocationConstraint>    
    

错误码

错误码 描述 状态码 描述
... ... ... ...

关于Object操作

上传对象

此PUT接口可以添加一个Object对象文件到某个存储桶。如果要使用此接口,需要具有该存储桶的 写权限。

请求

  • 请求语法

    • 内容

        PUT /{ObjectKey} HTTP/1.1
        Host: {BucketName}.{endpoint}
        Date: {date}
        Authorization: {SignatureValue}
      
    • 描述

        Endpoint:参考与region地域的关系
        SignatureValue:参考签名算法
      
  • 请求参数

  • 非公共请求头

名称 类型 是否必须 描述
Cache-Control 字符串 告诉所有的缓存机制是否可以缓存及哪种类型。
默认值:None
Content-Disposition 字符串 指定对象的表达信息。
默认值:None
Content-Encoding 字符串 指定文件内容编码格式。
默认值:None
Content-Length 字符串 指明对象的大小,按字节。
默认值:None
Content-MD5 字符串 对消息内容(不包括头部)计算MD5值,获得128比特位数字,然后对该数字进行base64编码,用于对象完整性校验。
默认值:None
Content-Type 字符串 用于描述文件内容MIME格式。
默认值:binary/octet-stream
有效值: MIME types
Expect 字符串 当你使用 100-continue 时,直到收到确认时才会发送请求体。如果头部信息被拒绝,请求体不会被发送
默认值:None
有效值:100-continue
Expires 字符串 对象存在于缓存的有效时间日期。
默认值:None
x-oss-meta- 字符串 用户元数据前缀标识。若某个头部前缀为 x-oss-meta-, 则为用户自定义元数据。
默认值:None
x-oss-storage-class 字符串 设置存储方式。
默认值:None
有效值:STANDARD
x-oss-acl 字符串 定义 Object 的 ACL 属性。用于对象的预定义权限。
默认值:private
有效值:private,public-read-write,public-read;
(提示)为用户授予权限的功能,在系统设计中,需要考虑,暂时不用实现,可以参考(x-oss-grant-read、x-oss-grant-write、x-oss-grant-full-control)
  • 请求体

响应

  • 非公共响应头
名称 类型 描述
ETag 字符串 ETag (entity tag) 在每个 Object 生成的时候被创建,ETag 值是该 Object 内容的uuid,可以用于检查该 Object 内容是否发生变化。
  • 响应体

示例

示例 内容 描述
请求 GET /my-image.jpg HTTP/1.1
Host: oss-example.oss-cn-beijing.inspurcloud.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
Authorization: authorization string
Content-Type: text/plain
Content-Length: 11434
Expect: 100-continue
Authorization: authorization string
[data]
当服务器上文件已存在时,若上传成功,将会导致覆盖。Content-Length是必须的,且不能大于body中的实际数据大小
响应 HTTP/1.1 100 Continue
HTTP/1.1 200 OK
x-oss-requestid:dbea4ce4ec23415b9e454ecfa25ec4d9
Date: Wed, 12 Oct 2009 17:50:00 GMT
ETag: "1b2cf535f27731c974343645a3985328"
Content-Length: 0
Connection: close
Server:

错误码

错误码 描述 状态码 描述
... ... ... ...

下载对象

此接口可以在存储桶中将一个文件(对象)下载至本地。该操作需要请求者对目标对象具有读权限或目标对象对所有人都开放了读权限(公有读)。

请求

  • 请求语法

    • 内容

        GET /{ObjectKey} HTTP/1.1
        Host: {BucketName}.{endpoint}
        Date: {date}
        Authorization: {SignatureValue}    
      
    • 描述

        Endpoint:参考与region地域的关系
        SignatureValue:参考签名算法
      
  • 请求参数

名称 类型 是否必须 描述
response-content-type 字符串 设置响应头部 Content-Type
默认值:None
response-content-language 字符串 设置响应头部 Content-Language
默认值:None
response-expires 字符串 设置响应头部 Expires
默认值:None
response-cache-control 字符串 设置响应头部 Cache-Control
默认值:None
response-content-disposition 字符串 设置响应头部 Content-Disposition
默认值:None
response-content-encoding 字符串 设置响应头部 Content-Encoding
默认值:None

备注:有时也许需要在 GET 响应中返回某一个确定的响应头部值,比如,用户可能需要在 GET 请求中设置响应头部 Content-Disposition 的值。只有当返回200状态码时,设置的header才会生效。

  • 非公共请求头
名称 类型 是否必须 描述
Range 字符串 下载指定 range 字节的 object。
默认值:None
If-Modified-Since 字符串 如果 object 在指定时间后被改变,则返回 object。否则,返回304状态码
默认值:None
If-Unmodified-Since 字符串 如果 object 在指定时间后没有被改变,则返回 object。否则,返回412状态码
默认值:None
If-Match 字符串 如果 object 的 ETag(entity tag)与指定值一致,则返回 object。否则,返回412状态码
默认值:None
If-None-Match 字符串 如果 object 的 ETag(entity tag)与指定值不一致,则返回 object。否则,返回304状态码
默认值:None
  • 请求体

响应

  • 非公共响应头
名称 类型 是否必须 描述
x-oss-meta- * 字符串 如果在PUT Object中使用了用户元数据,格式为前缀 x-oss-meta- 后缀为你自定的字段,那么响应头部会返回它,并不解析。
x-oos-storage-class 枚举字符串 Object 的存储级别
有效值:STANDAR
  • 响应体

示例

  • 请求

      GET /my-image.jpg? ?response-content-type=text%2fplain HTTP/1.1
      Host: oss-example.oss-cn-beijing.inspurcloud.com
      Date: Fri, 26 Dec 2014 06:52:15 GMT
      Authorization: authorization string     
    
  • 响应

      HTTP/1.1 200 OK
      x-oss-request-id: 5a868ca0ebd74bcc8eff1f1a7c9bcd6c
      Date: Fri, 26 Dec 2014 06:48:46 GMT
      Last-Modified: Wed, 12 Oct 2009 17:50:00 GMT
      ETag: "fba9dede5f27731c9771645a39863328"
      Content-Length: 434234
      Content-Type: text/plain
      Connection: close
      x-oss-storage-class: STANDARD
      Server: 
      [object data]     
    

错误码

错误码 描述 状态码 描述
... ... ... ...

删除对象

此接口主要实现删除对象操作(如果存在)。如果不存在,则不做任何操作。

请求

  • 请求语法

    • 内容

        DELETE /{ObjectKey} HTTP/1.1
        Host: {BucketName}.{endpoint}
        Date: {date}
        Authorization: {SignatureValue}    
      
    • 描述

        Endpoint:参考与region地域的关系
        SignatureValue:参考签名算法
      
  • 请求参数

  • 非公共请求头

  • 请求体

响应

  • 非公共响应头

  • 响应体

示例

  • 请求

      DELETE /my-image.jpg HTTP/1.1
      Host: oss-example.oss-cn-beijing.inspurcloud.com
      Date: Fri, 26 Dec 2014 06:52:15 GMT
      Authorization: authorization string
      Content-Type: text/plain
    
  • 响应

      HTTP/1.1 200 OK
      x-oss-request-id: 5a868ca0ebd74bcc8eff1f1a7c9bcd6c
      Date: Wed, 28 Oct 2009 22:32:00 GMT
      Content-Length: 124
      Connection: close
      Server:                              
    

错误码

错误码 描述 状态码 描述
... ... ... ...

批量删除对象

此接口主要实现在指定 Bucket 中批量删除 Object,单次请求最大支持批量删除 1000 个 Object。 删除对象操作(如果存在),如果不存在,则不做任何操作。并提供两种返回模式:详细(verbose)模式和简单(quiet)模式:

  • 详细模式(默认):OSS 返回的消息体中会包含每一个删除 Object 的结果。

  • 简单模式:OSS 返回的消息体中只包含删除过程中出错的 Object结果;如果所有删除都成功的话,则没有消息体。

请求

  • 请求语法

    • 内容

        POST /? delete HTTP/1.1
        Host: {BucketName}.{endpoint}
        Date: {date}
        Content-Length: length
        Content-Type: application/xml
        Content-MD5: MD5
        Authorization: {SignatureValue}    
      
    • 描述

        Endpoint:参考与region地域的关系
        SignatureValue:参考签名算法
      
  • 请求参数

  • 非公共请求头

名称 类型 是否必须 描述
Content-Length 字符串 RFC 2616 中定义的 HTTP 请求内容长度(字节)
默认值:None
Content-MD5 字符串 RFC 1864 中定义的经过 Base64 编码的 128-bit 内容 MD5 校验值。此头部用来校验文件内容是否发生变化
默认值:None
  • 请求体
名称 类型 是否必须 描述
DELETE 容器 描述本次删除的返回结果方式和目标 Object
子节点:Quiet、Object
Quiet 布尔值 布尔值,这个值决定了是否启动 Quiet 模式。值为 true 启动 Quiet 模式,值为 false 则启动 Verbose 模式,默认值为 False
父节点:DELECT
Object 容器 描述每个将要删除的目标 Object 信息
子节点:Object
父节点:DELECT
Key 字符串 目标 Object 文件名称
父节点:Object

响应

  • 非公共响应头

  • 响应体

名称 类型 描述
DeleteResult 容器 本次删除返回结果的方式和目标 Object

Container 节点 Deleted 的内容:

名称 类型 描述
Deleted 容器 说明本次删除的成功 Object 信息父节点: DeleteResult
Key 字符串 Object名称父节点: DeleteResult.Deleted

Container 节点 Error 的内容:

名称 类型 描述
Error 容器 说明本次删除的失败 Object 信息
父节点: DeleteResult
Key 字符串 Object名称
父节点:DeleteResult.Error
Code 字符串 删除失败的错误代码
父节点:DeleteResult.Error
Message 字符串 删除失败的错误信息
父节点:DeleteResult.Error

示例

  • 请求1(简单模式)

      POST /?delete HTTP/1.1
      Host: oss-example.oss-cn-beijing.inspurcloud.com
      Date: Wed, 23 Oct 2016 21:32:00 GMT
      Connection: keep-alive
    
      Accept-Encoding: gzip, deflate
      Accept: */*
      User-Agent: python-requests/2.12.4
      Authorization: sa76972ba599cba25a8a733d2fef
      Content-MD5: yoLiNjQuvB7lu8cEmPafrQ==
      Content-Length: 125
    
      <Delete>
        <Quiet>true</Quiet>
        <Object>
          <Key>aa</Key>
        </Object>
        <Object>
          <Key>aaa</Key>
        </Object>
      </Delete>     
    
  • 响应1

      <DeleteResult/>    
    
  • 请求2(详细模式)

      POST /?delete HTTP/1.1
      Host: oss-example.oss-cn-beijing.inspurcloud.com
      Date: Tue, 22 Aug 2017 12:16:35 GMT
      Connection: keep-alive
      Accept-Encoding: gzip, deflate
      Accept: */*
      User-Agent: python-requests/2.12.4
      Authorization: 8a733d2fef
      Content-MD5: V0XuU8V7aqMYeWyD3BC2nQ==
      Content-Length: 126
    
      <Delete>
        <Quiet>false</Quiet>
        <Object>
          <Key>aa</Key>
        </Object>
        <Object>
          <Key>aaa</Key>
        </Object>
      </Delete>    
    
  • 响应2

      <DeleteResult>
       <Deleted>
        <Key>aa</Key>
       </Deleted>
       <Deleted>
        <Key>aaa</Key>
       </Deleted>
      </DeleteResult>    
    

错误码

错误码 描述 状态码 描述
... ... ... ...

获得对象元信息

此HEAD操作将会在不返回 object 的情况下获取对象的元数据信息。 使用此接口,需要具有对对象的 READ 权限。

请求

  • 请求语法
- **内容**

        HEAD /{ObjectKey} HTTP/1.1
        Host: {BucketName}.{endpoint}
        Date: {date}
        Authorization: {SignatureValue}    

- **描述**

        Endpoint:参考与region地域的关系
        SignatureValue:参考签名算法
  • 请求参数

  • 非公共请求头

名称 类型 是否必须 描述
Range 字符串 下载指定 range 字节的 object。默认值:None
If-Modified-Since 字符串 如果 object 在指定时间后被改变,则返回 object。否则,返回304状态码
默认值:None
If-Unmodified-Since 字符串 如果 object 在指定时间后没有被改变,则返回 object。否则,返回412状态码
默认值:None
If-Match 字符串 如果 object 的 ETag(entity tag)与指定值一致,则返回 object。否则,返回412状态码
默认值:None
If-None-Match 字符串 如果 object 的 ETag(entity tag)与指定值不一致,则返回 object。否则,返回304状态码
默认值:None
  • 请求体

响应

  • 非公共响应头
名称 类型 描述
x-oss-meta- * 字符串 如果在PUT Object中使用了用户元数据,格式为前缀 x-oss-meta- 后缀为你自定的字段,那么响应头部会返回它,并不解析。
x-oss-storage-class 枚举字符串 Object 的存储级别
有效值:STANDAR
  • 响应体

示例

  • 请求

      HEAD /my-image.jpg HTTP/1.1
      Host: oss-example.oss-cn-beijing.inspurcloud.com
      Date: Wed, 28 Oct 2009 22:32:00 GMT
      Authorization: authorization string     
    
  • 响应

      HTTP/1.1 200 OK
      x-oss-request-id: NTk5YzIwYTNfMzFhYzM1MGFfMmNmOWZfZWVhNjQ
      Date: Wed, 28 Oct 2009 22:32:00 GMT
      Last-Modified: Sun, 1 Jan 2006 12:00:00 GMT
      ETag: "fba9dede5f27731c9771645a39863328"
      Content-Length: 434234
      Content-Type: text/plain
      x-oss-storage-class: STANDARD
      Connection: close
      Server:     
    

错误码

错误码 描述 状态码 描述
... ... ... ...

通过表单形式上传对象

此POST操作将使用HTML表单为指定的空间添加一个对象。POST是PUT的另外一种选择,为了方便用户空间可以基于浏览器的上传对象。 参数通过POST以表单域的形式将数据编码封装到消息体传递,而不是PUT方式。用户需要拥有对Bucket的写权限才能添加新的对。

请求

  • 请求语法

    • 内容

        POST /  HTTP/1.1
        Host: {BucketName}.{endpoint}
        User-Agent: browser_data
        Accept: file_types
        Accept-Language: Regions 
        Accept-Encoding: encoding 
        Accept-Charset: character_set
        Keep-Alive: 300 
        Connection: keep-alive 
        Content-Type: form-data; boundary=9431149156168 
        Content-Length: length
      
        --9431149156168 
        Content-Disposition: form-data; name="key"
      
        acl
         --9431149156168 
        Content-Disposition: form-data; name="tagging"
        <Tagging><TagSet><Tag><Key>Tag Name</Key><Value>Tag Value</Value></Tag></TagSet></Tagging> 
        --9431149156168 
        Content-Disposition: form-data; name="success_action_redirect"
      
        success_redirect
        --9431149156168
         Content-Disposition: form-data; name="Content-Type"
      
        content_type 
        --9431149156168 
        Content-Disposition: form-data; name="x-amz-meta-uuid"
      
        uuid 
        --9431149156168 
        Content-Disposition: form-data; name="x-amz-meta-tag"
      
        metadata 
        --9431149156168 Content-Disposition: form-data; name="AccessKeyId"
      
        access-key-id 
        --9431149156168 
        Content-Disposition: form-data; name="Policy"
      
        encoded_policy 
        --9431149156168 
        Content-Disposition: form-data; name="Signature"
      
        signature= 
        --9431149156168 
        Content-Disposition: form-data; name="file"; filename="MyFilename.jpg" 
        Content-Type: image/jpeg
      
        file_content 
        --9431149156168 
        Content-Disposition: form-data; name="submit"
      
        Upload to InspurCloud OSS 
        --9431149156168--    
      
    • 描述

        Endpoint:参考与region地域的关系
        SignatureValue:参考签名算法
      
  • 请求参数

  • 非公共请求头

  • 请求体(表单域)

名称 类型 必须 描述
AccessKeyId 字符串 有条件的 Bucket 拥有者的Access Key Id。
默认值:无
约束条件:当 bucket 非 public-read-write 或者提供了policy表单域时,必须提供该表单域。
acl 字符串 指定访问控制权限,如果指定的访问权限列表无效,则会返回错误。
默认值: private
有效值: private; public-read
Cache-Control
Content-Type
Content-Disposition
Content-Encoding
Expires
字符串 REST 特别头部. 更多信息,请查看PUT Object。
默认值: 无
file 文件或文本内容 文件或文本内容。用户每次只能上传一个文件,且内容必须放到最后一个表单域中。
默认值: 无
key 字符串 ObjectKey。如果用户想要使用文件名作为Key,可以使用${filename} 变量。例如:如果用户想要上传文件local.jpg,需要指明specify /user/betty/${filename},那么键值就会为/user/betty/local.jpg。
默认值: 无.
policy 字符串 有条件的 请求中用于描述获准行为的安全策略。没有安全策略的请求被认为是匿名请求,只能访问公共可写对象。
类型: String
默认值:
无约束条件: 当 bucket 非 public-read-write.必须提供该表单域。
success_action_redirect 字符串 成功上传后客户端的重定向URL。如果用户没有指定success_action_redirect,OSS将会返回空文件类型。 如果OSS无法解析URL地址,那么会无视此表单域。如果上传失败,OSS不会将客户端重定向。
默认值: 无
success_action_status 字符串 返回的状态码,如果没有指定,则依赖于上传的成功状态。允许值为200,,201,204(默认值)。如果是200或204,OSS将返回一个状态为200或204的空文件。如果状态码为201,那么OSS将会返回一个状态码为201的XML文档。如果值无效,或者没有设定,OSS将会返回一个状态码为204的空文档。
默认值: 无
x-oss-storage-class 字符串 设置文件的存储类型。
默认值:无
有效值:STANDARD
约束条件:无
x-oss-meta-* 字符串 用户元数据前缀标识。若某个头部前缀为 x-oss-meta-, 则为用户自定义元数据。
默认值:无
约束条件:无
signature 字符串 有条件的 根据Access Key Secret和policy计算的签名信息,OSS验证该签名信息从而验证该Post请求的合法性。
默认值: 无
约束条件: 当 bucket 非 public-read-write 或者提供了policy表单域时,必须提供该表单域。

响应

  • 非公共响应头
名称 类型 描述
success_action_redirect 字符串 成功上传后客户端的重定向URL。
  • 响应体
名称 类型 描述
PostResponse 容器 保存 POST Object 结果的容器
是否必须:是
Location 字符串 新创建 Object 的 URL。
父节点:PostResponse
Bucket 字符串 Bucket 名称。
父节点:PostResponse
Key 字符串 对象 key 名
父节点:PostResponse
ETag 字符串 ETag (entity tag) 在每个 Object 生成的时候被创建,Post 请求创建的 Object,ETag 值是该 Object 内容的 uuid,可以用于检查该 Object 内容是否发生变化。
父节点:PostResponse

示例

示例 内容 描述
请求 POST / HTTP/1.1
Content-Length: 4
Host:
Date: Wed, 01 Mar 2006 12:00:00 GMT
Authorization: authorization string
Content-Type: text/plain
Expect: the 100-continue HTTP status code
ObjectContent
用户需要对Bucket拥有写权限除
非匿名用户对Bucket有写权限,否则需要在表单域中
提供OSSAccessKeyId、policy和signature三项,具
体构造方法见Post Policy
POST Object时,Content-Type必须为 form-data
policy中规定了表单需要满足
的规则,表单必须满足policy中定义的规则,方可上传成功。policy中必须包
含表单中除OSSAccessKeyId、policy、signature和file
外的所有表单项。
用户可以在表单项中添加以x-oss-meta开头的表单项,
视为添加用户元数据。注意,这些表单项也是需要在
policy中定义的。
当OSS返回403时,应该首先检查表单是否满足policy
响应 HTTP/1.1 100 Continue
HTTP/1.1 200 OK
x-oss-requestid: 0A49CE4060975EAC
Date: Wed, 12 Oct 2009 17:50:00 GMT
ETag: "1b2cf535f27731c974343645a3985328"
Content-Length: 0
Connection: close
Server:

错误码

错误码 描述 状态码 描述
... ... ... ...

获取对象的权限

此GET操作使用 acl 子资源来返回 object 的 ACL(access control list)。只有bucket的所有者拥有调用该接口的权限。

请求

  • 请求语法

    • 内容

        GET /{ObjectKey}?acl HTTP/1.1
        Host: {BucketName}.{endpoint}
        Date: {date}
        Authorization: {SignatureValue}    
      
    • 描述

        Endpoint:参考与region地域的关系
        SignatureValue:参考签名算法
      
  • 请求参数

  • 非公共请求头

  • 请求体

响应

  • 非公共响应头

  • 响应体

名称 类型 描述
AccessControlPolicy 容器 包含了每一个 Grantee 对于某个对象的 ACL 权限设置信息
AccessControlList 容器 包含 Grant,Grantee,Permission 的容器类型:Container
父节点:AccessControlPolicy
Grant 容器 包含被授权者和其权限信息。
父节点:AccessControlPolicy.AccessControlList
Grantee 字符串 被授权者,参考授予权限方式
父节点:AccessControlPolicy.AccessControlList.Grant
Permission 字符串 指明授予被授权者的权限信息(FULL_CONTROL,READ,WRITE)
父节点:AccessControlPolicy.AccessControlList.Grant
Owner 容器 包含bucket拥有者信息(DisplayName,ID)的容器
父节点:AccessControlPolicy
ID 字符串 Bucket拥有者的用户ID,或者是被授权者的ID
父节点:AccessControlPolicy.Owner 或者 AccessControlPolicy.AccessControlList.Grant
DisplayName 字符串 Bucket拥有者的名称
父节点:AccessControlPolicy.Owner

示例

  • 请求

      GET /my-image.jpg?acl HTTP/1.1
      Host: oss-example.oss-cn-beijing.inspurcloud.com
      Date: Fri, 26 Dec 2014 06:34:32 GMT
      Authorization: authorization string     
    
  • 响应

      <AccessControlPolicy>
      <Owner>
      <ID>73410125</ID>
      <DisplayName>123@163.com</DisplayName>
      </Owner>
      <AccessControlList>
      <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
      <ID>73404060</ID>
      <DisplayName>123@163.com </DisplayName>
      </Grantee>
      <Permission>FULL_CONTROL</Permission>
      </Grant>
      </AccessControlList>
      </AccessControlPolicy>:     
    

错误码

错误码 描述 状态码 描述
... ... ... ...

设置对象的权限

此PUT操作为bucket 中的 object设置访问控制权限(ACL)。只有bucket的所有者可以调用该接口。你可以使用下面两种方式来设置对象的权限;

  • 在请求体中指定 ACL。

  • 使用请求头部来设置访问权限。

    注意 : 不能同时使用以上两种方式。

请求

  • 请求语法

    • 内容

        PUT /{ObjectKey}?acl HTTP/1.1
        Host: {BucketName}.{endpoint}
        Date: {date}
        Authorization: {SignatureValue}    
      
    • 描述

        Endpoint:参考与region地域的关系
        SignatureValue:参考签名算法
      
  • 请求参数

  • 非公共请求头

名称 类型 是否必须 描述
x-oss-acl 字符串 用于对象的预定义权限。
默认值:private
有效值:private; public-read; public-read-write
(提示)为用户授予权限的功能,在系统设计中,需要考虑,暂时不用实现,
可以参考(x-oss-grant-read、x-oss-grant-write、x-oss-grant-full-control)
备注:当同时在header中和Body中设置了ACL,最后只有header中的
会生效。当同时在header中设置了x-oss-acl和x-oss-grant-*时,后者生
效。对于大部分用户,使用x-oss-acl在header中设置预设的ACL就可以
满足大部分需求

响应

  • 非公共响应头

  • 响应体

示例

  • 请求

      PUT /my-image.jpg ?acl HTTP/1.1
      Host: oss-example.oss-cn-beijing.inspurcloud.com
      x-oss-acl:public-read;
      Content-Length: 1660
      Date: Fri, 26 Dec 2014 06:34:32 GMT
      Authorization: authorization string     
    
  • 响应

      HTTP/1.1 200 OK
      Date: Fri, 26 Dec 2014 06:34:32 GMT
      x-oss-request-id: dbea4ce4ec23415b9e454ecfa25ec4d9
      Content-Length: 0
      Server:     
    

错误码

错误码 描述 状态码 描述
... ... ... ...