PutObject_对象存储(OSS)-阿里云帮助中心

注意事项

添加的 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。

权限说明

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

请求语法

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 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 下载到浏览器指定路径时：
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 中定义的大小，其他数据将被丢弃。
Expires	字符串	否	Wed, 08 Jul 2015 16:57:01 GMT	过期时间。更多信息，请参见 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
x-oss-server-side-data-encryption	字符串	否	SM4	指定 Object 的加密算法。如果未指定此选项，表明 Object 使用 AES256 加密算法。此选项仅当 x-oss-server-side-encryption 为 KMS 时有效。
x-oss-server-side-encryption-key-id	字符串	否	9468da86-3509-4f8d-a61e-6eab1eac****	KMS 托管的用户主密钥。此选项仅在 x-oss-server-side-encryption 为 KMS 时有效。
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 ：标准存储
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` 。

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

响应头

名称	类型	示例值	描述
Content-MD5	字符串	1B2M2Y8AsgTpgAmY7PhC****	表示文件的 MD5 值。
x-oss-hash-crc64ecma	字符串	316181249502703****	表示文件的 CRC64 值。
x-oss-version-id	字符串	CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****	表示文件的版本 ID。仅当您将文件上传至已开启版本控制状态的 Bucket 时，会返回该响应头。

此接口还涉及其他公共响应头，例如 Date、x-oss-request-id 等。更多信息，请参见公共响应头（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****"

SDK

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

命令行工具 ossutil

PutObject 接口所对应的 ossutil 命令，请参见 put-object 。

错误码

错误码	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 中的数据处于被保护状态时，如果尝试删除或修改相应数据，则返回该错误。

常见问题

是否支持修改已上传文件的元数据？

支持。您可以通过 OSS 控制台、图形化管理工具 ossbrowser、各语言 SDK、命令行工具 ossutil 或者 REST API 修改已上传文件的元数据，例如将文件元数据 Content-Type 的值从 application/octet-stream 修改为 image/jpeg。具体步骤，请参见管理文件元数据。

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

优先级问题

当您同时设置 Expires 和 Cache-Control 头部时， Cache-Control 头部的优先级高于 Expires 头部。这意味着浏览器会先检查 Cache-Control 头部，只有在没有找到有效的 Cache-Control 头部时才会考虑 Expires 头部。如果 Cache-Control 头部包含了缓存控制指令（例如 Cache-Control:max-age=3600）， Expires 头部可能会被忽略。

Expires 头部设置有误

Expires 头部表示缓存内容的绝对过期时间，格式是格林威治时间（GMT），并且必须确保是未来的有效时间。如果 Expires 头部设置的时间已过期或者格式不正确，则该头部将被视为无效。以下提供了 OSS Node.js SDK 设置 Expires 头部的代码示例：

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);

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`

PutObject

注意事项

版本控制

权限说明

请求语法

请求头

响应头

示例

SDK

命令行工具 ossutil

错误码

常见问题

是否支持修改已上传文件的元数据？

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

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