上傳物件 - Amazon Simple Storage Service

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

上傳物件

當您將檔案上傳至 Amazon S3 時,該檔案會另存為 S3 物件。物件是由檔案資料與說明物件的中繼資料所組成。儲存貯體中可以有不限數目的物件。您需要儲存貯體的寫入許可,才能將檔案上傳至 Amazon S3 儲存貯體。如需存取許可的詳細資訊,請參閱「適用於 Amazon S3 的 Identity and Access Management」。

您可以將任何檔案類型 (影像、備份、資料、影片等) 上傳至 S3 儲存貯體。使用 Amazon S3 主控台可上傳的檔案大小上限為 160 GB。若要上傳大於 160 GB 的檔案,請使用 AWS Command Line Interface (AWS CLI)、 AWS 開發套件或 Amazon S3 REST API。

如果上傳物件的金鑰名稱已存在於啟用版本控制的儲存貯體中,Amazon S3 會建立另一個物件版本,而不是取代現有的物件。如需版本控制的詳細資訊,請參閱「使用 S3 主控台」。

視上傳資料大小之不同,Amazon S3 提供下列選項:

  • 使用 AWS SDK、REST API 在單一作業中上傳物件,或 AWS CLI— 透過單一PUT作業,您可以上傳大小最多 5 GB 的單一物件。

  • 使用 Amazon S3 主控台上傳單一物件 – 使用 Amazon S3 主控台,您可以上傳大小最多 160 GB 的單一物件。

  • 使用 AWS SDK、REST API 分部分上傳物件,或 AWS CLI 使用多部分上傳 API 作業,您可以上傳單一大型物件,大小最多可達 5 TB。

    分段上傳 API 操作是專為改善較大型物件上傳體驗所設計。您可以上傳零件中的物件。這些物件部分可個別、依任何順序以及同時上傳。您可以為大小介於 5 MB 到 5 TB 之間的物件使用分段上傳。如需詳細資訊,請參閱「使用分段上傳來上傳和複製物件」。

上傳物件時,根據預設,物件使用伺服器端加密與 Amazon S3 受管金鑰 (SSE-S3) 進行自動加密。當您下載物件時,該物件會解密。如需詳細資訊,請參閱 對 Amazon S3 儲存貯體設定預設伺服器端加密行為使用加密來保護資料

上傳物件時,若您想要使用不同類型的預設加密,也可以在 S3 PUT 請求中使用 AWS Key Management Service (AWS KMS) 金鑰 (SSE-KMS) 指定伺服器端加密,或在目標儲存貯體中設定預設加密組態,以使用 SSE-KMS 加密資料。如需 SSE-KMS 的詳細資訊,請參閱「使用 AWS KMS (SSE-KMS) 指定伺服器端加密」。若您想要使用其他帳戶的 KMS 金鑰,您必須具有該金鑰的使用權限。如需詳細了解 KMS 金鑰跨帳戶權限,請參閱《AWS Key Management Service 開發人員指南》中的建立其他帳戶可使用的 KMS 金鑰

如果您在 Amazon S3 中遇到「拒絕存取」(403 禁止) 錯誤,請參閱針對 Amazon S3 中的拒絕存取 (403 禁止) 錯誤進行疑難排解以進一步了解其常見原因。

此程序說明如何使用主控台,將物件和資料夾上傳至 Amazon S3 儲存貯體。

上傳物件時,物件索引鍵名稱為檔案名稱加上任何選擇性的字首。在 Amazon S3 主控台中,您可以建立資料夾來整理物件。在 Amazon S3 中,資料夾表示為物件索引鍵名稱中的字首。如果您在 Amazon S3 主控台中將個別物件上傳到資料夾,則物件索引鍵名稱中會包含該資料夾名稱。

例如,如果您將名為 sample1.jpg 的物件上傳到名為 backup 的資料夾,則索引鍵名稱為 backup/sample1.jpg。不過,此物件在主控台中會顯示為 sample1.jpg 資料夾中的 backup。如需金鑰名稱的詳細資訊,請參閱「使用物件中繼資料」。

注意

如果您在 Amazon S3 主控台中重新命名物件或變更物件的任何屬性 (例如儲存類別加密中繼資料),則會建立新物件來取代舊的物件。如果啟用 S3 版本控制,則系統會建立物件的新版本,且現有物件會變成較舊的版本。變更屬性的角色也會成為新物件 (或物件版本) 的擁有者。

當您上傳資料夾時,Amazon S3 會將指定資料夾中的所有檔案與子資料夾上傳至您的儲存貯體。然後會指派一個由已上傳檔案名稱與資料夾名稱所組成的物件金鑰名稱。例如,如果您上傳一個名為 /images 的資料夾,其中包含兩個檔案 sample1.jpgsample2.jpg,Amazon S3 會上傳檔案,然後指派對應的索引鍵名稱 images/sample1.jpgimages/sample2.jpg。金鑰名稱包含資料夾名稱作為字首。Amazon S3 主控台只會顯示最後一個 / 後面的金鑰名稱部分。例如,在 images 資料夾中,images/sample1.jpgimages/sample2.jpg 物件會顯示為 sample1.jpgsample2.jpg

將資料夾和檔案上傳至 S3 儲存貯體
  1. 登入 AWS Management Console 並開啟 Amazon S3 主控台,網址為 https://console.aws.amazon.com/s3/

  2. 在左側導覽窗格中,選擇 Buckets (儲存貯體)。

  3. Buckets (儲存貯體) 清單中,選擇您要上傳資料夾或檔案的目標儲存貯體名稱。

  4. 選擇 Upload (上傳)。

  5. Upload (上傳) 視窗中,執行下列其中一個操作:

    • 將檔案和資料夾拖放至 Upload (上傳) 視窗。

    • 選擇新增檔案新增資料夾,選擇要上傳的檔案或資料夾,然後選擇開啟

  6. 若要啟用多版本設定,請在 Destination (目的地) 下選擇 Enable Bucket Versioning (啟用儲存貯體版本控制)。

  7. 若要上傳列出的檔案和資料夾,而不設定其他上傳選項,請選擇頁面底部的 Upload (上傳)。

    Amazon S3 會上傳您的物件和資料夾。上傳完成後,您可以在上傳:狀態頁面上看到成功訊息。

設定其他物件屬性
  1. 若要變更存取控制清單許可,請選擇Permissions (許可)。

  2. 存取控制清單 (ACL)中,編輯許可。

    如需物件存取許可的資訊,請參閱「使用 S3 主控台來設定物件的 ACL 許可」。您可以針對您上傳的所有檔案,將物件的讀取存取許可授予大眾 (全世界的所有人)。但是,建議不要變更公有讀取存取的預設設定。授予公有讀取存取適用於一小部分的使用情況,例如當儲存貯體用於網站時。您一律可以在上傳物件之後變更物件許可。

  3. 若要設定其他附加屬性,請選擇Properties (屬性)。

  4. 儲存類別下,選擇您要上傳的檔案的儲存類別。

    如需儲存體方案的詳細資訊,請參閱「使用 Amazon S3 儲存體方案」。

  5. 若要更新物件的加密設定,請在 Server-side encryption settings (伺服器端加密設定) 下,執行下列操作。

    1. 選擇 Specify an encryption key (指定加密金鑰)。

    2. 加密設定底下,選擇使用預設加密的儲存貯體設定覆寫預設加密的儲存貯體設定

    3. 若您選擇覆寫預設加密的儲存貯體設定,則您必須設定下列加密設定。

      • 若要使用 Amazon S3 管理的金鑰加密上傳的檔案,請選擇 Amazon S3 受管金鑰 (SSE-S3)

        如需詳細資訊,請參閱 使用 Amazon S3 受管金鑰 (SSE-S3) 進行伺服器端加密

      • 若要使用 AWS Key Management Service () 中儲存的金鑰加密上傳的檔案,請選擇金AWS Key Management Service 鑰 (SSE-KMS AWS KMS)。然後針對 AWS KMS 金鑰,選擇下列其中一個選項:

        • 若要從可用的 KMS 金鑰清單中選擇,請選擇從 AWS KMS keys中選擇,然後從可用金鑰清單中選擇您的 KMS 金鑰

          AWS 受管金鑰 (aws/s3) 和您的客戶管理金鑰都會出現在此清單中。如需詳細了解客戶受管金鑰,請參閱《AWS Key Management Service 開發人員指南》中的客戶金鑰和 AWS 金鑰

        • 若要輸入 KMS 金鑰 ARN,請選擇 [輸入 AWS KMS key ARN],然後在出現的欄位中輸入您的 KMS 金鑰 ARN。

        • 若要在 AWS KMS 主控台中建立新的客戶管理金鑰,請選擇 [建立 KMS 金鑰]。

          如需有關建立金鑰的詳細資訊 AWS KMS key,請參閱AWS Key Management Service 開發人員指南中的建立金鑰

        重要

        您只能使用與值區相同 AWS 區域 的 KMS 金鑰。Amazon S3 主控台僅會列出與儲存貯體位於相同區域的前 100 個 KMS 金鑰。若要使用未列出的 KMS 金鑰,必須輸入 KMS 金鑰 ARN。若您想要使用其他帳戶的 KMS 金鑰,您必須先具有該金鑰的使用權限,然後輸入 KMS 金鑰 ARN。

        Amazon S3 僅支援對稱加密 KMS 金鑰,而不支援非對稱 KMS 金鑰。如需詳細資訊,請參閱《AWS Key Management Service 開發人員指南》中的識別對稱和非對稱 KMS 金鑰

  6. 若要使用額外的檢查總和,請選擇 On (開啟)。然後為 檢查總和函數,選擇您要使用的函數。Amazon S3 在接收完整物件後計算並存儲檢查總和的值。您可以使用 預先計算的值 方塊以提供預先計算的值。如果您這樣做,Amazon S3 會將您提供的值與其計算的值進行比較。如果兩個值不匹配,Amazon S3 將產生錯誤。

    通過額外的檢查總和,您可以指定要用於驗證資料的檢查總合演算法。如需額外的檢查總和詳細資訊,請參閱「檢查物件完整性」。

  7. 若要將標籤新增至您要上傳的所有物件,請選擇 Add tag (新增標籤)。在金鑰欄位中輸入標籤名稱。輸入標籤值。

    物件標記提供您一個分類儲存的方法。每個標籤都是金鑰值對。金鑰與標記值皆區分大小寫。每物件最多可有 10 個標籤。標籤金鑰最長可包含 128 個 Unicode 字元;標籤值最長可包含 255 個 Unicode 字元。如需物件標籤的詳細資訊,請參閱 使用標籤分類儲存空間

  8. 若要新增中繼資料,請選擇 Add metadata (新增中繼資料)。

    1. Type (類型) 下,選擇 System defined (系統定義) 或 User defined (使用者定義)。

      對於系統定義的中繼資料,您可以選取常見的 HTTP 標頭,例如 Content-TypeContent-Disposition。如需系統定義的中繼資料清單及是否可新增值的資訊,請參閱「系統定義的物件中繼資料」。以字首 x-amz-meta- 開頭的所有中繼資料都會視為使用者定義的中繼資料。使用者定義的中繼資料會隨著物件一起存放,並在下載物件時傳回。金鑰及其值都必須符合 US-ASCII 標準。使用者定義的中繼資料最大可達 2 KB。如需系統定義與使用者定義中繼資料的詳細資訊,請參閱 「使用物件中繼資料」。

    2. 針對 Key (金鑰) 中,選擇一個金鑰。

    3. 輸入金鑰的值。

  9. 若要上傳物件,請選擇 Upload (上傳)。

    Amazon S3 會上傳您的物件。上傳完成後,您可以在 Upload: status (上傳:狀態) 頁面上看到成功訊息。

  10. 選擇 Exit (退出)

您可以使用 AWS 開發套件在 Amazon S3 上傳物件。SDK 提供包裝函式程式庫,供您輕鬆地上傳資料。如需詳細資訊,請參閱支援的 SDK 清單

以下是幾個選取 SDK 的範例:

.NET

下列 C# 程式碼範例會使用兩個 PutObjectRequest 請求建立兩個物件:

  • 第一個 PutObjectRequest 請求會將文字字串儲存為範例物件資料。它也會指定儲存貯體和物件金鑰名稱。

  • 第二個 PutObjectRequest 請求會指定檔案名稱來上傳檔案。此請求也會指定 ContentType 標頭以及選用的物件中繼資料 (標題)。

如需如何建立及測試工作範例的說明,請參閱「執行 Amazon S3 .NET 程式碼範例」。

using Amazon; using Amazon.S3; using Amazon.S3.Model; using System; using System.Threading.Tasks; namespace Amazon.DocSamples.S3 { class UploadObjectTest { private const string bucketName = "*** bucket name ***"; // For simplicity the example creates two objects from the same file. // You specify key names for these objects. private const string keyName1 = "*** key name for first object created ***"; private const string keyName2 = "*** key name for second object created ***"; private const string filePath = @"*** file path ***"; private static readonly RegionEndpoint bucketRegion = RegionEndpoint.EUWest1; private static IAmazonS3 client; public static void Main() { client = new AmazonS3Client(bucketRegion); WritingAnObjectAsync().Wait(); } static async Task WritingAnObjectAsync() { try { // 1. Put object-specify only key name for the new object. var putRequest1 = new PutObjectRequest { BucketName = bucketName, Key = keyName1, ContentBody = "sample text" }; PutObjectResponse response1 = await client.PutObjectAsync(putRequest1); // 2. Put the object-set ContentType and add metadata. var putRequest2 = new PutObjectRequest { BucketName = bucketName, Key = keyName2, FilePath = filePath, ContentType = "text/plain" }; putRequest2.Metadata.Add("x-amz-meta-title", "someTitle"); PutObjectResponse response2 = await client.PutObjectAsync(putRequest2); } catch (AmazonS3Exception e) { Console.WriteLine( "Error encountered ***. Message:'{0}' when writing an object" , e.Message); } catch (Exception e) { Console.WriteLine( "Unknown encountered on server. Message:'{0}' when writing an object" , e.Message); } } } }
Java

以下範例將建立兩個物件。第一個物件擁有文字字串形式的資料,而第二個物件是一個檔案。該範例會直接在對 AmazonS3Client.putObject() 的呼叫中指定儲存貯體名稱、物件金鑰和文字資料,來建立第一個物件。該範例會使用 PutObjectRequest 指定儲存貯體名稱、物件金鑰和檔案路徑,來建立第二個物件。PutObjectRequest 也會指定 ContentType 標頭和標題中繼資料。

如需建立及測試可行範例的說明,請參閱 測試 Amazon S3 Java 程式碼範例

import com.amazonaws.AmazonServiceException; import com.amazonaws.SdkClientException; import com.amazonaws.regions.Regions; import com.amazonaws.services.s3.AmazonS3; import com.amazonaws.services.s3.AmazonS3ClientBuilder; import com.amazonaws.services.s3.model.ObjectMetadata; import com.amazonaws.services.s3.model.PutObjectRequest; import java.io.File; import java.io.IOException; public class UploadObject { public static void main(String[] args) throws IOException { Regions clientRegion = Regions.DEFAULT_REGION; String bucketName = "*** Bucket name ***"; String stringObjKeyName = "*** String object key name ***"; String fileObjKeyName = "*** File object key name ***"; String fileName = "*** Path to file to upload ***"; try { // This code expects that you have AWS credentials set up per: // https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/setup-credentials.html AmazonS3 s3Client = AmazonS3ClientBuilder.standard() .withRegion(clientRegion) .build(); // Upload a text string as a new object. s3Client.putObject(bucketName, stringObjKeyName, "Uploaded String Object"); // Upload a file as a new object with ContentType and title specified. PutObjectRequest request = new PutObjectRequest(bucketName, fileObjKeyName, new File(fileName)); ObjectMetadata metadata = new ObjectMetadata(); metadata.setContentType("plain/text"); metadata.addUserMetadata("title", "someTitle"); request.setMetadata(metadata); s3Client.putObject(request); } catch (AmazonServiceException e) { // The call was transmitted successfully, but Amazon S3 couldn't process // it, so it returned an error response. e.printStackTrace(); } catch (SdkClientException e) { // Amazon S3 couldn't be contacted for a response, or the client // couldn't parse the response from Amazon S3. e.printStackTrace(); } } }
JavaScript

下列範例會將現有檔案上傳至特定區域的 Amazon S3 儲存貯體。

import { PutObjectCommand, S3Client } from "@aws-sdk/client-s3"; const client = new S3Client({}); export const main = async () => { const command = new PutObjectCommand({ Bucket: "test-bucket", Key: "hello-s3.txt", Body: "Hello S3!", }); try { const response = await client.send(command); console.log(response); } catch (err) { console.error(err); } };
PHP

此範例會引導您使用來自的類別 AWS SDK for PHP 來上傳大小最大為 5 GB 的物件。若是較大的檔案,則必須使用分段上傳 API 操作。如需詳細資訊,請參閱 使用分段上傳來上傳和複製物件

此範例假設您已遵循「使用 AWS SDK for PHP 與執行 PHP 的範例」中的說明進行操作,且已正確安裝 AWS SDK for PHP 。

範例 - 上傳資料以在 Amazon S3 儲存貯體中建立物件

下列 PHP 範例會使用 putObject() 方法上傳資料,以在指定的儲存貯體中建立物件。如需執行本指南中 PHP 範例的資訊,請參閱「執行 PHP 範例」。

require 'vendor/autoload.php'; use Aws\S3\Exception\S3Exception; use Aws\S3\S3Client; $bucket = '*** Your Bucket Name ***'; $keyname = '*** Your Object Key ***'; $s3 = new S3Client([ 'version' => 'latest', 'region' => 'us-east-1' ]); try { // Upload data. $result = $s3->putObject([ 'Bucket' => $bucket, 'Key' => $keyname, 'Body' => 'Hello, world!', 'ACL' => 'public-read' ]); // Print the URL to the object. echo $result['ObjectURL'] . PHP_EOL; } catch (S3Exception $e) { echo $e->getMessage() . PHP_EOL; }
Ruby

AWS SDK for Ruby -版本 3 有兩種將對象上傳到 Amazon S3 的方法。第一個方法使用受管檔案上傳工具,可讓您更輕鬆地從磁碟上傳任意大小的檔案。若要使用受管理的檔案上傳工具方法:

  1. 建立 Aws::S3::Resource 類別的執行個體。

  2. 依儲存貯體名稱與金鑰參考目標物件。物件存在於儲存貯體中,並具有可識別每個物件且不重複的金鑰。

  3. 在物件上呼叫 #upload_file

require "aws-sdk-s3" # Wraps Amazon S3 object actions. class ObjectUploadFileWrapper attr_reader :object # @param object [Aws::S3::Object] An existing Amazon S3 object. def initialize(object) @object = object end # Uploads a file to an Amazon S3 object by using a managed uploader. # # @param file_path [String] The path to the file to upload. # @return [Boolean] True when the file is uploaded; otherwise false. def upload_file(file_path) @object.upload_file(file_path) true rescue Aws::Errors::ServiceError => e puts "Couldn't upload file #{file_path} to #{@object.key}. Here's why: #{e.message}" false end end # Example usage: def run_demo bucket_name = "doc-example-bucket" object_key = "my-uploaded-file" file_path = "object_upload_file.rb" wrapper = ObjectUploadFileWrapper.new(Aws::S3::Object.new(bucket_name, object_key)) return unless wrapper.upload_file(file_path) puts "File #{file_path} successfully uploaded to #{bucket_name}:#{object_key}." end run_demo if $PROGRAM_NAME == __FILE__

第二種方式 AWS SDK for Ruby -第 3 版可以上傳物件使用的#put方法Aws::S3::Object。如果物件是字串或非磁碟上檔案的 I/O 物件,即可使用此方法。若要使用此方法:

  1. 建立 Aws::S3::Resource 類別的執行個體。

  2. 依儲存貯體名稱與金鑰參考目標物件。

  3. 呼叫 #put,傳入字串或 I/O 物件。

require "aws-sdk-s3" # Wraps Amazon S3 object actions. class ObjectPutWrapper attr_reader :object # @param object [Aws::S3::Object] An existing Amazon S3 object. def initialize(object) @object = object end def put_object(source_file_path) File.open(source_file_path, "rb") do |file| @object.put(body: file) end true rescue Aws::Errors::ServiceError => e puts "Couldn't put #{source_file_path} to #{object.key}. Here's why: #{e.message}" false end end # Example usage: def run_demo bucket_name = "doc-example-bucket" object_key = "my-object-key" file_path = "my-local-file.txt" wrapper = ObjectPutWrapper.new(Aws::S3::Object.new(bucket_name, object_key)) success = wrapper.put_object(file_path) return unless success puts "Put file #{file_path} into #{object_key} in #{bucket_name}." end run_demo if $PROGRAM_NAME == __FILE__

您可以傳送 REST 請求以上傳物件。您可以傳送 PUT 請求,以單一操作上傳資料。如需詳細資訊,請參閱 PUT 物件

您可以傳送 PUT 請求,以便在單一操作中上傳多達 5 GB 的物件。如需詳細資訊,請參閱《AWS CLI 命令參考》中的 PutObject 範例。