調用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 qn6q**************:77Dv**************** | 表示請求本身已被授權。 關于Authorization計算方法的更多信息，請參見在Header中包含簽名。 通常情況下Authorization是必選請求頭，但如果采用了URL包含簽名，則不用攜帶該請求頭。更多信息，請參見在URL中包含簽名。 默認值：無 |
Cache-Control | 字符串 | 否 | no-cache | 指定該Object被下載時網頁的緩存行為。取值如下：
默認值：無 |
Content-Disposition | 字符串 | 否 | attachment | 指定Object的展示形式。取值如下：
將Object下載到瀏覽器指定路徑時： 說明
通過文件URL訪問文件時是預覽還是以附件形式下載，與文件所在Bucket的創建時間、OSS開通時間以及使用的域名類型有關。更多信息，請參見通過文件URL訪問文件無法預覽而是以附件形式下載？。 默認值：無 |
Content-Encoding | 字符串 | 否 | identity | 聲明Object的編碼方式。您需要按照Object 的實際編碼類型填寫，否則可能造成客戶端（瀏覽器）解析編碼失敗或Object下載失敗。若Object未編碼，請置空此項。取值如下：
默認值：無 |
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的內容。
說明 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請求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托管的用戶主密鑰。 此選項僅在x-oss-server-side-encryption為KMS時有效。 說明 在OSS ON云盒使用場景中，不支持使用此選項。 |
x-oss-object-acl | 字符串 | 否 | default | 指定OSS創建Object時的訪問權限。 取值：
關于訪問權限的更多信息，請參見設置Object ACL。 |
x-oss-storage-class | 字符串 | 否 | Standard | 指定Object的存儲類型。 對于任意存儲類型的Bucket，如果上傳Object時指定此參數，則此次上傳的Object將存儲為指定的類型。例如在IA類型的Bucket中上傳Object時，如果指定x-oss-storage-class為Standard，則該Object直接存儲為Standard。 取值：
更多信息，請參見存儲類型介紹。 |
x-oss-meta-* | 字符串 | 否 | x-oss-meta-location | 使用PutObject接口時，如果配置以x-oss-meta-為前綴的參數，則該參數視為元數據，例如 元數據支持短劃線（-）、數字、英文字母（a~z）。英文字符的大寫字母會被轉成小寫字母，不支持下劃線（_）在內的其他字符。 |
x-oss-tagging | 字符串 | 否 | TagA=A&TagB=B | 以鍵值對（Key-Value）的形式指定Object的標簽信息，可同時設置多個標簽，例如 說明 Key和Value需進行URL編碼。其中，Key為必選項，Value為可選項，即Object標簽信息可設置為 |
此接口還需要包含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或SM4。 |
AccessDenied | 403 | 添加Object時，用戶對設置的Bucket沒有訪問權限。 |
NoSuchBucket | 404 | 添加Object時，設置的Bucket不存在。 |
InvalidObjectName | 400 | 傳入的Object key長度大于1023字節。 |
InvalidArgument | 400 | 返回該錯誤的可能原因如下：
|
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中攜帶 |
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);