对象存储PutObject接口_对象存储(OSS)-阿里云帮助中心

PutObject接口用于上传文件到OSS的存储空间，单次上传文件大小限制为5GB。

请求语法

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。

使用说明

单次上传文件大小限制为5GB。若需上传大于5GB的文件，应使用分片上传功能。
上传同名文件时，默认覆盖原有文件并返回200 OK状态码。通过设置禁止覆盖参数可避免意外覆盖重要文件。
OSS采用扁平化存储结构，无传统文件系统的目录概念。通过创建以正斜线（/）结尾的空对象可模拟文件夹结构。

权限要求

阿里云账号默认拥有全部权限。阿里云账号下的RAM用户或RAM角色默认没有任何权限，需要阿里云账号或账号管理员通过RAM Policy或Bucket Policy授予操作权限。

API	Action	说明
PutObject	`oss:PutObject`	上传Object。
	`oss:PutObjectTagging`	上传Object时，如果通过x-oss-tagging指定Object的标签，则需要此操作的权限。
	`kms:GenerateDataKey`	上传Object时，如果Object的元数据包含X-Oss-Server-Side-Encryption: KMS，则需要这两个操作的权限。
	`kms:Decrypt`

版本控制

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

在暂停版本控制的Bucket中，新添加的Object版本ID为null。OSS确保同一Object仅存在一个null版本。

请求参数

OSS支持标准HTTP请求头Cache-Control、Expires、Content-Encoding、Content-Disposition、Content-Type。设置这些请求头后，下载文件时会自动应用相应的值。

参数名称	类型	必选	示例值	说明
Authorization	字符串	否	OSS qn6q************:77Dv**************	表示请求已通过身份验证和授权。关于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的展示形式。取值如下： Content-Disposition:inline：直接预览文件内容。 Content-Disposition:attachment：以原文件名的形式下载到浏览器指定路径。 Content-Disposition:attachment; filename="yourFileName"：以自定义文件名的形式下载到浏览器指定路径。 yourFileName用于自定义下载后的文件名称，例如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*=UTF-8''%E6%B5%8B%E8%AF%95.txt`。通过文件URL访问文件时是预览还是以附件形式下载，与文件所在Bucket的创建时间、OSS开通时间以及使用的域名类型有关。更多信息，请参见通过文件URL访问文件无法预览而是以附件形式下载？。默认值：无
Content-Encoding	字符串	否	identity	声明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算法生成的值。设置该请求头后，OSS会计算消息体的Content-MD5并检查一致性。详细信息请参见Content-MD5的计算方法。为确保数据完整性，OSS提供多种数据MD5值校验方式。如需通过Content-MD5进行MD5验证，可将Content-MD5加入到请求头中。默认值：无
Content-Length	字符串	否	344606	描述HTTP消息体的传输大小，单位为字节。如果请求头中的Content-Length值小于实际请求体传输的数据大小，OSS仍将成功创建Object，但Object大小等于Content-Length中定义的大小，超出部分数据将被丢弃。
Expires	字符串	否	Wed, 08 Jul 2015 16:57:01 GMT	指定Object的过期时间。详细信息请参见RFC2616。默认值：无
x-oss-forbid-overwrite	字符串	否	false	指定PutObject操作时是否覆盖同名Object。当目标Bucket处于已开启或已暂停的版本控制状态时，x-oss-forbid-overwrite请求Header设置无效，即允许覆盖同名Object。不指定x-oss-forbid-overwrite或者指定x-oss-forbid-overwrite为false时，表示允许覆盖同名Object。指定x-oss-forbid-overwrite为true时，表示禁止覆盖同名Object。设置x-oss-forbid-overwrite请求Header会影响QPS处理性能，如果大量操作需要使用x-oss-forbid-overwrite请求Header（QPS>1000），请联系技术支持，避免影响业务运行。默认值：false
x-oss-server-side-encryption	字符串	否	AES256	创建Object时指定服务器端加密方式。取值：AES256、KMS或SM4 说明在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托管的用户主密钥ID。此选项仅在x-oss-server-side-encryption为KMS时有效。说明在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：标准存储说明在OSS ON云盒使用场景中，仅支持Standard类型。 IA：低频访问 Archive：归档存储 ColdArchive：冷归档存储 DeepColdArchive：深度冷归档存储重要如果要上传的文件数量较多，直接指定上传的文件类型为深度冷归档类型会造成较高的PUT类请求费用。建议您先将文件的存储类型指定为标准存储进行上传，然后通过生命周期规则将其转储为深度冷归档类型，从而降低PUT类请求费用。详细信息请参见存储类型介绍。
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`。

更多公共请求头信息请参见公共响应头（Common Response Headers）。

响应参数

参数名称	类型	示例值	说明
Content-MD5	字符串	1B2M2Y8AsgTpgAmY7PhC****	表示上传文件的MD5值。重要文件的MD5值指的是客户端上传完成后获取到的文件MD5，并非响应体的MD5。
x-oss-hash-crc64ecma	字符串	316181249502703****	表示上传文件的CRC64值
x-oss-version-id	字符串	CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****	表示文件的版本ID。仅当文件上传至已开启版本控制状态的Bucket时，会返回该响应头。

更多公共响应头信息请参见公共响应头（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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
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: 316181249502703****
Content-MD5: 1B2M2Y8AsgTpgAmY7PhC****
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-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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-disposition;content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e 
[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
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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

返回示例

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****"

错误码

错误码	HTTP状态码	描述
MissingContentLength	411	请求头没有采用chunked encoding编码方式，或没有设置Content-Length参数。
InvalidEncryptionAlgorithmError	400	指定x-oss-server-side-encryption的值无效。取值：AES256、KMS或SM4。
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值，并与请求中Content-MD5的值进行比较。如果二者不一致，则返回该错误。
KmsServiceNotEnabled	403	将x-oss-server-side-encryption指定为KMS，但没有预先购买KMS套件。
FileAlreadyExists	409	当请求的Header中携带`x-oss-forbid-overwrite=true`时，表示禁止覆盖同名文件。如果同名文件已存在，则返回该错误。
FileImmutable	409	Bucket中的数据处于被保护状态时，如果尝试删除或修改相应数据，则返回该错误。

集成方式

SDK
PutObject接口对应的各语言SDK如下：
Java
Python V2
Go V2
C++
PHP V2
C
.NET
Android
iOS
Node.js
Browser.js
Ruby
Harmony
命令行工具ossutil
PutObject接口所对应的ossutil命令，请参见put-object。

常见问题

如何修改已上传文件的元数据？

支持通过OSS控制台、ossbrowser工具、各语言SDK、ossutil命令行工具或REST API修改文件元数据。例如将Content-Type从application/octet-stream修改为image/jpeg。详细操作请参见管理文件元数据。

为什么设置的Expires头部无效？

缓存头部优先级问题
同时设置Expires和Cache-Control时，Cache-Control优先级更高。如果Cache-Control包含缓存指令（如max-age=3600），Expires可能被忽略。

Expires设置错误

Expires必须是未来的有效GMT时间且格式正确。以下是Node.js SDK设置示例：

const OSS = require('ali-oss');

// 创建OSS客户端实例
const client = new OSS({
  // yourregion填写Bucket所在地域。以华东1（杭州）为例，Region填写为oss-cn-hangzhou。
  region: 'yourregion',
  // 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // 填写Bucket名称。
  bucket: 'examplebucket',
});

async function setExpires(objectName, expiresDate) {
  try {
    const result = await client.copy(objectName, objectName, {
      meta: {
        'Expires': expiresDate.toGMTString()
      }
    });
    console.log('Expires header set successfully.');
  } catch (error) {
    console.error('Error setting Expires header:', error);
  }
}

// 设置缓存内容的绝对过期时间。
const expiresDate = new Date('2024-10-12T00:00:00.000Z');
setExpires('your-object-name', expiresDate);

Java	Python V2	Go V2	C++	PHP V2
C	.NET	Android	iOS	Node.js
Browser.js	Ruby	Harmony