全部產品
Search

搜尋本產品

    Object Storage Service：PutObject

    文件中心

    Object Storage Service：PutObject

    更新時間：Oct 25, 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：Archive Storage

    • ColdArchive：冷Archive Storage

    • DeepColdArchive：深度冷Archive Storage

      重要

      如果要上傳的檔案數量較多，直接指定上傳的檔案類型為深度冷歸檔類型會造成較高的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

    • 帶有Archive Storage類型

      請求樣本

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