PutObject
PutObject接口用于上传文件(Object)。
- 添加的Object大小不得超过5 GB。
- 默认情况下,如果已经存在同名Object且对该Object有访问权限,则新添加的Object将覆盖原有的Object,并成功返回200 OK。
- OSS没有文件夹的概念,所有元素都是以文件来存储,但您可以通过创建一个以正斜线(/)结尾,大小为0的Object来创建模拟文件夹,具体参见OSS文件夹。
请求语法
PUT /ObjectName HTTP/1.1
Content-Length:ContentLength
Content-Type: ContentType
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
请求头
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
Authorization | 字符串 | 否 | 表示请求本身已被授权,详细描述参考RFC2616。
一般情况下Authorization是必选请求头,但是若采用URL包含签名,可以不用携带该请求头。详细描述参考在URL中包含签名。 默认值:无 |
Cache-Control | 字符串 | 否 | 指定该Object被下载时网页的缓存行为,详细描述参考RFC2616。
默认值:无 |
Content-Disposition | 字符串 | 否 | 指定该Object被下载时的名称,详细描述参考RFC2616。
默认值:无 |
Content-Encoding | 字符串 | 否 | 指定该Object被下载时的内容编码格式,详细描述参考RFC2616。
默认值:无 |
Content-MD5 | 字符串 | 否 | 用于检查消息内容是否与发送时一致。Content-MD5是一串由MD5算法生成的值。上传了Content-MD5请求头后,OSS会计算消息体的Content-MD5并检查一致性。有关Content-MD5的计算方法,详情请参见Content-MD5的计算方法。
默认值:无 |
Content-Length | 字符串 | 否 | 用于描述HTTP消息体的传输大小。
如果请求头中的Content-Length值小于实际请求体中传输的数据大小,OSS仍将成功创建文件,但Object的大小只等于Content-Length中定义的大小,其他数据将被丢弃。 |
ETag | 字符串 | 否 | Object生成时会创建相应的ETag (entity tag) ,ETag用于标示一个Object的内容。
说明 ETag值可以用于检查Object内容是否发生变化。不建议使用ETag作为Object内容的MD5来校验数据完整性。
默认值:无 |
Expires | 字符串 | 否 | 过期时间,详细描述参考照RFC2616。
默认值:无 |
x-oss-forbid-overwrite | 字符串 | 否 | 指定PutObject操作时是否覆盖同名Object。
|
x-oss-server-side-encryption | 字符串 | 否 | 指定OSS创建Object时的服务器端加密编码算法。
取值:AES256 或 KMS(您需要购买KMS套件,才可以使用 KMS 加密算法,否则会报 KmsServiceNotEnabled 错误码) 指定此参数后,在响应头中会返回此参数,OSS会对上传的Object进行加密编码存储。当下载该Object时,响应头中会包含x-oss-server-side-encryption,且该值会被设置成该Object的加密算法。 |
x-oss-server-side-encryption-key-id | 字符串 | 否 | KMS托管的用户主密钥。
该参数在x-oss-server-side-encryption为KMS时有效。 |
x-oss-object-acl | 字符串 | 否 | 指定OSS创建Object时的访问权限。
合法值:public-read,private,public-read-write |
x-oss-storage-class | 字符串 | 否 | 指定Object的存储类型。
对于任意存储类型的Bucket,若上传Object时指定此参数,则此次上传的Object将存储为指定的类型。例如,在IA类型的Bucket中上传Object时,若指定x-oss-storage-class为Standard,则该Object直接存储为Standard。 取值:Standard、IA、Archive 支持的接口:PutObject、InitMultipartUpload、AppendObject、 PutObjectSymlink、CopyObject。 |
x-oss-meta-* | 字符串 | 否 | 使用PutObject接口时,如果配置以x-oss-meta-*为前缀的参数,则该参数视为元数据,例如x-oss-meta-location。一个Object可以有多个类似的参数,但所有的元数据总大小不能超过8KB。
元数据支持短横线(-)、数字、英文字母(a-z),英文字符的大写字母会被转成小写字母,不支持下划线(_)在内的其他字符 |
x-oss-tagging | 字符串 | 否 | 指定Object的标签,可同时设置多个标签,例如: TagA=A&TagB=B。
说明 Key和Value需要先进行URL编码,如果某项没有"=",则看作Value为空字符串。
|
示例
- 简单上传的请求示例
PUT /test.txt HTTP/1.1 Host: test.oss-cn-zhangjiakou.aliyuncs.com User-Agent: aliyun-sdk-python/2.6.0(Windows/7/AMD64;3.7.0) Accept: */* Connection: keep-alive Content-Type: text/plain date: Tue, 04 Dec 2018 15:56:37 GMT authorization: OSS qn6qrrqxo2oawuk53otfjbyc:kZoYNv66bsmc10+dcGKw5x2P**** Transfer-Encoding: chunked
返回示例HTTP/1.1 200 OK Server: AliyunOSS Date: Tue, 04 Dec 2018 15:56:38 GMT Content-Length: 0 Connection: keep-alive x-oss-request-id: 5C06A3B67B8B5A3DA422299D ETag: "D41D8CD98F00B204E9800998ECF8****" x-oss-hash-crc64ecma: 0 Content-MD5: 1B2M2Y8AsgTpgAmY7PhCfg== x-oss-server-time: 7
- 带有归档存储类型的请求示例
PUT /oss.jpg HTTP/1.1 Host: oss-example.oss-cn-hangzhou.aliyuncs.com Cache-control: no-cache Expires: Fri, 28 Feb 2012 05:38:42 GMT Content-Encoding: utf-8 Content-Disposition: attachment;filename=oss_download.jpg Date: Fri, 24 Feb 2012 06:03:28 GMT Content-Type: image/jpg Content-Length: 344606 x-oss-storage-class: Archive Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:kZoYNv66bsmc10+dcGKw5x2P**** [344606 bytes of object data]
返回示例HTTP/1.1 200 OK Server: AliyunOSS Date: Sat, 21 Nov 2015 18:52:34 GMT Content-Type: image/jpg Content-Length: 0 Connection: keep-alive x-oss-request-id: 5650BD72207FB30443962F9A x-oss-bucket-version: 1418321259 ETag: "A797938C31D59EDD08D86188F6D5B872"
SDK
错误码
错误码 | HTTP 状态码 | 描述 |
---|---|---|
MissingContentLength | 411 | 请求头没有采用chunked encoding编码方式,且没有Content-Length参数。 |
InvalidEncryptionAlgorithmError | 400 | 指定x-oss-server-side-encryption的值无效。
有效值:AES256或KMS。 |
AccessDenied | 403 | 对试图添加Object的Bucket没有访问权限。 |
NoSuchBucket | 404 | 试图添加Object的Bucket不存在。 |
InvalidObjectName | 400 | 传入的Object key长度大于1023字节。 |
InvalidArgument | 400 |
|
RequestTimeout | 400 | 指定了Content-Length,但是没有发送消息体,或者发送的消息体小于给定的大小。这种情况下服务器会一直等待,直到time out。 |
KmsServiceNotEnabled | 403 | 将x-oss-server-side-encryption指定为KMS,但没有预先购买KMS套件。 |
FileAlreadyExists | 409 | 当请求的header中携带x-oss-forbid-overwrite=true时,表示禁止覆盖同名文件。如果文件已存在,则返回该错误。 |
版权声明
本文仅代表作者观点,不代表本站立场。
本文系作者授权发表,未经许可,不得转载。
评论