调用PutObject接口上传文件(Object)。

注意事项

  • 添加的Object大小不能超过5 GB。
  • 默认情况下,如果已存在同名Object且对该Object有访问权限,则新添加的Object将覆盖原有的Object,并返回200 OK。
  • OSS没有文件夹的概念,所有资源都是以文件来存储,但您可以通过创建一个以正斜线(/)结尾,大小为0的Object来创建模拟文件夹。

版本控制

在已开启版本控制的Bucket中,OSS会为新添加的Object自动生成唯一的版本ID,并在响应Header中通过x-oss-version-id形式返回。

在暂停了版本控制的Bucket中,新添加的Object的版本ID为null。OSS会保证同一个Object仅有一个null的版本ID。

请求语法

PUT /ObjectName HTTP/1.1
Content-Length:ContentLength
Content-Type: ContentType
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

当您在OSS ON云盒中调用该接口时,您需要将Host替换为云盒Endpoint。更多信息,请参见云盒Endpoint

请求头

OSS支持HTTP协议规定的5个请求头Cache-Control、Expires、Content-Encoding、Content-Disposition、Content-Type。如果上传Object时设置了这些请求头,则下载该Object时,相应的请求头的值会自动使用上传Object时设置的值。

名称 类型 是否必选 示例值 描述
Authorization 字符串 OSS lkojgn8y1exic6e:6****+BuuEqzI1tAMW0wgIyl**** 表示请求本身已被授权。 关于Authorization计算方法的更多信息,请参见在Header中包含签名

通常情况下Authorization是必选请求头,但如果采用了URL包含签名,则不用携带该请求头。更多信息,请参见在URL中包含签名

默认值:无

Cache-Control 字符串 no-cache 指定该Object被下载时网页的缓存行为。取值如下:
  • no-cache:不可直接使用缓存,而是先到服务端验证Object是否已更新。如果Object已更新,表明缓存已过期,需从服务端重新下载Object;如果Object未更新,表明缓存未过期,此时将使用本地缓存。
  • no-store:所有内容都不会被缓存。
  • public:所有内容都将被缓存。
  • private:所有内容只在客户端缓存。
  • max-age=<seconds>:缓存内容的相对过期时间,单位为秒。此选项仅在HTTP 1.1中可用。

默认值:无

Content-Disposition 字符串 attachment 指定Object的展示形式。取值如下:
  • inline:预览Object。
    注意 在以下情况中通过浏览器访问OSS内的Object,即使Content-Disposition取值为inline,也会直接下载Object:
    • Object为网页文件,未使用Bucket绑定的自定义域名进行访问。
    • Object为图片文件,Object所在的Bucket于2019年09月23日之后创建,且未使用Bucket绑定的自定义域名进行访问。
    • 请求的Object为浏览器不支持预览的类型。
  • attachment:将Object下载到本地。例如attachment; filename="example.jpg",表示下载Object到本地并以example.jpg文件名进行保存。
    说明
    • 通过浏览器将Object下载到本地时,如果Object名称包含星号(*)、正斜线(/)等特殊字符时,可能会出现特殊字符转义的情况。例如,下载example*.jpg"到本地时,example*.jpg"可能会转义为example_.jpg"
    • 如需确保下载名称中包含中文字符的Object到本地指定路径后,文件名称不出现乱码的现象,您需要将名称中包含的中文字符进行URL编码。例如,将测试.txt从OSS下载到本地后,需要保留文件名为测试.txt,需按照"attachment;filename="+URLEncoder.encode("测试","UTF-8")+".txt;filename*=UTF-8''"+URLEncoder.encode("测试","UTF-8")+".txt")的格式设置Content-Disposition,即attachment;filename=%E6%B5%8B%E8%AF%95.txt;filename*=%E6%B5%8B%E8%AF%95.txt

默认值:无

Content-Encoding 字符串 identity 声明Object的编码方式。您需要按照Object 的实际编码类型填写,否则可能造成客户端(浏览器)解析编码失败或Object下载失败。若Object未编码,请置空此项。取值如下:
  • identity(默认值):表示Object未经过压缩或编码。
  • gzip:表示Object采用Lempel-Ziv(LZ77)压缩算法以及32位CRC校验的编码方式。
  • compress:表示Object采用Lempel-Ziv-Welch(LZW)压缩算法的编码方式。
  • deflate:表示Object采用zlib结构和deflate压缩算法的编码方式。
  • br:表示Object采用Brotli算法的编码方式。

默认值:无

Content-MD5 字符串 eB5eJF1ptWaXm4bijSPyxw== 用于检查消息内容是否与发送时一致。Content-MD5是由MD5算法生成的值。上传了Content-MD5请求头后,OSS会计算消息体的Content-MD5并检查一致性。更多信息,请参见Content-MD5的计算方法

为确保数据完整性,OSS提供多种方式对数据的MD5值进行校验。 如果需要通过Content-MD5进行MD5验证,可将Content-MD5加入到请求头中。

默认值:无

Content-Length 字符串 344606 用于描述HTTP消息体的传输大小。

如果请求头中的Content-Length值小于实际请求体中传输的数据大小,OSS仍将成功创建Object,但Object的大小只能等于Content-Length中定义的大小,其他数据将被丢弃。

ETag 字符串 Object生成时会创建相应的ETag ,ETag用于标识一个Object的内容。
  • 对于PutObject请求创建的Object,ETag值是其内容的MD5值。
  • 对于其他方式创建的Object,ETag值是基于一定计算规则生成的唯一值,但不是其内容的MD5值。
说明 ETag值可以用于检查Object内容是否发生变化。不建议使用ETag作为Object内容的MD5来校验数据完整性。

默认值:无

Expires 字符串 2022-10-12T00:00:00.000Z 缓存内容的绝对过期时间,格式是格林威治时间(GMT)。

默认值:无

x-oss-forbid-overwrite 字符串 false 指定PutObject操作时是否覆盖同名Object。 当目标Bucket处于已开启或已暂停的版本控制状态时,x-oss-forbid-overwrite请求Header设置无效,即允许覆盖同名Object。
  • 不指定x-oss-forbid-overwrite或者指定x-oss-forbid-overwritefalse时,表示允许覆盖同名Object。
  • 指定x-oss-forbid-overwritetrue时,表示禁止覆盖同名Object。

设置x-oss-forbid-overwrite请求Header会导致QPS处理性能下降,如果您有大量的操作需要使用x-oss-forbid-overwrite请求Header(QPS>1000),请联系技术支持,避免影响您的业务。

默认值:false

x-oss-server-side-encryption 字符串 AES256 创建Object时,指定服务器端加密方式。

取值:AES256KMSSM4

说明 在OSS ON云盒使用场景中,仅支持AES256。

指定此选项后,在响应头中会返回此选项,OSS会对上传的Object进行加密编码存储。当下载该Object时,响应头中会包含x-oss-server-side-encryption,且该值会被设置成此Object的加密算法。

x-oss-server-side-data-encryption 字符串 SM4 指定Object的加密算法。如果未指定此选项,表明Object使用AES256加密算法。此选项仅当x-oss-server-side-encryption为KMS时有效。
说明 在OSS ON云盒使用场景中,不支持使用此选项。

取值:SM4

x-oss-server-side-encryption-key-id 字符串 9468da86-3509-4f8d-a61e-6eab1eac**** KMS托管的用户主密钥。

此选项仅在x-oss-server-side-encryption为KMS时有效。

在OSS ON云盒使用场景中,不支持使用此选项。

说明 在OSS ON云盒使用场景中,不支持使用此选项。
x-oss-object-acl 字符串 default 指定OSS创建Object时的访问权限。
取值:
  • default(默认):Object遵循所在存储空间的访问权限。
  • private:Object是私有资源。只有Object的拥有者和授权用户有该Object的读写权限,其他用户没有权限操作该Object。
  • public-read:Object是公共读资源。只有Object的拥有者和授权用户有该Object的读写权限,其他用户只有该Object的读权限。请谨慎使用该权限。
  • public-read-write:Object是公共读写资源。所有用户都有该Object的读写权限。请谨慎使用该权限。

关于访问权限的更多信息,请参见Object ACL

x-oss-storage-class 字符串 Standard 指定Object的存储类型。

对于任意存储类型的Bucket,如果上传Object时指定此参数,则此次上传的Object将存储为指定的类型。例如在IA类型的Bucket中上传Object时,如果指定x-oss-storage-class为Standard,则该Object直接存储为Standard。

取值:
  • Standard:标准存储
  • IA:低频访问
  • Archive:归档存储
  • ColdArchive:冷归档存储
说明 在OSS ON云盒使用场景中,仅支持Standard类型。

关于存储类型的更多信息,请参见存储类型介绍

x-oss-meta-* 字符串 x-oss-meta-location 使用PutObject接口时,如果配置以x-oss-meta-*为前缀的参数,则该参数视为元数据,例如x-oss-meta-location。一个Object可以有多个类似的参数,但所有的元数据总大小不能超过8 KB。

元数据支持短划线(-)、数字、英文字母(a~z)。英文字符的大写字母会被转成小写字母,不支持下划线(_)在内的其他字符。

x-oss-tagging 字符串 TagA=A&TagB=B 以键值对(Key-Value)的形式指定Object的标签信息,可同时设置多个标签,例如TagA=A&TagB=B
说明 Key和Value需进行URL编码。其中,Key为必选项,Value为可选项,即Object标签信息可设置为TagA&TagB=B

此接口还需要包含Host、Date等公共请求头。更多信息,请参见公共请求头(Common Request Headers)

响应头

此接口仅涉及公共响应头。更多信息,请参见公共响应头(Common Response Headers)

示例

  • 简单上传
    请求示例
    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 qn6qrrqxo2oawuk53otf****: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 qn6qrrqxo2oawuk53otf****: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"
  • 已开启版本控制
    请求示例
    PUT /test HTTP/1.1
    Content-Length:362149
    Content-Type: text/html
    Host: versioning-put.oss-cn-hangzhou.aliyuncs.com
    Date: Tue, 09 Apr 2019 02:53:24 GMT
    Authorization: OSS lkojgn8y1exic6e:6****+BuuEqzI1tAMW0wgIyl****
    返回示例
    HTTP/1.1 200 OK
    Server: AliyunOSS
    Date: Tue, 09 Apr 2019 02:53:24 GMT
    Content-Length: 0
    Connection: keep-alive
    x-oss-request-id: 5CAC0A3DB7AEADE01700****
    x-oss-version-id: CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****
    ETag: "4F345B1F066DB1444775AA97D5D2****"

SDK

PutObject接口对应的各语言SDK如下:

错误码

错误码 HTTP状态码 描述
MissingContentLength 411 请求头没有采用chunked encoding编码方式,或没有设置Content-Length参数。
InvalidEncryptionAlgorithmError 400 指定x-oss-server-side-encryption的值无效。

取值:AES256KMSSM4

AccessDenied 403 添加Object时,用户对设置的Bucket没有访问权限。
NoSuchBucket 404 添加Object时,设置的Bucket不存在。
InvalidObjectName 400 传入的Object key长度大于1023字节。
InvalidArgument 400 返回该错误的可能原因如下:
  • 添加的Object大小超过5 GB。
  • x-oss-storage-class等参数的值无效。
RequestTimeout 400 指定了Content-Length,但没有发送消息体,或者发送的消息体小于指定的大小。此种情况下服务器会一直等待,直至请求超时。
Bad Request 400 在请求中指定Content-MD5后,OSS会计算所发送数据的MD5值,并与请求中Conent-MD5的值进行比较。如果二者不一致,则返回该错误。
KmsServiceNotEnabled 403 x-oss-server-side-encryption指定为KMS,但没有预先购买KMS套件。
FileAlreadyExists 409 当请求的Header中携带x-oss-forbid-overwrite=true时,表示禁止覆盖同名文件。如果同名文件已存在,则返回该错误。
FileImmutable 409 Bucket中的数据处于被保护状态时,如果尝试删除或修改相应数据,则返回该错误。