全部产品
Search

搜索本产品

    对象存储 OSS：PutObject

    文档中心

    对象存储 OSS：PutObject

    更新时间：Sep 02, 2024

    调用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支持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下载到浏览器指定路径时：

    说明

    • 如果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下载失败。若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

    字符串

    否

    D41D8CD98F00B204E9800998ECF8****

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

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

    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：标准存储

      说明

      在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。

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

    响应头

    名称

    类型

    示例值

    描述

    Content-MD5

    字符串

    1B2M2Y8AsgTpgAmY7PhC****

    表示文件的MD5值。

    重要

    文件的MD5值指的是客户端上传完成后获取到的文件MD5，并非响应体的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: OSS qn6q**************:77Dv****************
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-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 qn6q**************:77Dv**************** 
[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: OSS qn6q**************:77Dv****************

      返回示例 

      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的值无效。

    取值：AES256、KMS。

    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来禁止覆盖同名文件，但是Bucket中已有同名文件。

    • Bucket开启了分层命名空间功能，且当前目录层级已有同名目录。

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