View a markdown version of this page

POST 物件 - Amazon Simple Storage Service
說明要求範例相關資源

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

POST 物件

說明

POST 操作會使用 HTML 表單將物件新增至指定的儲存貯體。 POST 是 的替代形式PUT，可啟用瀏覽器型上傳，做為將物件放入儲存貯體的方式。PUT 透過 HTTP 標頭傳遞至 的參數，會改為在分段/表單編碼訊息內文POST中以表單欄位形式傳遞至 。若要將物件新增至儲存貯體，您必須在儲存貯體上具有WRITE存取權。Amazon S3 絕不會存放部分物件。如果您收到成功的回應，您可以確信儲存了整個物件。

Amazon S3 是分散式系統。除非您已啟用儲存貯體的版本控制，否則如果 Amazon S3 同時收到相同物件的多個寫入請求，則只會儲存最後一個寫入的物件版本。

若要確保資料在周遊網路時不會損毀，請使用 Content-MD5 表單欄位。當您使用此表單欄位時，Amazon S3 會根據提供的 MD5 值檢查物件。如果不相符，Amazon S3 會傳回錯誤。此外，您可以在將物件發佈至 Amazon S3 時計算 MD5 值，並將傳回的 ETag 與計算的 MD5 值進行比較。ETag 僅反映物件內容的變更，而不是其中繼資料。

注意

若要設定應用程式在傳送請求內文之前傳送請求標頭，請使用 HTTP 狀態碼 100 （繼續）。對於 POST操作，如果根據標頭拒絕訊息 （例如，因為身分驗證失敗或重新導向），使用此狀態碼可協助您避免傳送訊息內文。如需 HTTP 狀態碼 100 （繼續） 的詳細資訊，請前往 http://www.ietf.org/rfc/rfc2616.txt：// 的第 8.2.3 節。

Amazon S3 會自動加密上傳到 S3 儲存貯體的所有新物件。上傳物件的加密設定取決於目的地儲存貯體的預設加密組態。根據預設，所有儲存貯體的預設加密組態都是使用 Amazon S3 受管金鑰的伺服器端加密 (SSE-S3)。

如果目的地儲存貯體的加密組態使用伺服器端加密搭配 AWS Key Management Service (AWS KMS) 金鑰 (SSE-KMS)、雙層伺服器端加密搭配 AWS KMS 金鑰 (DSSE-KMS) 或客戶提供的加密金鑰 (SSE-C)，Amazon S3 會使用對應的 KMS 金鑰或客戶提供的金鑰來加密上傳的物件。上傳物件時，如果您想要變更上傳物件的加密設定，您可以指定伺服器端加密的類型。您可以設定 SSE-S3、SSE-KMS、DSSE-KMS 或 SSE-C。 如需詳細資訊，請參閱《Amazon Simple Storage Service 使用者指南》中的使用伺服器端加密保護資料。

重要

建構請求時，請確定 file 欄位是表單中的最後一個欄位。

要求

語法

POST / HTTP/1.1
Host: destinationBucket.s3.amazonaws.com
User-Agent: browser_data
Accept: file_types
Accept-Language: Regions
Accept-Encoding: encoding
Accept-Charset: character_set
Keep-Alive: 300
Connection: keep-alive
Content-Type: multipart/form-data; boundary=9431149156168
Content-Length: length

--9431149156168
Content-Disposition: form-data; name="key"

acl
--9431149156168
Content-Disposition: form-data; name="tagging"

<Tagging><TagSet><Tag><Key>Tag Name</Key><Value>Tag Value</Value></Tag></TagSet></Tagging>
--9431149156168
Content-Disposition: form-data; name="success_action_redirect"

success_redirect
--9431149156168
Content-Disposition: form-data; name="Content-Type"

content_type
--9431149156168
Content-Disposition: form-data; name="x-amz-meta-uuid"

uuid
--9431149156168
Content-Disposition: form-data; name="x-amz-meta-tag"

metadata
--9431149156168
Content-Disposition: form-data; name="AWSAccessKeyId"

access-key-id
--9431149156168
Content-Disposition: form-data; name="Policy"

encoded_policy
--9431149156168
Content-Disposition: form-data; name="Signature"

signature=
--9431149156168
Content-Disposition: form-data; name="file"; filename="MyFilename.jpg"
Content-Type: image/jpeg

file_content
--9431149156168
Content-Disposition: form-data; name="submit"

Upload to Amazon S3
--9431149156168--

請求參數

此實作操作不使用請求參數。

表單欄位

此操作可以使用下列表單欄位。

名稱 描述 必要
AWSAccessKeyId

儲存貯體擁有者的 AWS 存取金鑰 ID，其會針對滿足政策中一組限制的請求授予匿名使用者存取。

類型：字串

預設：無

限制條件：如果請求中包含政策文件，則為必要。

有條件
acl

指定的 Amazon S3 存取控制清單 (ACL)。如果指定的 ACL 無效，則會產生錯誤。如需 ACLs的詳細資訊，請參閱《Amazon Simple Storage Service 使用者指南》中的存取控制清單 (ACL) 概觀。

類型：字串

預設值：private

有效值: private | public-read | public-read-write | aws-exec-read | authenticated-read | bucket-owner-read | bucket-owner-full-control

否
Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires

REST 特定的標頭。如需詳細資訊，請參閱 PutObject。

類型：字串

預設：無

否
file

檔案或文字內容。

檔案或文字內容必須是表單中的最後一個欄位。

您無法一次上傳多個檔案。

類型：檔案或文字內容

預設：無

是
key

上傳的金鑰名稱。

若要使用使用者提供的檔案名稱，請使用 ${filename}變數。例如，如果名為 Mary 的使用者上傳檔案，example.jpg而您指定 /user/mary/${filename}，則金鑰名稱為 /user/mary/example.jpg。

如需詳細資訊，請參閱《Amazon Simple Storage Service 使用者指南》中的物件金鑰和中繼資料。

類型：字串

預設：無

是
policy

描述請求中允許內容的安全政策。沒有安全政策的請求會被視為匿名，並且僅適用於可公開寫入的儲存貯體。如需詳細資訊，請參閱《Amazon Simple Storage Service 使用者指南》中的 HTML 表單和上傳範例。

類型：字串

預設：無

限制條件：如果儲存貯體無法公開寫入，則需要安全政策。

有條件
success_action_redirect, redirect

用戶端在成功上傳時重新導向的 URL。

若未指定 success_action_redirect，Amazon S3 會傳回 success_action_status 欄位中所指定的空白文件類型。

如果 Amazon S3 無法解譯 URL，就好像 欄位不存在一樣。

如果上傳失敗，Amazon S3 會顯示錯誤，而不會將使用者重新導向至 URL。

類型：字串

預設：無

注意

redirect 欄位名稱已棄用，未來將移除對redirect欄位名稱的支援。

否
success_action_status

如果您未指定 success_action_redirect，狀態碼會在上傳成功時傳回給用戶端。

此欄位接受值 200、 201或 204（預設值）。

如果值設定為 200或 204，Amazon S3 會傳回狀態碼為 200 或 204 的空白文件。

如果值設定為 201，Amazon S3 會傳回狀態碼為 201 的 XML 文件。

如果未設定 值，或將其設定為無效的值，Amazon S3 會傳回狀態碼為 204 的空白文件。

類型：字串

預設：無

否
tagging

要新增至物件的指定標籤集。若要新增標籤，請使用下列編碼方案。

<Tagging>
  <TagSet>
    <Tag>
      <Key>TagName</Key>
      <Value>TagValue</Value>
    </Tag>
    ...
  </TagSet>
</Tagging>

如需詳細資訊，請參閱《Amazon Simple Storage Service 使用者指南》中的物件標記。

類型：字串

預設：無

否
x-amz-storage-class

用於存放物件的儲存類別。如果您未指定類別，Amazon S3 會使用預設儲存類別 STANDARD。Amazon S3 支援其他儲存類別。如需詳細資訊，請參閱《Amazon Simple Storage Service 使用者指南》中的儲存類別。

類型：字串

預設：STANDARD

有效值：REDUCED_REDUNDANCY | EXPRESS_ONEZONE | DEEP_ARCHIVE | GLACIER | GLACIER_IR | INTELLIGENT_TIERING | ONEZONE_IA | STANDARD | STANDARD_IA

否
x-amz-meta-*

以此字首開頭的標頭是使用者定義的中繼資料。每個項目都會儲存並傳回為一組索引鍵/值組。Amazon S3 不會驗證或解譯使用者定義的中繼資料。如需詳細資訊，請參閱 PutObject。

類型：字串

預設：無

否
x-amz-security-token

Amazon DevPay 安全性字符。

每個使用 Amazon DevPay 的請求都需要兩個 x-amz-security-token 表單欄位：一個表示產品字符，另一個表示使用者字符。

類型：字串

預設：無

否
x-amz-signature

(AWS 簽章版本 4) 安全政策的 HMAC-SHA256 雜湊。

類型：字串

預設：無

有條件
x-amz-website-redirect-location

如果儲存貯體設定為網站，此欄位會將此物件的請求重新導向至相同儲存貯體中的另一個物件或外部 URL。Amazon S3 會將此標頭的值儲存在物件中繼資料中。如需有關物件中繼資料的資訊，請參閱《Amazon Simple Storage Service 使用者指南》中的物件金鑰和中繼資料。

在下列範例中，請求標頭會將重新導向設定為相同儲存貯體中的物件 (anotherPage.html)：

x-amz-website-redirect-location: /anotherPage.html

在下列範例中，請求標頭會將物件重新導向設定為另一個網站：

x-amz-website-redirect-location: http://www.example.com/

如需在 Amazon S3 中託管網站的詳細資訊，請參閱《Amazon Simple Storage Service 使用者指南》中的在 Amazon S3 上託管網站以及如何設定網站頁面重新導向。

類型：字串

預設：無

限制條件：值必須以 /、 http://或 為字首https://。值的長度限制為 2 KB。

 否

其他檢查總和申請表欄位

上傳物件時，您可以指定要用來驗證資料完整性的各種檢查總和。您可以指定一個額外的檢查總和演算法供 Amazon S3 使用。如需其他檢查總和值的詳細資訊，請參閱《Amazon Simple Storage Service 使用者指南》中的檢查物件完整性。

名稱 描述 必要
x-amz-checksum-algorithm

指出用來建立物件檢查總和的演算法。如果指定了值，您必須包含相符的檢查總和標頭。否則，您的請求會產生 400 錯誤。

可能的值包括 CRC32、CRC32C、SHA1 與 SHA256。

 否
x-amz-checksum-crc32

指定物件的 base64 編碼、32 位元 CRC32 檢查總和。

如果 的值x-amz-checksum-algorithm為 ，則需要此參數CRC32。

 有條件
x-amz-checksum-crc32c

指定物件的 base64 編碼、32 位元 CRC32C 檢查總和。

如果 的值x-amz-checksum-algorithm為 ，則需要此參數CRC32C。

 有條件
x-amz-checksum-sha1

指定物件的 base64 編碼、160 位元 SHA-1 摘要。

如果 的值x-amz-checksum-algorithm為 ，則需要此參數SHA1。

 有條件
x-amz-checksum-sha256

指定物件的 base64 編碼、256 位元 SHA-256 摘要。

如果 的值x-amz-checksum-algorithm為 ，則需要此參數SHA256。

 有條件

伺服器端加密特定請求表單欄位

伺服器端加密是靜態資料加密。Amazon S3 會在將資料寫入 AWS 資料中心的磁碟時加密資料，並在您存取資料時解密資料。上傳物件時，您可以指定您希望 Amazon S3 用來加密物件的伺服器端加密類型。

伺服器端加密有四種類型：

  • 使用 Amazon S3 受管金鑰 (SSE-S3) 的伺服器端加密 – 從 2022 年 5 月開始，所有 Amazon S3 儲存貯體預設都會設定加密。伺服器端加密的預設選項是使用 SSE-S3。每個物件都使用不重複的金鑰加密。SSE-S3 使用定期輪換的根金鑰自行加密金鑰，提供額外的防護。SSE-S3 使用目前最強大的其中一種區塊加密法 (256 位元進階加密標準 (AES-256))，加密您的資料。

  • 伺服器端加密與 AWS KMS 金鑰 (SSE-KMS) – SSE-KMS 透過整合 AWS KMS 服務與 Amazon S3 來提供。使用 AWS KMS，您可以更好地控制您的金鑰。例如，您可以檢視個別金鑰、編輯控制政策，並遵循 AWS CloudTrail中的金鑰。此外，您可以建立和管理客戶受管金鑰，或是使用您、您服務和您區域唯一的 AWS 受管金鑰 。

  • 使用 AWS KMS 金鑰的雙層伺服器端加密 (DSSE-KMS) – 使用 AWS KMS keys (DSSE-KMS) 的雙層伺服器端加密類似於 SSE-KMS，但會套用兩個個別的物件層級加密，而不是一層。

  • 伺服器端加密搭配客戶提供的金鑰 (SSE-C) – 透過 SSE-C，您可以管理加密金鑰，Amazon S3 會在寫入磁碟時管理加密，並在您存取物件時管理解密。

    注意

    如果您的一般用途儲存貯體封鎖了客戶提供的金鑰 (SSE-C) 的伺服器端加密，則在將新資料寫入儲存貯體時，當您指定 SSE-C 請求標頭時，將會收到 HTTP 403 存取遭拒錯誤。如需詳細資訊，請參閱一般用途儲存貯體的封鎖或取消封鎖 SSE-C。

如需詳細資訊，請參閱《Amazon Simple Storage Service 使用者指南》中的使用伺服器端加密保護資料。

根據您要使用的伺服器端加密類型，指定下列表單欄位。

  • 使用 SSE-S3、SSE-KMS 或 DSSE-KMS – 如果您想要使用這些類型的伺服器端加密，請在請求中指定下列表單欄位。

    名稱 描述 必要
    x-amz-server-side-encryption

    指定 Amazon S3 建立物件時要使用的伺服器端加密演算法。若要使用 SSE-S3，請指定 AES256。若要使用 SSE-KMS，請指定 aws:kms。若要使用 DSSE-KMS，請指定 aws:kms:dsse。

    類型：字串

    有效值：aws:kms、AES256、 aws:kms:dsse

    		 是
    x-amz-server-side-encryption-aws-kms-key-id

    如果x-amz-server-side-encryption標頭的有效值為 aws:kms或 aws:kms:dsse，此標頭會指定 AWS KMS key 用來加密物件的 ID。

    類型：字串

    		 是，如果 的值x-amz-server-side-encryption是 aws:kms或 aws:kms:dsse
    x-amz-server-side-encryption-context

    如果 x-amz-server-side-encryption的有效值為 aws:kms或 aws:kms:dsse，則此標頭會指定物件的加密內容。此標頭的值是 base64 編碼的 UTF-8 字串，其中包含加密內容的 JSON 格式金鑰值對。

    類型：字串

    		 否
    x-amz-server-side-encryption-bucket-key-enabled

    如果 x-amz-server-side-encryption的有效值為 aws:kms或 aws:kms:dsse，此標頭會指定 Amazon S3 是否應使用 S3 儲存貯體金鑰搭配 SSE-KMS 或 DSSE-KMS。將此標頭設定為 true 會導致 Amazon S3 使用 S3 儲存貯體金鑰進行 SSE-KMS 或 DSSE-KMS 的物件加密。

    類型：布林值

    		 否
    注意

    如果您指定 x-amz-server-side-encryption:aws:kms或 x-amz-server-side-encryption:aws:kms:dsse，但未提供 x-amz-server-side-encryption-aws-kms-key-id，Amazon S3 會使用 AWS 受管金鑰 (aws/S3) 來保護資料。

  • 使用 SSE-C – 如果您想要管理自己的加密金鑰，您必須在請求中提供下列所有表單欄位。

    注意

    如果您使用 SSE-C，Amazon S3 在回應中傳回ETag的值不是物件的 MD5。

    名稱 描述 必要
    x-amz-server-side-encryption-customer-algorithm

    指定加密物件時要使用的演算法。

    類型：字串

    預設：無

    有效值： AES256

    限制條件：必須隨附有效的 x-amz-server-side-encryption-customer-key和 x-amz-server-side-encryption-customer-key-MD5 欄位。

    		 是
    x-amz-server-side-encryption-customer-key

    指定客戶提供的 base64 編碼加密金鑰，讓 Amazon S3 用於加密資料。此值用於存放物件，然後將其捨棄。Amazon 不會存放加密金鑰。金鑰必須適合與 x-amz-server-side-encryption-customer-algorithm標頭中指定的演算法搭配使用。

    類型：字串

    預設：無

    限制條件：必須隨附有效的 x-amz-server-side-encryption-customer-algorithm和 x-amz-server-side-encryption-customer-key-MD5 欄位。

    		 是
    x-amz-server-side-encryption-customer-key-MD5

    根據 RFC 1321 指定加密金鑰的 base64 編碼 128 位元 MD5 摘要。Amazon S3 使用此標頭進行訊息完整性檢查，以確保加密金鑰的傳輸沒有錯誤。

    類型：字串

    預設：無

    限制條件：必須隨附有效的 x-amz-server-side-encryption-customer-algorithm和 x-amz-server-side-encryption-customer-key 欄位。

    		 是

回應

回應標頭

除了所有回應通用的回應標頭之外，此操作的實作還可以包含下列回應標頭。如需詳細資訊，請參閱常見回應標頭。

名稱 描述
x-amz-checksum-crc32

物件的 base64 編碼、32 位元 CRC32 檢查總和。

類型：字串
x-amz-checksum-crc32c

物件的 base64 編碼、32 位元 CRC32C 檢查總和。

類型：字串
x-amz-checksum-sha1

物件的 base64 編碼、160 位元 SHA-1 摘要。

類型：字串
x-amz-checksum-sha256

物件的 base64 編碼、256 位元 SHA-256 摘要。

類型：字串
x-amz-expiration

如果已為物件設定Expiration動作做為儲存貯體生命週期組態的一部分，Amazon S3 會傳回此標頭。 標頭值包含 expiry-date元件和 URL 編碼rule-id元件。 對於已啟用版本的儲存貯體，此標頭僅適用於目前的版本。Amazon S3 不提供標頭來指出非目前版本何時符合永久刪除的資格。如需詳細資訊，請參閱 PutBucketLifecycleConfiguration。

類型：字串
success_action_redirect, redirect

用戶端在成功上傳時重新導向到的 URL。

類型：字串

Ancestor：PostResponse
x-amz-server-side-encryption

在 Amazon S3 中存放此物件時所使用的伺服器端加密演算法 （例如，、AES256aws:kms、aws:kms:dsse)。

類型：字串
x-amz-server-side-encryption-aws-kms-key-id

如果x-amz-server-side-encryption標頭的有效值為 aws:kms，此標頭會指定用來加密物件的 KMS 金鑰 ID。

類型：字串
x-amz-server-side-encryption-bucket-key-enabled

如果 x-amz-server-side-encryption的有效值為 aws:kms，此標頭會指出物件是否使用 S3 儲存貯體金鑰以 SSE-KMS 加密。如果此標頭設定為 true，物件會使用 S3 儲存貯體金鑰搭配 SSE-KMS。

類型：布林值
x-amz-server-side-encryption-customer-algorithm

如果請求 SSE-C，回應會包含此標頭，確認使用的加密演算法。

類型：字串

有效值:AES256
x-amz-server-side-encryption-customer-key-MD5

如果請求 SSE-C，回應會包含此標頭，以驗證客戶提供加密金鑰的往返訊息完整性。

類型：字串
x-amz-version-id

物件的版本。

類型：字串

回應元素

名稱 描述
Bucket

物件存放所在的儲存貯體名稱。

類型：字串

Ancestor：PostResponse
ETag

實體標籤 (ETag) 是 物件的 MD5 雜湊，您可以使用If-Modified請求標籤搭配GET請求GET操作來執行條件式操作。 只會ETag反映物件內容的變更，而不會反映至其中繼資料。

類型：字串

Ancestor：PostResponse
Key

物件金鑰名稱。

類型：字串

Ancestor：PostResponse
Location

物件的 URI。

類型：字串

Ancestor：PostResponse

特殊錯誤

此操作的實作不會傳回特殊錯誤。如需 Amazon S3 錯誤和錯誤代碼清單的一般資訊，請參閱錯誤回應。

範例

請求範例

POST /Neo HTTP/1.1
Content-Length: 4
Host: quotes.s3.amazonaws.com
Date: Wed, 01 Mar  2006 12:00:00 GMT
Authorization: authorization string
Content-Type: text/plain
Expect: the 100-continue HTTP status code

ObjectContent

暫停版本控制的回應範例

以下是儲存貯體版本控制暫停時的回應範例：

HTTP/1.1 100 Continue
HTTP/1.1 200 OK
x-amz-id-2: LriYPLdmOdAiIfgSm/F1YsViT1LW94/xUQxMsF7xiEb1a0wiIOIxl+zbwZ163pt7
x-amz-request-id: 0A49CE4060975EAC
x-amz-version-id: default
Date: Wed, 12 Oct 2009 17:50:00 GMT
ETag: "1b2cf535f27731c974343645a3985328"
Content-Length: 0
Connection: close
Server: AmazonS3

在此回應中，版本 ID 為 null。

啟用版本控制的範例回應

以下是啟用儲存貯體版本控制時的範例回應。

HTTP/1.1 100 Continue
HTTP/1.1 200 OK
x-amz-id-2: LriYPLdmOdAiIfgSm/F1YsViT1LW94/xUQxMsF7xiEb1a0wiIOIxl+zbwZ163pt7
x-amz-request-id: 0A49CE4060975EAC
x-amz-version-id: 43jfkodU8493jnFJD9fjj3HHNVfdsQUIFDNsidf038jfdsjGFDSIRp
Date: Wed, 01 Mar  2006 12:00:00 GMT
ETag: "828ef3fdfa96f00ad9f27c383fc9ac7f"
Content-Length: 0
Connection: close
Server: AmazonS3