对象存储API文档 - 滴滴云 - 滴滴云客户支持服务平台

快速开始

滴滴云S3 API提供标准的轻量级无状态HTTPS接口，支持用户对数据的全方位管理。如果您没有使用对象存储相关产品经验，建议您先了解一些概念和名词解释。

一个标准使用API的快速开始流程如下：

接口概览

关于Service的操作

API	描述
Get Service	获取用户所有的Bucket

关于Bucket的操作

API	描述
Put Bucket	创建Bucket
Put Bucket Acl	设置Bucket访问权限
Delete Bucket	删除Bucket
Head Bucket	判断Bucket是否存在和用户是否有权限操作Bucket
Get Bucket（List Objects）Version 1	获取Bucket（文件列表）版本1
Get Bucket（List Objects）Version 2	获取Bucket（文件列表）版本2

关于Object的操作

API	描述
Put Object	上传文件
Put Object Acl	设置Object访问权限
Post Object	使用HTML表单上传文件
Delete Object	删除文件
Delete Multiple Object	同时删除多个文件
Head Object	获取Object的meta信息
Get Object	下载文件

请求签名

待补充

公共请求头部

我们约定了公共请求头部，下表描述了公共请求头部的详细定义：

名称	描述	是否必须
Authorization	用于验证用户身份所需要的信息	否
Content-Length	RFC2616定义的HTTP请求内容长度	否
Content-Type	RFC2616定义的HTTP请求内容类型	否
Content-MD5	RFC1864定义的HTTP请求内容base64编码的128位MD5摘要	否
Date	HTTP1.1协议中规定的GMT时间，例如：Wed, 01 Mar 2006 12:00:00 GMT。指定Authorization时，必须指定x-didi-date或 Date。	否
Expect	当使用100-continue时，客户端在收到确认之前不会发送请求体，如果服务端根据header的内容拒绝了该请求，则客户端不会发送请求体。有效值：100-continue。	否
Host	访问host的值，对于路径样式的请求，值是s3.didiyunapi.com，对于虚拟样式的请求，值是`yourBucket`.s3.didiyunapi.com。	是
x-didi-content-sha256	当使用签名版本4来验证请求时，x-didi-content-sha256提供了请求内容的hash值。	否
x-didi-date	同Date。指定Authorization时，必须指定x-didi-date或者Date，如果同时指定x-didi-date和Date，则优先考虑x-didi-date。	否

公共返回头部

S3的接口中使用了一些公共响应头部。下表描述了公共响应头部的详细定义

名称	描述
Content-Length	HTTP响应内容的长度。类型:字符串默认值:无
Content-Type	HTTP 响应内容的类型。类型:字符串默认值:无
Connection	指定到服务器的链接状态。类型:枚举有效值:open \| close 默认值:无
Date	S3返回的日期和时间,例如: Wed, 01 Mar 2006 12:00:00 GMT. 类型:字符串默认值:无
ETag	ETag是一个文件的哈希值,在文件生成的时候创建，用来检查文件内容是否发生变化。 1. 文件通过PUT Object,POST Object创建的，ETag是文件的MD5 2. 文件通过分片上传创建的，ETag不是文件的MD5 类型:字符串
Server	生成响应的服务器类型:字符串默认值: DSS
x-didi-delete-marker	文件是否被删除。类型:布尔有效值:true \| false 默认值: false
x-didi-version-id	文件的版本，如果启用版本管理，S3会给上传到Bucket的文件一个随机字符串，字符串复合URL命名规则，使用UTF-8编码
x-didi-request-id	由S3创建的唯一标识请求的值

错误码

当用户访问s3服务出现错误时，s3会返回给用户相应的错误码和错误信息。

错误响应格式

当用户访问s3服务出现错误时，会返回给用户一个3xx、4xx或者5xx的HTTP状态码以及一个application/xml格式的响应体。响应体格式如下：

 <?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>NoSuchKey</Code>
  <Message>The resource you requested does not exist</Message>
  <Resource>/mybucket/myfoto.jpg</Resource> 
  <RequestId>4442587FB7D0A2F9</RequestId>
</Error>

主要包含以下几种元素：

l Code：错误码

l Message：详细的错误信息

l Resource：请求的资源路径

l RequestId：用于标识此次请求的Id

错误码列表

错误码	描述	HTTP状态码
AccessDenied	拒绝访问	403
BadDigest	Content-MD5不匹配	400
BucketAlreadyExists	Bucket已经存在	409
BucketAlreadyOwnedByYou	用户已经创建了该Bucket	409
BucketNotEmpty	Bucket非空	409
EntityTooSmall	上传的文件大小小于允许的最小Object大小	400
EntityTooLarge	上传的文件大小超过允许的最大Object大小	400
IncompleteBody	请求体大小和Content-Length描述的不符	400
InternalError	服务器内部错误	500
InvalidAccessKeyId	提供的access key id不存在	403
InvalidArgument	无效的参数	400
InvalidBucketName	无效的Bucket	400
InvalidDigest	无效的Content-MD5	400
InvalidObjectState	针对目前状态的Object，该操作非法	403
InvalidPart	无效的part，请求的part至少有一个不存在	400
InvalidPartOrder	无效的part顺序，part列表需按照part number升序排列	400
InvalidRange	无效的range	416
InvalidRequest	不支持的签名算法，	400
InvalidRequest	缺少Credential字段	400
MalformedPOSTRequest	Post请求的body体格式非法	400
MalformedXML	请求的XML格式非法	400
MetadataTooLarge	Metadata请求头域超过了允许的最大metadata大小	400
MethodNotAllowed	请求资源的方法不允许	405
MissingContentLength	请求缺少Content-Length头域	411
MissingRequestBodyError	请求体为空	400
NoSuchBucket	请求Bucket不存在	404
NoSuchKey	请求Key不存在	404
NoSuchUpload	指定的multipart upload不存在	404
NotImplemented	请求的header还未实现	501
PreconditionFailed	指定的前提条件至少有一个不成立	412
RequestTimeTooSkewed	请求时间和服务器时间差异太大	403
SignatureDoesNotMatch	计算的签名和提供的签名不一致	403
TooManyBuckets	创建的Bucket数目超过了允许的	400
InvalidContentType	无效的Content-Type	400
InvalidObjectName	无效的Object名称	400
MissingContentMD5	请求缺少Content-MD5头域	400
InvalidRegion	Region不匹配	400
AuthorizationQueryParametersError	无效的服务，Authorization头域中的Credential字段中的服务应该为s3	400
AuthorizationQueryParametersError	无效的终端，Authorization头域中的Credential字段中的终端非法	400
AuthorizationQueryParametersError	请求头域中X-didi-Date格式不正确，必须是ISO8601 Long 格式	400
AuthorizationQueryParametersError	无效的时间格式，Authorization头域中的Credential字段中的时间格式应该为yyyymmdd	400
AuthorizationQueryParametersError	请求头域中X-didi-Expires 应该为一个数字	400
AuthorizationQueryParametersError	请求头域中X-didi-Expires 应该非负	400
AuthorizationQueryParametersError	请求头域中X-didi-Algorithm非法。	400
AuthorizationQueryParametersError	预签名版本4中字段非法，只能是X-didi-Algorithm, X-didi-Credential, X-didi-Signature, X-didi-Date, X-didi-SignedHeader和X-didi-Expires	400
InvalidArgument	请求头域中缺少SignedHeaders	400
InvalidArgument	请求头域中缺少Authorization字段或者Authorizarion字段为空	400
MalformedDate	请求头域中date格式不正确，可以是ISO8601, RFC1123 或者 RFC1123Z	400
RequsetTooFrequently	请求过于频繁	400
InvalidACL	无效的ACL	400
XdidiContentSHA256Mismatch	请求头域中的x-didi-content-sha256和实际不符	400

Service接口

GetService

GetService用于获取用户的Bucket列表，其请求语法，响应元素及实例如下：

1. 请求语法：

GET / HTTP/1.1
Host: s3.didiyunapi.com
Date: date
Authorization: authorization string

l 请求参数

无

l 请求头

公共请求头部

l 请求体

无

2. 响应语法

l 响应头

公共返回头部

l 响应体

名称	描述
Bucket	保存Bucket信息的容器类型：容器子节点：Name，CreationDate 父节点：ListAllMyBucketsResult.Buckets
Buckets	保存一个或多个Bucket信息的容器类型：容器子节点：Bucket 父节点：ListAllMyBucketsResult
CreationDate	Bucket创建的日期类型：时间（格式：yyyy-mm-ddThh:mm:ss.timezone ，例如：2009-02-03T16:45:09.000Z ）父节点：ListAllMyBucketsResult.Buckets.Bucket
DisplayName	Bucket拥有者的名称类型：字符串父节点：ListAllMyBucketsResult.Owner
ID	Bucket拥有者的ID 类型：字符串父节点：ListAllMyBucketsResult.Owner
ListAllMyBucketsResult	保存响应的容器类型：容器子节点：Owner、Buckets 父节点：无
Name	Bucket的名称类型：字符串父节点：ListAllMyBucketsResult.Buckets.Bucket
Owner	保存Bucket拥有者信息的容器类型：容器父节点：ListAllMyBucketsResult

3. 请求示例：

GET / HTTP/1.1
Host: s3.didiyunapi.com
Date: Wed, 21 Aug 2012 23:09:55 GMT
Authorization: authorization string

4. 响应示例：

content-length: 348
content-type: application/xml
date: Wed, 03 Jan 2018 10:55:12 GMT
server: DSS
x-didi-request-id: c46b6406-67c4-4159-b347-dbfc319ddfbc
 
<?xml version="1.0" encoding="UTF-8"?>
<ListAllMyBucketsResult>
  <Owner>
    <ID>bcaf1ffd86f461ca5fb16fd081034f</ID>
    <DisplayName>webfile</DisplayName>
  </Owner>
  <Buckets>
    <Bucket>
      <Name>quotes</Name>
      <CreationDate>2006-02-03T16:45:09.000Z</CreationDate>
    </Bucket>
    <Bucket>
      <Name>samples</Name>
      <CreationDate>2006-02-03T16:41:58.000Z</CreationDate>
    </Bucket>
  </Buckets>
</ListAllMyBucketsResult>

Bucket接口

PutBucket

PutBucket用于创建Bucket（不支持匿名访问）。创建的Bucket所在的Region和发送请求的Endpoint所对应的Region一致。Bucket所在的数据中心确定后，该Bucket下的所有Object将一直存放在对应的地区。

1. 请求语法：

PUT / HTTP/1.1
Host: yourBucket.s3.didiyunapi.com
Content-Length: 109
Date: Wed, 01 Mar  2006 12:00:00 GMT
Authorization: authorization string 
 
<CreateBucketConfiguration> 
    <LocationConstraint>gz</LocationConstraint> 
</CreateBucketConfiguration>

l 请求参数

无

l 请求头

除了公共请求头部，还可以使用下列字段。

字段	描述	是否必须
x-didi-acl	通过指定的ACL值设置Bucket的ACL 类型: 字符串有效值: private \| public-read \| public-read-write 默认值: private	否

使用Put请求中的 x-didi-acl 头来设置Bucket访问权限。目前Bucket有三种访问权限：public-read-write，public-read和private。

l 请求体

字段	描述	是否必须
CreateBucketConfiguration	Bucket配置的字段描述类型: xml容器	否
LocationConstraint	指定Bucket创建的Region 类型: 枚举有效值: gz 默认值: gz	否

2. 响应语法：

l 响应头

公共返回头部

l 响应体

无

3. 请求示例：

PUT / HTTP/1.1
Host: yourBucket.s3.didiyunapi.com
Content-Length: 109
Date: Wed, 01 Mar  2006 12:00:00 GMT
Authorization: authorization string 
<CreateBucketConfiguration>    
    <LocationConstraint>gz</LocationConstraint>
</CreateBucketConfiguration>

4. 响应示例：

HTTP/1.1 200 OK
x-didi-request-id: 464e3128-6d17-4b02-bbb1-7ffcd7fd3a57
Date: Wed, 01 Mar 2017 12:00:00 GMT
Location: /gz
Content-Length: 0
Server: DSS

HeadBucket

确认Bucket是否存在和是否有权限访问此Bucket，如果Bucket存在并且有权限访问，则返回200，否则返回404(Not Found)或者403(Forbidden)

1. 请求语法：

HEAD / HTTP/1.1    
Host: yourBucket.s3.didiyunapi.com
Date: Wed, 01 Mar 2017 12:00:00 GMT
Authorization: authorization string

l 请求参数

无

l 请求头

公共请求头部

l 请求体

无

2. 响应语法：

l 响应头

公共返回头部

l 响应体

无

3. 请求示例：

HEAD / HTTP/1.1    
Host: yourBucket.s3.didiyunapi.com
Date: Wed, 01 Mar 2017 12:00:00 GMT
Authorization: authorization string

4. 响应示例：

HTTP/1.1 200 OK
x-didi-request-id: 3235bbe1-956e-46df-8c6b-1a8c919c77bb
Date: Fri, 10 2012 21:34:56 GMT
Server: DSS

DeleteBucket

删除某个Bucket，Bucket中的所有文件必须全部删除后，然后才能删除桶本身

1. 请求语法：

DELETE / HTTP/1.1
Host: yourBucket.s3.didiyunapi.com
Date: Wed, 01 Mar 2017 12:00:00 GMT
Authorization: authorization string

l 请求参数

无

l 请求头

公共请求头部

l 请求体

无

2. 响应语法：

l 响应头

公共返回头部

l 响应体

无

3. 请求示例：

DELETE / HTTP/1.1
Host: yourBucket.s3.didiyunapi.com
Date: Wed, 01 Mar 2017 12:00:00 GMT
Authorization: authorization string

4. 响应示例：

HTTP/1.1 204 No Content
x-didi-request-id: 32FE2CEB32F5EE25
Date: Wed, 01 Mar  2006 12:00:00 GMT
Server: DSS

PutBucketAcl

PutBucketACL接口用于修改Bucket访问权限。目前Bucket有三种访问权限：public-read-write，public-read和privatePutBucketACL操作通过Put请求中的“x-didi-acl”头来设置这个操作,需要拥有WRITE_ACP权限。如果操作成功，则返回200；否则返回相应的错误码和提示信息。

1. 请求语法：

PUT /?acl HTTP/1.1
x-didi-acl: Permission
Host: yourBucket.s3.didiyunapi.com
Date: Wed, 01 Mar 2017 12:00:00 GMT
Authorization: authorization string

l 请求参数

无

l 请求头

除了使用公共请求头部，还可以使用下列字段。

字段	描述	是否必须
x-didi-acl	通过指定的ACL值设置Bucket的ACL 类型: 字符串有效值: private \| public-read \| public-read-write 默认值: private	否

l 请求体

无

2. 响应语法：

l 响应头

公共返回头部

l 响应体

无

3. 请求示例：

PUT /?acl HTTP/1.1
x-didi-acl: Permission
Host: yourBucket.s3.didiyunapi.com
Date: Wed, 01 Mar 2017 12:00:00 GMT
Authorization: authorization string

4. 响应示例：

HTTP/1.1 200 OK
x-didi-request-id: 32FE2CEB32F5EE25
Date: Wed, 01 Mar  2006 12:00:00 GMT
Content-Length: 0
Server: DSS

Get Bucket（List Objects）Version 2

Get Bucket操作用来返回Bucket里一个或者多个(最多1000)Object的信息。您可以使用请求参数作为选择条件来返回存储桶中对象的子集。

1. 请求语法：

GET /?list-type=2 HTTP/1.1
Host: yourBucket.s3.didiyunapi.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
Authorization: authorization string
Content-Type: text/plain

l 请求参数

参数	描述	是否必须
delimiter	是一个用于对Object名字进行分组的字符。所有名字包含指定的前缀且第一次出现delimiter字符之间的object作为一组元素——CommonPrefixes。数据类型：字符串默认值：无	否
max-keys	限定此次返回object的最大数，如果不设定，默认为100，max-keys取值不能大于1000。数据类型：字符串默认值：100	否
prefix	限定返回的object key必须以prefix作为前缀。注意使用prefix查询时，返回的key中仍会包含prefix。类型：字符串默认值：无	否
list-type	第二版本API必需字段类型:字符串默认值:必须是2	是
continuation-token	当DSS的返回结果被截断，结果会包含NextContinuationToken字段,下一次请求时continuation-token使用NextContinuationToken的值获取后续结果类型:字符串默认值:无	否
fetch-owner	默认情况下，API不会在响应中返回Owner信息。如果您希望响应中的所有者信息，则可以将该参数的值指定为true。类型:字符串默认值:false	否
start-after	如果你希望获取特定的object之后的key,可以指定这个值，如果同时指定了 continuation-token，DSS会忽略start-after字段类型:字符串默认值:无	否

l 请求头

公共请求头部

l 请求体

无

2. 响应语法：

l 响应头

公共返回头部

l 响应体

名称	描述
Contents	保存每个返回Object meta的容器。类型：xml容器父节点：ListBucketResult
CommonPrefixes	如果请求中指定了delimiter参数，则在DSS返回的响应中包含CommonPrefixes元素。该元素标明那些以delimiter结尾，并有共同前缀的object名称的集合。类型：字符串父节点：ListBucketResult
Delimiter	对Object名字进行分组的字符, 所有名字包含指定的前缀且第一次出现delimiter字符之间的object作为一组元素——CommonPrefixes。类型：字符串父节点：ListBucketResult
DisplayName	Object 拥有者的名字。类型：字符串父节点：ListBucketResult.Contents.Owner
ETag	ETag是文件的MD5值，可以用来检测文件是否发生变化类型:字符串父节点: ListBucketResult.Contents
ID	Object拥有者的ID 类型:字符串父节点: ListBucketResult.Contents.Owner
IsTruncated	指定是否返回所有结果。true代表没有返回了所有结果,false代表已经返回了所有结果
Key	Object的key 类型:字符串父节点: ListBucketResult.Contents
LastModified	Object的最后修改时间类型: 字符串父节点: ListBucketResult.Contents
MaxKeys	返回结果的最大条数类型:字符串父节点: ListBucketResult
Name	Bucket的名称类型: 字符串父节点: ListBucketResult
Owner	Bucker的拥有者类型: 字符串子节点: DisplayName,ID 父节点: ListBucketResult.Contents \| CommonPrefixes
Prefix	本次查询的指定前缀类型: 字符串父节点: ListBucketResult
Size	Object的字节数类型: 字符串父节点: ListBucketResult.Contents
ContinuationToken	如果请求携带了continuation-token，则返回时会包含这个字段类型: 字符串父节点: ListBucketResult
KeyCount	返回结果的数目,数目小于等于MaxKeys的值类型: 字符串父节点: ListBucketResult
NextContinuationToken	如果结果被截断,你可以在下一次请求时,把这个值应用于continuation-token字段,来查询后续结果类型: 字符串父节点: ListBucketResult
StartAfter	如果请求携带了start-after，则返回时会包含这个字段类型: 字符串父节点: ListBucketResult

3. 请求示例：

GET /?list-type=2 HTTP/1.1
Host: yourBucket.s3.didiyunapi.com
x-didi-date: 20160430T233541Z
Authorization: authorization string
Content-Type: text/plain

使用max-keys, prefix, and start-after参数请求

GET /?list-type=2&max-keys=3&prefix=E&start-after=ExampleGuide.pdf HTTP/1.1
Host: yourBucket.s3.didiyunapi.com
x-didi-date: 20160430T232933Z
Authorization: authorization string

使用prefix和delimiter参数请求

GET /?list-type=2&delimiter=/ HTTP/1.1
Host: yourBucket.s3.didiyunapi.com
x-didi-date: 20160430T235931Z
Authorization: authorization string

4. 响应示例：

HTTP/1.1 200 OK
x-didi-request-id: 3B3C7C725673C630
Date: Wed, 01 Mar  2006 12:00:00 GMT
Content-Type: application/xml
Content-Length: 302
Server: DSS

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.didiyunapi.com/doc/2006-03-01/">
    <Name>bucket</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>
        <Owner>
            <ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
            <DisplayName>test@didiyun.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>
         <Owner>
        <ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
            <DisplayName>test@didiyun.com</DisplayName>
        </Owner>
    </Contents>
</ListBucketResult>

 <?xml version="1.0" encoding="UTF-8"?><ListBucketResult xmlns="http://s3.didiyunapi.com/doc/">
     <Name>bucket</Name>    
     <Prefix/>    
     <KeyCount>205</KeyCount>    
     <MaxKeys>1000</MaxKeys>    
     <IsTruncated>false</IsTruncated>    
     <Contents>        
         <Key>my-image.jpg</Key>        
         <LastModified>2009-10-12T17:50:30.000Z</LastModified>            <ETag>&quot;fba9dede5f27731c9771645a39863328;</ETag>
         <Size>434234</Size>        
         <StorageClass>STANDARD</StorageClass>    
     </Contents>    
     <Contents>       
         ...    
     </Contents>
         ...
</ListBucketResult>

HTTP/1.1 200 OK
x-didi-request-id: 3B3C7C725673C630
Date: Sat, 30 Apr 2016 23:29:37 GMT
Content-Type: application/xml
Content-Length: length
Connection: close
Server: DSS

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns=" 
  <Name>quotes</Name>
  <Prefix>E</Prefix>  
  <StartAfter>ExampleGuide.pdf</StartAfter>  
  <KeyCount>1</KeyCount>  
  <MaxKeys>3</MaxKeys>  
  <IsTruncated>false</IsTruncated>  
  <Contents>    
      <Key>ExampleObject.txt</Key>    
      <LastModified>2013-09-17T18:07:53.000Z</LastModified>    
      <ETag>&quot;599bab3ed2c697f1d26842727561fd94&</ETag>    
      <Size>857</Size>  
  </Contents>
 </ListBucketResult> 
 
<ListBucketResult xmlns="http://s3.didiyunapi.com/doc/2006-03-01/">  
     <Name>example-bucket</Name>  
     <Prefix></Prefix>  
     <KeyCount>2</KeyCount>  
     <MaxKeys>1000</MaxKeys>  
     <Delimiter>/</Delimiter>  
     <IsTruncated>false</IsTruncated>  
     <Contents>    
         <Key>sample.jpg</Key>    
         <LastModified>2011-02-26T01:56:20.000Z</LastModified>    
         <ETag>&quot;bf1d737a4d46a19f3bced6905cc8b902</ETag>    
         <Size>142863</Size>  
     </Contents>  
     <CommonPrefixes>    
         <Prefix>photos/</Prefix>  
     </CommonPrefixes>
</ListBucketResult

Get Bucket（List Objects）Version 1

这个API已经被修改，建议使用新版本，为了兼容，我们会支持这个版本

1. 请求语法：

GET / HTTP/1.1
Host: yourBucket.s3.didiyunapi.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
Authorization: authorization string
Content-Type: text/plain

l 请求参数

参数	描述	是否必须
delimiter	是一个用于对Object名字进行分组的字符。所有名字包含指定的前缀且第一次出现delimiter字符之间的object作为一组元素——CommonPrefixes。数据类型：字符串默认值：无	否
marker	设定结果从marker之后按字母排序的第一个开始返回。数据类型：字符串默认值：无	否
max-keys	限定此次返回object的最大数，如果不设定，默认为100，max-keys取值不能大于1000。数据类型：字符串默认值：100	否
prefix	限定返回的object key必须以prefix作为前缀。注意使用prefix查询时，返回的key中仍会包含prefix。数据类型：字符串默认值：无	否

l 请求头

公共请求头部

l 请求体

无

2. 响应语法：

l 响应头

公共返回头部

l 响应体

名称	描述
Contents	保存每个返回Object meta的容器。类型：xml容器父节点：ListBucketResult
CommonPrefixes	如果请求中指定了delimiter参数，则在DSS返回的响应中包含CommonPrefixes元素。该元素标明那些以delimiter结尾，并有共同前缀的object名称的集合。类型：字符串父节点：ListBucketResult
Delimiter	对Object名字进行分组的字符, 所有名字包含指定的前缀且第一次出现delimiter字符之间的object作为一组元素——CommonPrefixes。类型：字符串父节点：ListBucketResult
DisplayName	Object 拥有者的名字。类型：字符串父节点：ListBucketResult.Contents.Owner
ETag	ETag是文件的MD5值，可以用来检测文件是否发生变化类型:字符串父节点: ListBucketResult.Contents
ID	Object拥有者的ID 类型:字符串父节点: ListBucketResult.Contents.Owner
IsTruncated	指定是否返回所有结果。true代表没有返回了所有结果,false代表已经返回了所有结果
Key	Object的key 类型:字符串父节点: ListBucketResult.Contents
LastModified	Object的最后修改时间类型: 字符串父节点: ListBucketResult.Contents
Marker	标明这一次GetBucket(List Objects)的起始位置类型: 字符串父节点: ListBucketResult
MaxKeys	返回结果的最大条数类型:字符串父节点: ListBucketResult
Name	Bucket的名称类型: 字符串父节点: ListBucketResult
NextMarker	当返回的结果被截断的时候,可以使用这个值作为下一次请求的marker来获取后续的结果
Owner	Bucker的拥有者类型: 字符串子节点: DisplayName,ID 父节点: ListBucketResult.Contents \| CommonPrefixes
Prefix	本次查询的指定前缀类型: 字符串父节点: ListBucketResult
Size	Object的字节数类型: 字符串父节点: ListBucketResult.Contents

3. 请求示例：

GET / HTTP/1.1
Host: yourBucket.s3.didiyunapi.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
Authorization: authorization string
Content-Type: text/plain

4. 响应示例：

HTTP/1.1 200 OK
x-didi-request-id: 3B3C7C725673C630
Date: Wed, 01 Mar  2006 12:00:00 GMT
Content-Type: application/xml
Content-Length: 302
Server: DSS
 
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.didiyunapi.com/doc/2006-03-01/">
    <Name>bucket</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>
        <Owner>
            <ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
            <DisplayName>test@didiyun.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>
         <Owner>
        <ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
            <DisplayName>test@didiyun.com</DisplayName>
        </Owner>
    </Contents>
</ListBucketResult>

Object 接口

PutObject

PutObejct用于上传文件，上传时需指定上传Bucket。

1. 请求语法：

PUT /ObjectName HTTP/1.1
Host: yourBucket.s3.didiyunapi.com
Date: date
Authorization: authorization string

l 请求参数

无

l 请求头

除了公共请求头部，还可以使用下列字段。

名称	描述	是否必须
Cache-Control	指定请求响应的缓存行为类型：字符串默认值：无	否
Content-Disposition	指定Object被下载时的名称类型：字符串默认值：无	否
Content-Encoding	指定Object被下载时的编码格式类型：字符串默认值：无	否
Content-Length	消息体的大小，以字节为单位类型：字符串默认值：无	是
Expires	Object过期时间类型：字符串默认值：无	否
x-didi-meta-*	以x-didi-meta-为前缀的header称为用户自定义header，用户自定义header限制2KB大小，用户自定义header是key-value对的集合，每个key和value的UTF-8编码的字符总数作为用户自定义header的大小，服务端不会校验用户自定义header。类型：字符串默认值：无	否
x-didi-acl	Object的访问权限类型：字符串默认值：Private 有效值：private \| public-read \| public-read-｜inherited 其中： private是默认值，代表对该文件的读写操作需要是创建者（控制台）或调用API时持有账号下API密钥的请求； public-read代表对文件的写操作需要是创建者（控制台）或调用API时持有账号下API密钥的请求；对文件的读操作不需要经过API密钥的校验； public-read-write代表对文件的读写操作不需要经过API密钥的校验，风险较高，建议谨慎操作； inherited代表文件权限继承于Bucket的权限；	否

l 请求体

文件字节流

2. 响应语法：

l 响应头

公共返回头部

l 响应体

无

3. 请求示例：

PUT /exampleobject HTTP/1.1
Host: yourBucket.s3.didiyunapi.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
Authorization: authorization string
Content-Type: text/plain
Content-Length: 11434
[11434 bytes of object data]

4. 响应示例：

HTTP/1.1 200 OK
x-didi-request-id: 318BC8BC148832E5
Date: Wed, 28 Oct 2009 22:32:00 GMT
Content-Length: 0
Content-Type: text/plain; charset=utf-8
Server: DSS
Etag: 7999e7b5aa948bf41380bf5f8593c68a

PutObjectACL

PutObejctACL用于设置Object访问权限，目前Object有四种访问权限：private、public-read、public-read-write和inherited。Put Object ACL通过PUT请求的x-didi-acl头域来设置。

1. 请求语法：

PUT /ObjectName?acl HTTP/1.1
Host: yourBucket.s3.didiyunapi.com
Date: date
Authorization: authorization string
x-didi-acl: acl

l 请求参数

无

l 请求头

除了公共请求头部，还可以使用下列字段。

名称

描述

是否必须

x-didi-acl

Object的访问权限

类型：字符串

默认值：private

有效值：private | public-read | public-read-write｜inherited

其中：

private是默认值，代表对该文件的读写操作需要是创建者（控制台）或调用API时持有账号下API密钥的请求；

public-read代表对文件的写操作需要是创建者（控制台）或调用API时持有账号下API密钥的请求；对文件的读操作不需要经过API密钥的校验；

public-read-write代表对文件的读写操作不需要经过API密钥的校验，风险较高，建议谨慎操作；

inherited代表文件权限继承于Bucket的权限；

否

l 请求体

无

2. 响应语法：

l 响应头

公共返回头部

l 响应体

无

3. 请求示例：

PUT /exampleobject?acl HTTP/1.1
Host: yourBucket.s3.didiyunapi.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: authorization string
x-didi-acl: private

4. 响应示例：

HTTP/1.1 200 OK
access-control-allow-origin: *
x-didi-request-id: 318BC8BC148832E5
Date: Wed, 28 Oct 2009 22:32:00 GMT
Content-Length: 0
Content-Type: text/plain; charset=utf-8
Server: DSS

DeleteObject

DeleteObject用于删除文件。

1. 请求语法：

DELETE /ObjectName HTTP/1.1
Host: yourBucket.s3.didiyunapi.com
Date: date
Authorization: authorization string

l 请求参数

无

l 请求头

公共请求头部

l 请求体

无

2. 响应语法：

l 响应头

公共返回头部

l 响应体

无

3. 请求示例：

DELETE /exampleobject HTTP/1.1
Host: yourBucket.s3.didiyunapi.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
Authorization: authorization string

4. 响应示例：

HTTP/1.1 204 NoContent
x-didi-request-id: 0A49CE4060975EAC
x-didi-delete-marker: true
Date: Wed, 12 Oct 2009 17:50:00 GMT
Server: DSS

DeleteMultipleObjects

DeleteMultipleObjects用于支持用户通过一个HTTP请求删除同一个Bucket的多个Object，并提供两种返回模式：详细（verbose）模式和简单（quiet）模式。

l 详细模式：返回消息体中包含每一个Object删除的结果。

l 简单模式：返回消息体中只包含删除失败的Object，如果所有Object都删除成功的话，则没有消息体。

1. 请求语法：

POST /?delete HTTP/1.1
Host: yourBucket.s3.didiyunapi.com
Date: date
Authorization: authorization string
Content-Length: Size
Content-MD5: MD5

<?xml version="1.0" encoding="UTF-8"?>
    <Delete>    
    <Quiet>true</Quiet>    
        <Object>
              <Key>Key</Key>    
        </Object>    
        <Object>         
            <Key>Key</Key>    
        </Object>    
        ...
</Delete>

l 请求参数

无

l 请求头

除了使用公共请求头部，还可以使用下列字段。

名称

描述

是否必须

Content-MD5

根据RFC 1864，消息内容（不包括头部）base64编码的128位MD5摘要。用作消息完整性检查，以验证数据和发送时的数据一致。

类型：字符串

默认值：无

是

Content-Length

消息内容的长度

类型：字符串

默认值：无

是

l 请求体

名称	描述	必须
Delete	保存请求的容器类型：容器子节点：一个或者多个Object和一个可选的Quiet 父节点：无	是
Quiet	是否开启简单模式类型：布尔默认值：false 有效值：true \| false 父节点：Delete	否
Object	保存一个Object信息的容器类型：容器子节点：Key和VersionId 父节点：Delete	是
Key	被删除Object的名字类型：字符串父节点：Object	是

1. 响应语法：

l 响应头

公共返回头部

l 响应体

名称	描述
DeleteResult	保存请求结果的容器类型：容器子节点：Deleted、Error 父节点：无
Deleted	保存被成功删除的Object的容器类型：容器子节点：Key、VersionId 父节点：DeleteResult
Key	执行删除操作的Object名字类型：字符串父节点：Deleted或者Error
VersionId	被删除Object的版本Id 类型：字符串父节点：Deleted或者Error
DeleteMarker	DeleteMarker为true表明创建了删除标记类型：布尔父节点：Deleted
DeleteMarkerVersionId	被删除Object的版本Id 类型：字符串父节点：Deleted
Error	保存删除失败信息的人容器类型：容器子节点：Key, VersionId, Code, Message 父节点：DeleteResult
Code	删除Object失败的状态码类型：字符串有效值：InternalError 父节点：Error
Message	删除Object失败的详情类型：字符串父节点Error

2. 请求示例：

POST /?delete HTTP/1.1
Host: yourBucket.s3.didiyunapi.com
x-didi-date: Wed, 30 Nov 2011 03:39:05 GMT
Content-MD5: p5/WA/oEr30qrEEl21PAqw==
Authorization: authorization string
Content-Length: 125

<Delete>  
    <Object>    
        <Key>sample1.txt</Key>  
    </Object>  
    <Object>    
        <Key>sample2.txt</Key>  
    </Object>
</Delete>

3. 响应示例：

HTTP/1.1 200 OK
x-didi-request-id: A437B3B641629AEE
Date: Fri, 02 Dec 2011 01:53:42 GMT
Content-Type: application/xml
Server: DSS
Content-Length: 251 

<?xml version="1.0" encoding="UTF-8"?>
<DeleteResult>  
    <Deleted>    
        <Key>sample1.txt</Key>  
    </Deleted>  
    <Error>    
        <Key>sample2.txt</Key>    
        <Code>AccessDenied</Code>    
        <Message>Access Denied</Message>  
    </Error>
</DeleteResult>

HeadObject

HeadObject用于查询Object的meta信息。

1. 请求语法：

HEAD /ObjectName HTTP/1.1
Host: yourBucket.s3.didiyunapi.com
Authorization: authorization string
Date: date

l 请求参数

无

l 请求头

公共请求头部

l 请求体

无

2. 响应语法：

l 响应头

除了公共响应头部，还可以使用下列字段。

名称	描述
x-didi-meta-*	以x-didi-meta-为前缀的header称为用户自定义header，用户自定义header是key-value对的集合，服务端不会校验用户自定义的header 类型：字符串
Content-Encoding ，Content-Language, Content-Disposition, Expires，Cache-Control，Accept-Ranges	REST请求头类型：字符串默认值：无
Last-Modified	Object上次被修改的时间类型：日期

l 响应体

无

3. 请求示例：

HEAD /exampleobject HTTP/1.1
Host: yourBucket.s3.didiyunapi.com
Date: Fri, 02 Dec 2011 01:53:42 GMT
Authorization: authorization string

4. 响应示例：

HTTP/1.1 200 OK
accept-ranges: bytes
cache-control: no-cache
content-length: 8369
content-type: application/x-www-form-urlencoded
date: Wed, 03 Jan 2018 11:07:28 GMT
etag: 7999e7b5aa948bf41380bf5f8593c68a
last-modified: Wed, 03 Jan 2018 11:05:16 GMT
server: DSS
x-didi-request-id: 006f9c96-9791-4ad6-b6e7-4760886a8f36

GetObject

Get Object用于下载文件。

1. 请求语法：

GET /ObjectName HTTP/1.1
Host: yourBucket.s3.didiyunapi.com
Date: dateAuthorization: authorization string

l 请求参数

参数	描述	是否必须
response-content-type	设置响应的Content-Type头域类型：字符串默认值：无	否
response-content-language	设置响应的Content-Language头域类型：字符串默认值：无	否
response-expires	设置响应的expires头域类型：字符串默认值：无	否
response-cache-control	设置响应的Cache-Control头域类型：字符串默认值：无	否
response-content-disposition	设置响应的Content-Disposition头域类型：字符串默认值：无	否
response-content-encoding	设置响应的Content-Encoding头域类型：字符串默认值：无	否

l 请求头

除了使用公共请求头部，还可以使用下列字段。

名称	描述	是否必须
If-Modified-Since	如果指定的时间早于实际修改时间，则正常传送文件，并返回200 OK；否则返回304 not modified 类型：字符串默认值：无时间格式：GMT时间，例如Fri, 13 Nov 2015 14:47:53 GMT	否
If-Unmodified-Since	如果指定的时间等于或者晚于文件实际修改时间，则正常传输文件，并返回200 OK；否则返回412 precondition failed 类型：字符串默认值：无时间格式：GMT时间，例如Fri, 13 Nov 2015 14:47:53 GMT	否
If-Match	如果指定的值和Object的MD5值匹配，则正常传输文件，并返回200 OK；否则返回412 precondition failed 类型：字符串默认值：无	否
If-None-Match	如果指定的值和Object的MD5值不匹配，则正常传输文件,并返回200 OK；否则返回304 Not Modified 类型：字符串默认值：无	否

l 请求体

无

2. 响应语法：

l 响应头

除去公共返回头部，您还可以使用如下参数：

名称	描述
x-didi-meta-*	以x-didi-meta-为前缀的header称为用户自定义header，用户自定义header是key-value对的集合，服务端不会校验用户自定义的header 类型：字符串
Content-Encoding ，Content-Language, Content-Disposition, Expires，Cache-Control，Accept-Ranges	REST请求头类型：字符串默认值：无
Last-Modified	Object上次被修改的时间类型：日期

l 响应体

无

3. 请求示例：

GET /exampleobject HTTP/1.1
Host: yourBucket.s3.didiyunapi.com
Date: Mon, 3 Oct 2016 22:32:00 GMT
Authorization: authorization string

4. 响应示例：

HTTP/1.1 200 OK
accept-ranges:bytes
cache-control:no-cache
content-length:8369
content-type:image/jpeg
date:Wed, 03 Jan 2018 07:20:43 GMT
etag:7999e7b5aa948bf41380bf5f8593c68a
last-modified:Tue, 02 Jan 2018 11:56:03 GMT
server:DSS
x-didi-meta-a:24
x-didi-meta-b:24
x-didi-request-id:9c423cd6-68c0-4bf1-b183-3ab76178d34c

上一篇对象存储SDK文档

下一篇对象存储控制台用户指南

快速开始

接口概览

关于Service的操作

关于Bucket的操作

关于Object的操作

请求签名

公共请求头部

公共返回头部

错误码

错误响应格式

错误码列表

Service接口

GetService

PutBucket

HeadBucket

DeleteBucket

PutBucketAcl

Get Bucket（List Objects）Version 2

Get Bucket（List Objects）Version 1

Object 接口

PutObject

PutObjectACL

DeleteObject

DeleteMultipleObjects