6. 对象操作¶
6.1. DELETE Object¶
6.1.1. 描述¶
删除一个对象。
6.1.2. 语法¶
DELETE /${ObjectKey} HTTP/1.1
HOST: ${BucketName}.${endpoint}
Date: ${date}
Authorization: ${signature}
6.1.3. 请求参数¶
| 参数 | 描述 | 是否必须 |
|---|---|---|
| ObjectKey | 删除对象的对象名称
类型：字符串
|
Yes |
6.1.4. 响应头¶
| Header | 描述 |
|---|---|
| 无特定头部 | 除通用返回头部外，无特殊头部
类型：字符串
|
6.1.5. 示例¶
Request
DELETE /1.jpg HTTP/1.1
HOST: dream.nos-eastchina1.126.net
Date: Fri, 10 Feb 2012 21:34:55 GMT
Authorization: NOS I_AM_ACCESS_ID:I_AM_SIGNATURE
Response
HTTP/1.1 200 OK
x-nos-request-id: 17b21e42ac11000001390ab891440240
Date: Wed, 01 Mar 2012 21:34:55 GMT
Connection: close
Server: NOS
6.1.6. 细节描述¶
- 如果Bucket不存在，返回404 no content错误。错误码：NoSuchBucket。
- 只有Bucket的拥有者才能删除Bucket中的Object。非Bucket拥有者执行DELETE Object 操作将返回403 Forbidden错误。错误码：AccessDenied。
- 如果要删除的Object不存在，返回404- NoSuchKey。
6.2. Delete Multiple Objects¶
6.2.1. 描述¶
Delete Multiple Object 操作支持用户通过一个HTTP 请求删除同一个Bucket中的多个Object。Delete Multiple Object操作支持一次请求内最多删除1000个Object，并提供两种返回模式：详细(verbose)模式和简单(quiet)模式:
| 详细模式: | NOS返回的消息体中会包含每一个删除Object的结果。 |
|---|---|
| 简单模式: | NOS返回的消息体中只包含删除过程中出错的Object结果；如果所有删除都成功的话，则没有消息体。 |
6.2.2. 语法¶
POST / HTTP/1.1
HOST: ${BucketName}.${endpoint}
Content-Length: ${length}
Date: ${date}
Authorization: ${signature}
6.2.3. 请求元素¶
| Element | 描述 |
|---|---|
| Delete | 多重删除的请求容器元素
类型：容器
|
| Quiet | 是否显示具体删除信息
类型：布尔值
父节点：Delete
|
| Object | 要删除的单个对象的容器元素
类型：容器
父节点：Delete
|
| Key | 要删除的对象键值
类型：字符串
父节点：Object
|
| VersionId | 要删除的对象版本号
类型：数字
父节点：Object
|
6.2.4. 响应元素¶
| Element | 描述 |
|---|---|
| DeleteResult | 多重删除的响应容器元素
类型：容器
|
| Deleted | 已被成功删除的容器元素
类型：容器
父节点：DeleteResult
|
| Key | 已删除的对象键值
类型：字符串
父节点：Deleted，Error
|
| Error | 删除失败的对象版本号
类型：容器
父节点：DeleteResult
|
| Code | 删除失败返回的错误码
类型：字符串
父节点：Error
|
| Message | 删除失败返回的详细错误描述
类型：字符串
父节点：Error
|
6.2.5. 示例¶
Request
POST /?delete HTTP/1.1
HOST: dream.nos-eastchina1.126.net
Content-Length: 123
Content-MD5: cdb586d8ee4952fdcc234e8712ea2bdb
Authorization: NOS I_AM_ACCESS_ID:I_AM_SIGNATURE
<Delete>
<Quiet>false</Quiet>
<Object>
<Key>1.jpg</Key>
</Object>
<Object>
<Key>2.jpg</Key>
</Object>
</Delete>
Response
HTTP/1.1 200 OK
x-nos-request-id: 17b21e42ac11000001390ab891440240
Date: Fri, 02 Feb 2012 01:53:42 GMT
Content-Length: 251
Connection: close
Server: NOS
<?xml version="1.0" encoding="UTF-8"?>
<DeleteResult>
<Deleted>
<Key>1.jpg</Key>
</Deleted>
<Error>
<Key>2.jpg</Key>
<Code>AccessDenied</Code>
<Message>Access Denied</Message>
</Error>
<Error>
<Key>3.jpg</Key>
<Code>NoSuchKey</Code>
<Message>No Such Key</Message>
</Error>
</DeleteResult>
6.2.6. 细节描述¶
- 如果Bucket不存在，返回404 no content错误。错误码：NoSuchBucket。
- 只有Bucket的拥有者才能删除Bucket中的Object。非Bucket拥有者执行DELETE multiple Objects操作将返回403 Forbidden错误。错误码：AccessDenied。
- Delete Multiple Object请求默认是详细(verbose)模式。
- 在Delete Multiple Object请求中删除一个不存在的Object，仍然认为是成功的。
- Delete Multiple Object的消息体最大允许2MB的内容，超过2MB会返回MalformedXML错误码。
- Delete Multiple Object请求最多允许一次删除1000个Object；超过1000个Object会返回MalformedXML错误码。
- 如果HTTP请求的BODY XML格式有误，返回400 Bad Request消息。错误码：MalformedXML。
- HTTP请求头Content-Length必须，否则返回411 Length Required消息。错误码：MissingContentLength。
6.3. GET Object¶
6.3.1. 描述¶
读取对象内容，返回对象流。
6.3.2. 语法¶
GET /${ObjectKey}?download=${download}&ifNotFound=${ifNotFound} HTTP/1.1
HOST: ${BucketName}.${endpoint}
Date: ${date}
Authorization: ${signature}
Range: ${range}
6.3.3. 请求参数¶
| 参数 | 描述 | 是否必须 |
|---|---|---|
| download | 通过浏览器打开时，通过指定该值，浏览器将进行下载而非在浏览器中直接打开
当NOS发现请求的Url中有该值时，会在响应中增加标准HTTP字段 Content-Disposition，如下：
Content-Disposition: attachment; filename=”<file_name>”
类型：字符串（经过urlencode编码）
限制：字符串长度不得超过256字节（未经过编码时）
|
No |
| ifNotFound | 通过该参数，可以指定当访问的对象不存在时，期望返回的对象内容（注意此时返回值为404）
类型：字符串（经过urlencode编码）
|
No |
6.3.4. 请求头¶
| 参数 | 描述 | 是否必须 |
|---|---|---|
| Range | No | |
| If-Modified-Since | 只有当指定时间之后做过修改操作才返回这个对象，否则返回304(Not Modifed)
类型：字符串
默认：无
|
No |
6.3.5. 示例¶
Request
GET /1.jpg HTTP/1.1
HOST: dream.nos-eastchina1.126.net
Date: Fri, 10 Feb 2012 21:34:55 GMT
Range: 0-1024
Authorization: NOS I_AM_ACCESS_ID:I_AM_SIGNATURE
Response
HTTP/1.1 206 OK
x-nos-request-id: 17b21e42ac11000001390ab891440240
Content-Length: 1024
Content-Range: 0-1024/234564
ETag: d41d8cd98f00b204e9800998ecf8427e
Date: Wed, 01 Mar 2012 21:34:55 GMT
Last-Modified: Tue, 05 Jul 2016 17:32:21 Asia/Shanghai
Connection: close
Server: NOS
[1024 bytes of binary data]
6.3.6. 细节描述¶
- 如果Bucket不存在，返回404 no content错误。错误码：NoSuchBucket。
#. NOS支持匿名读，此时需要设置桶为Public-read。如果试图读取没有读权限的Bucket中 的Object，返回403 Forbidden错误。错误码：AccessDenied。 #. GetObject通过range参数可以支持断点续传，对于比较大的Object建议使用该功能。
- 表示头500个字节：bytes=0-499
- 表示第二个500字节：bytes=500-999
- 表示最后500个字节：bytes=-500
- 表示500字节以后的范围：bytes=500-
Range设置必须严格符合上述规则，否则返回416 Requested Range Not Satisfiable错误。错误码：InvalidRange。
- 如果文件修改时间早于If-Modified-Since，返回304 Not Modified。
- 如果文件不存在返回404 Not Found错误。错误码：NoSuchKey。
- Get Object返回的HTTP头中还包含对象的ETag、Content-Type、Last-Modified等信息。
- 若指定了ifNotFound参数，当访问指定对象不存在时，NOS会进一步查找ifNotFound参数指定的对象，若存在，则返回ifNotFound对象内容，返回值为404，若不存在，则直接返回NoSuchKey错误。
- 如果返回的对象是分块上传对象，etag不是由对应文件的md5生成的。etag尾部的 -1 无特殊含义，只是作为标志。
6.4. HEAD Object¶
6.4.1. 描述¶
获取对象相关信息，返回对象相关元数据信息。该接口通常也用来判断对象存在性和是否有权限。
6.4.2. 语法¶
HEAD /${ObjectKey} HTTP/1.1
HOST: ${BucketName}.${endpoint}
Date: ${date}
Authorization: ${signature}
6.4.3. 请求参数¶
| 参数 | 描述 | 是否必须 |
|---|---|---|
| ObjectKey | 对象名
类型:字符串
默认:无
|
No |
6.4.4. 请求头¶
| Header | 描述 | 是否必须 |
|---|---|---|
| If-Modified-Since | 只有当指定时间之后做过修改操作才返回这个对象，否则返回304(Not Modifed)
类型:字符串
默认:无
|
No |
6.4.5. 示例¶
Request
HEAD /1.jpg?versionId=3332619744290771 HTTP/1.1
HOST: dream.nos-eastchina1.126.net
Date: Fri, 10 Feb 2012 21:34:55 GMT
Authorization: NOS I_AM_ACCESS_ID:I_AM_SIGNATURE
Response
HTTP/1.1 200 OK
x-nos-request-id: 17b21e42ac11000001390ab891440240
Content-Type: image
Date: Fri, 02 Feb 2012 01:53:42 GMT
Last-Modified: Sun, 1 Jan 2012 12:00:00 GMT
ETag: d41d8cd98f00b204e9800998ecf8427e
Connection: close
Server: NOS
6.4.6. 细节描述¶
#. 不论正常返回200 OK还是非正常返回，Head Object都不返回消息体。所有对象元数据都 包含在HTTP返回头中。 #. 如果Bucket不存在，返回404 no content错误。错误码：NoSuchBucket。 #. 只有Bucket的拥有者才能获取Bucket中Object的元数据信息。非Bucket拥有者执行HEAD Object操作将返回403 Forbidden错误。错误码：AccessDenied。 #. 如果对象是分块上传的对象，返回的etag不是由该对象对应的文件的md5生成的。etag尾 部的 -1 无特殊含义，只是作为标志。
6.5. PUT Object¶
6.5.1. 描述¶
PUT Object接口把对象上传到一个桶中。主要特性有：
- 持久特性，返回成功，则代表对象所有备份已经安全存储。
- 并发特性，对象存储不提供锁机制，同时写一个对象，则后完成的会覆盖前者。
- 数据完整特性，为了保证数据不被损坏，在 Content-MD5头设置对象的MD5摘要，服务器
会比对收到的二进制内容。也可以边传输边计算MD5，传完后跟响应的ETag属性对比。
6.5.2. 语法¶
PUT /${ObjectKey} HTTP/1.1
HOST: ${BucketName}.${endpoint}
Date: ${date}
Content-Length: ${length}
Content-MD5: ${md5}
Authorization: ${signature}
6.5.3. 请求头定义¶
| 参数 | 描述 | 是否必须 |
|---|---|---|
| Content-Length | 对象的大小
类型：字符串
默认：无
|
Yes |
| Content-MD5 | 128位MD5摘要经过Base64编码的值，用来检查网络传输过程中文件是否损坏
类型：字符串
默认：无
|
No |
| x-nos-meta- | 以该前缀开头的header都将被认为是用户自定义的元数据，比如：x-nos-meta-title: TITLE 这个header会把title:TITLE作为用户自定义元数据key-value对。
类型：字符串
默认：无
|
6.5.4. 示例¶
Request
PUT /1.jpg HTTP/1.1
HOST: dream.nos-eastchina1.126.net
Date: Fri, 10 Feb 2012 21:34:55 GMT
Content-Type: image/jpeg
Content-Length: 4096
Content-MD5: fbacf535f27731c9771645a39863328
Authorization: NOS I_AM_ACCESS_ID:I_AM_SIGNATURE
[4096 bytes of Object data]
Response
HTTP/1.1 200 OK
x-nos-request-id: 17b21e42ac11000001390ab891440240
Date: Wed, 12 Oct 2012 17:50:00 GMT
ETag: fbacf535f27731c9771645a39863328
Connection: close
Server: NOS
6.5.5. 细节描述¶
- 如果Bucket不存在，返回404 no content错误。错误码：NoSuchBucket。
- 只有Bucket的拥有者才能向Bucket中PUT Object。非Bucket拥有者执行PUT Object 操作将返回403 Forbidden错误。错误码：AccessDenied。
- 如果Put Object请求带Content-MD5头，NOS会将其与实际上传文件内容的MD5值进行对比，如果不一致，说明用户操作有误，或者文件在传输过程中出错，返回400 Bad Request错误。错误码：BadDigest。
- 如果Put Object请求不带Content-MD5头，NOS会将收到文件的MD5值放在返回给用户的请求头”ETag”中，以便用户检查NOS上的数据和要上传的数据内容一致。
- PUT Object请求头中的Content-Length必须和HTTP BODY的长度一致，否则返回400 Bad Request。错误码：IncompleteBody。
- 如果在PutObject的时候，携带以x-nos-meta-为前缀的参数，则视为Meta data，比如x-nos-meta-location。一个Object可以有多个类似的参数，但所有的Meta data总大小不能超过2k。
- 如果Head中没有加入Content-Length参数，会返回411 Length Required错误。错误码：MissingContentLength。
- 如果用户数据已经达到配额上线，则返回403 Forbidden错误。错误码：QuotaExceeded。
- 如果添加文件长度超过100M，返回错误消息400 Bad Request。错误码：EntityTooLarge。建议大对象使用分块接口。
- PUT Object允许创建空文件。Object名长度不能超过1000字节，否则错误消息400 Bad Request。错误码：InvalidArgument。
6.6. PUT Object - Copy¶
6.6.1. 描述¶
远程拷贝操作，生成一个新的对象，相当于”一次GET”+”一次PUT”。
6.6.2. 语法¶
PUT /${DestinationObjectKey} HTTP/1.1
HOST: ${DestinationBucketName}.${endpoint}
Date: ${date}
x-nos-copy-source: /${SourceBucketName}/${SourceObjectKey}
Authorization: ${signature}
6.6.3. 请求头¶
| Header | 描述 | 是否必须 |
|---|---|---|
| x-nos-copy-source | 拷贝的源对象
类型：字符串
默认：无
限制：该字符串必须做一下URL Encode，并且对该桶有读权限
|
YES |
6.6.4. 示例¶
Request
PUT /2.jpg HTTP/1.1
HOST: photo.nos-eastchina1.126.net
Date: Fri, 10 Feb 2012 21:34:55 GMT
x-nos-copy-source: /dream/1.jpg
Authorization: NOS I_AM_ACCESS_ID:I_AM_SIGNATURE
Response
HTTP/1.1 200 OK
x-nos-request-id: 17b21e42ac11000001390ab891440240
Date: Wed, 01 Mar 2012 21:34:55 GMT
Connection: close
Server: NOS
6.7. PUT Object – Move¶
6.7.1. 描述¶
远程移动操作，生成一个新的对象，相当于”一次COPY”+”一次DELETE”，但不涉及物理文件的 拷贝动作，仅仅修改元数据，不支持跨桶move操作。
6.7.2. 语法¶
PUT /${DestinationObjectKey} HTTP/1.1
HOST: ${DestinationBucketName}.${endpoint}
Date: ${date}
x-nos-move-source: /${SourceBucketName}/${SourceObjectKey}
Authorization: ${signature}
6.7.3. 请求头¶
| Header | 描述 | 是否必须 |
|---|---|---|
| x-nos-move-source | 对象原来的桶号和名称
类型：字符串
默认：无
限制：该字符串必须做一下URL Encode，并且对该桶有读权限
|
YES |
6.7.4. 示例¶
Request
PUT /2.jpg HTTP/1.1
HOST: photo.nos-eastchina1.126.net
Date: Fri, 10 Feb 2012 21:34:55 GMT
x-nos-move-source: /dream/1.jpg
Authorization: NOS I_AM_ACCESS_ID:I_AM_SIGNATURE
Response
HTTP/1.1 200 OK
x-nos-request-id: 17b21e42ac11000001390ab891440240
Date: Wed, 01 Mar 2012 21:34:55 GMT
Connection: close
Server: NOS
6.8. PUT Object Meta¶
6.8.1. 描述¶
修改获取对象时的HTTP响应的响应首部。
6.8.2. 语法¶
PUT /${ObjectKey}?meta HTTP/1.1
HOST: ${BucketName}.${endpoint}
Date: ${date}
Content-Length: ${length}
Content-MD5: ${md5}
Authorization: ${signature}
Content-Type: ${type}
Content-Encoding: ${encoding}
Cache-Control : ${cache-control}
Expires : ${expires}
Content-Disposition : ${disposition}
Content-Language : ${language}
6.8.3. 请求头¶
| Header | 描述 | 是否必须 |
|---|---|---|
| Content-Type | 对象所属类型
类型：字符串
默认：application/octet-stream
|
NO |
| Content-Encoding | 对象编码格式
类型：字符串
默认：无
|
NO |
| Cache-Control | 对象缓存控制
类型：字符串
默认：无
|
NO |
| Expires | 缓存的失效日期
类型：字符串
默认：无
|
NO |
| Content-Disposition | 对象的默认文件名
类型：字符串
默认：无
|
NO |
| Content-Language | 对象内容所属语言
类型：字符串
默认：无
|
NO |
| x-nos-meta- | 以该前缀开头的header都将被认为是用户自定义的元数据，比如：x-nos-meta-title: TITLE 这个header会把title:TITLE作为用户自定义元数据key-value对。
类型：字符串
默认：无
|
NO |
6.8.4. 示例¶
Request
PUT /2.jpg?meta HTTP/1.1
HOST: photo.nos-eastchina1.126.net
Date: Fri, 10 Feb 2012 21:34:55 GMT
Authorization: NOS I_AM_ACCESS_ID:I_AM_SIGNATURE
Content-Type: image/jpeg
Content-Encoding: utf-8
Cache-Control: max-age=0
Expires: Fri, 10 Feb 2012 21:34:55 GMT
Content-Language: en
Response
HTTP/1.1 200 OK
x-nos-request-id: 17b21e42ac11000001390ab891440240
Date: Wed, 01 Mar 2012 21:34:55 GMT
Connection: close
Server: NOS
6.8.5. 细节描述¶
- 如果要修改的Object不存在，返回404 Not Found。
- 如果用户输入非法的Content-Type则Content-Type自动为application/octet-stream，其他参数不检验合法性。
- 如果用户使用PutObjectMeta接口中没有指定某项元数据，那么认为该元数据在本次修改中设置为空；如果Content-Type没有指定，统一把Content-type修改为application/octet-stream。
- Content-Disposition 如果没有对应的记录，使用GET Object接口时通过默认的规则返回。默认的规则是根据对象的objectname生成。
- 本接口的权限控制类型与PUT Object一致。