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使用說明
單次上傳檔案大小限制為5GB。若需上傳大於5GB的檔案，應使用分區上傳功能。
上傳同名檔案時，預設覆蓋原有檔案並返回200 OK狀態代碼。通過設定禁止覆蓋參數可避免意外覆蓋重要檔案。
OSS採用扁平化儲存結構，無傳統檔案系統的目錄概念。通過建立以正斜線（/）結尾的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下載時的緩衝行為。取值如下：
預設值：無 |
Content-Disposition | 字串 | 否 | attachment | 指定Object的展示形式。取值如下：
將Object下載到瀏覽器指定路徑時： 說明
通過檔案URL訪問檔案時是預覽還是以附件形式下載，與檔案所在Bucket的建立時間、OSS開通時間以及使用的網域名稱類型有關。更多資訊，請參見通過檔案URL訪問檔案無法預覽而是以附件形式下載？。 預設值：無 |
Content-Encoding | 字串 | 否 | identity | 聲明Object的編碼方式。必須按照Object的實際編碼類別型填寫，否則可能造成用戶端解析失敗或下載失敗。若Object未編碼，請置空此項。取值如下：
預設值：無 |
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請求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託管的使用者主要金鑰ID。 此選項僅在x-oss-server-side-encryption為KMS時有效。 |
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標籤資訊可設定為 |
更多公用要求標頭資訊請參見公用回應標頭（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。 |
AccessDenied | 403 | 添加Object時，使用者對設定的Bucket沒有存取權限。 |
NoSuchBucket | 404 | 添加Object時，設定的Bucket不存在。 |
InvalidObjectName | 400 | Object名稱不符合規範，包括未指定Object名稱、Object名稱超出長度限制、指定的Object名稱無效。 |
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 | 返回該錯誤的可能原因如下：
|
FileImmutable | 409 | Bucket中的資料處於被保護狀態時，如果嘗試刪除或修改相應資料，則返回該錯誤。 |
整合方式
常見問題
如何修改已上傳檔案的中繼資料？
支援通過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);