本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用目錄儲存貯體中的物件建立 Amazon S3 目錄儲存貯體之後，您可以使用 Amazon S3 主控台、 AWS Command Line Interface (AWS CLI) 和 AWS SDKs 來使用物件。如需在目錄儲存貯體中執行大量操作、匯入、上傳、複製、刪除和下載物件的詳細資訊，請參閱下列主題。 **Topics** + [將物件匯入目錄儲存貯體](create-import-job.md) + [使用適用於目錄儲存貯體的 S3 生命週期](directory-buckets-objects-lifecycle.md) + [使用 Batch Operations 搭配目錄儲存貯體](directory-buckets-objects-Batch-Ops.md) + [將資料附加至目錄儲存貯體中的物件](directory-buckets-objects-append.md) + [重新命名目錄儲存貯體中的物件](directory-buckets-objects-rename.md) + [將物件上傳至目錄儲存貯體](directory-buckets-objects-upload.md) + [從目錄儲存貯體複製物件或將物件複製到目錄儲存貯體](directory-buckets-objects-copy.md) + [從目錄儲存貯體中刪除物件](directory-bucket-delete-object.md) + [從目錄儲存貯體下載物件](directory-buckets-objects-GetExamples.md) + [產生預先簽章的 URL 以共用物件目錄儲存貯體](directory-buckets-objects-generate-presigned-url-Examples.md) + [從目錄儲存貯體擷取物件中繼資料](directory-buckets-objects-HeadObjectExamples.md) + [列示目錄儲存貯體中的物件](directory-buckets-objects-listobjectsExamples.md) # 將物件匯入目錄儲存貯體在 Amazon S3 中建立目錄儲存貯體之後，您可以使用匯入動作將資料填入新的儲存貯體。匯入是用來建立 S3 Batch Operations 任務的簡化方法，可將物件從一般用途儲存貯體複製到目錄儲存貯體。 **注意** 下列限制適用於匯入任務：來源儲存貯體和目的地儲存貯體必須位於相同的 AWS 區域和帳戶中。來源儲存貯體不可以是目錄儲存貯體。不支援大於 5GB 的物件，而且會從複製操作中省略。 Glacier Flexible Retrieval、Glacier Deep Archive、Intelligent-Tiering Archive Access 層和 Intelligent-Tiering Deep Archive 層儲存類別中的物件必須先還原才能匯入。使用 MD5 檢查總和演算法匯入的物件會轉換為使用 CRC32 檢查總和。匯入的物件會使用 Express One Zone 儲存類別，此類別的定價結構與一般用途儲存貯體使用的儲存類別不同。匯入大量物件時，請考慮這項成本上的差異。當您設定匯入任務時，可以指定要從中複製現有物件的來源儲存貯體或字首。您也可以提供具有存取來源物件許可的 AWS Identity and Access Management (IAM) 角色。接著 Amazon S3 就會啟動 Batch Operations 任務來複製物件，並自動套用適當的儲存類別和檢查總和設定。您可以使用 Amazon S3 主控台來設定匯入任務。 ## 使用 Amazon S3 主控台 **將物件匯入目錄儲存貯體** 1. 登入 AWS 管理主控台，並在 https：//[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/) 開啟 Amazon S3 主控台。 1. 在左側導覽窗格中，選擇**儲存貯體**，然後選擇**目錄儲存貯體**索引標籤。選擇要將物件匯入其中的目錄儲存貯體旁的選項按鈕。 1. 選擇**匯入**。 1. 針對**來源**，輸入包含要匯入之物件的一般用途儲存貯體 (或包含字首的儲存貯體路徑)。若要從清單中選擇現有的一般用途儲存貯體，請選擇**瀏覽 S3**。 1. 針對**存取和複製來源物件的許可**，執行下列其中一項操作，以指定具有匯入來源物件所需許可的 IAM 角色： + 若要允許 Amazon S3 代表您建立新的 IAM 角色，請選擇**建立新的 IAM 角色**。 + 若要從清單中選擇現有的 IAM 角色，請選擇**從現有的 IAM 角色中選擇**。 + 若要透過輸入 Amazon Resource Name (ARN) 來指定現有的 IAM 角色，請選擇**輸入 IAM 角色 ARN**，然後在對應的欄位中輸入 ARN。 1. 檢閱**目的地**和**複製物件設定**區段中顯示的資訊。如果**目的地**區段中的資訊正確無誤，請選擇**匯入**以開始複製任務。 Amazon S3 主控台會在 **Batch Operations** 頁面上顯示新任務的狀態。如需有關任務的詳細資訊，請選擇任務名稱旁的選項按鈕，然後在**動作**選單上選擇**檢視詳細資訊**。若要開啟要將物件匯入其中的目錄儲存貯體，請選擇**檢視匯入目的地**。 # 使用適用於目錄儲存貯體的 S3 生命週期 S3 生命週期可協助您將物件儲存在 S3 Express One Zone 中，透過代表您刪除過期物件來實現目錄儲存貯體成本效益。若要管理物件的生命週期，請為您的目錄儲存貯體建立 S3 生命週期組態。S3 生命週期組態是一組定義 Amazon S3 動作的規則，適用於一組物件。您可以使用 AWS 命令列界面 (AWS CLI)、 AWS SDKs、Amazon S3 REST API 和 AWS CloudFormation，在目錄儲存貯體上設定 Amazon S3 生命週期組態。在生命週期組態中，您可以使用規則來定義希望 Amazon S3 對物件採取的動作。對於儲存在目錄儲存貯體中的物件，您可以建立生命週期規則，在物件老化時使這些物件過期。您也可以建立生命週期規則，每天刪除目錄儲存貯體中未完成的分段上傳。當您新增儲存貯體的生命週期組態時，組態規則會套用至現有物件以及稍後新增的物件。例如，如果您目前所新增生命週期組態規則包含過期動作，會讓具有特定字首的物件在建立 30 天之後過期，則 S3 會將任何超過 30 天且具有指定字首的現有物件排入佇列，等待移除。 ## 適用於目錄儲存貯體的 S3 生命週期有何不同對於目錄儲存貯體中的物件，您可以建立生命週期規則來使物件過期，並刪除未完成的分段上傳。不過，適用於目錄儲存貯體的 S3 生命週期不支援在儲存類別之間進行轉換的動作。 **CreateSession** 生命週期使用公有 `DeleteObject` 和 `DeleteObjects` API 操作來使目錄儲存貯體中的物件過期。若要使用這些 API 操作，S3 生命週期會使用 `CreateSession` API 建立臨時安全憑證，以存取目錄儲存貯體中的物件。如需詳細資訊，請參閱 [Amazon S3 API 參考**中的`CreateSession`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateSession.html)。如果您有拒絕刪除生命週期主體許可的作用中政策，此政策將使您無法允許 S3 生命週期代表您刪除物件。 ### 使用儲存貯體政策授予 S3 生命週期服務主體許可下列儲存貯體政策會授予 S3 生命週期服務主體許可，以建立執行 `DeleteObject`和等操作的工作階段`DeleteObjects`。在`CreateSession`請求中未指定工作階段模式時，工作階段會由中的許可以最大允許權限建立 (`ReadWrite`首先嘗試，如果`ReadWrite`不允許 `ReadOnly` )。不過，`ReadOnly`工作階段不足以進行修改或刪除物件的生命週期操作。因此，此範例使用 `s3express:SessionMode`條件索引鍵明確需要`ReadWrite`工作階段模式。 **Example – 允許使用明確`ReadWrite`工作階段模式進行生命週期操作的`CreateSession`呼叫的儲存貯體政策** ``` { "Version":"2008-10-17", "Statement":[ { "Effect":"Allow", "Principal": { "Service":"lifecycle.s3.amazonaws.com" }, "Action":"s3express:CreateSession", "Condition": { "StringEquals": { "s3express:SessionMode": "ReadWrite" } }, "Resource":"arn:aws:s3express:us-east-2:412345678921:bucket/amzn-s3-demo-bucket--use2-az2--x-s3" } ] } ``` ### 監控生命週期規則對於存放在目錄儲存貯體中的物件，S3 生命週期會產生 AWS CloudTrail 管理和資料事件日誌。如需詳細資訊，請參閱 [S3 Express One Zone 的 CloudTrail 日誌檔案範例](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-log-files.html)。如需建立生命週期組態及對 S3 生命週期相關問題進行故障診斷的詳細資訊，請參閱下列主題： **Topics** # 為目錄儲存貯體建立和管理生命週期組態您可以使用 (AWS CLI)、 AWS Command Line Interface AWS SDKs和 REST APIs 來建立目錄儲存貯體的生命週期組態。 ## 使用 AWS CLI 您可以使用下列 AWS CLI 命令來管理 S3 生命週期組態： + `put-bucket-lifecycle-configuration` + `get-bucket-lifecycle-configuration` + `delete-bucket-lifecycle` 如需設定的指示 AWS CLI，請參閱《[Amazon S3 API 參考》中的使用 AWS CLI 開發](https://docs.aws.amazon.com/AmazonS3/latest/API/setup-aws-cli.html) Amazon S3。 *Amazon S3 * Amazon S3 生命週期組態是 XML 檔案。但是，當您使用時 AWS CLI，您無法指定 XML 格式。您必須改為指定 JSON 格式。以下是範例 XML 生命週期組態，以及您可以在 AWS CLI命令中指定的同等 JSON 組態。下列 AWS CLI 範例會在目錄儲存貯體上放置生命週期組態政策。此政策指定，所有包含標記字首 (myprefix) 並具有定義物件大小的物件會在 7 天後過期。若要使用此範例，請以您自己的資訊取代每個*使用者輸入預留位置*。將生命週期組態原則儲存至 JSON 檔案。在此範例中，檔案會命名為 lifecycle1.json。 **Example** ``` { "Rules": [ { "Expiration": { "Days": 7 }, "ID": "Lifecycle expiration rule", "Filter": { "And": { "Prefix": "myprefix/", "ObjectSizeGreaterThan": 500, "ObjectSizeLessThan": 64000 } }, "Status": "Enabled" } ] } ``` 提交 JSON 檔案以做為 `put-bucket-lifecycle-configuration` CLI 命令的一部分。若要使用此命令，請以您自己的資訊取代每個*使用者輸入預留位置*。 ``` aws s3api put-bucket-lifecycle-configuration --region us-west-2 --profile default --bucket amzn-s3-demo-bucket--usw2-az1--x-s3 --lifecycle-configuration file://lc-policy.json --checksum-algorithm crc32c ``` **Example** ``` Lifecycle expiration rule myprefix/ 500 64000 Enabled 7 ``` ## 使用 AWS SDKs ------ #### [ SDK for Java ] **Example** ``` import software.amazon.awssdk.services.s3.model.PutBucketLifecycleConfigurationRequest; import software.amazon.awssdk.services.s3.model.PutBucketLifecycleConfigurationResponse; import software.amazon.awssdk.services.s3.model.ChecksumAlgorithm; import software.amazon.awssdk.services.s3.model.BucketLifecycleConfiguration; import software.amazon.awssdk.services.s3.model.LifecycleRule; import software.amazon.awssdk.services.s3.model.LifecycleRuleFilter; import software.amazon.awssdk.services.s3.model.LifecycleExpiration; import software.amazon.awssdk.services.s3.model.LifecycleRuleAndOperator; import software.amazon.awssdk.services.s3.model.GetBucketLifecycleConfigurationResponse; import software.amazon.awssdk.services.s3.model.GetBucketLifecycleConfigurationRequest; import software.amazon.awssdk.services.s3.model.DeleteBucketLifecycleRequest; import software.amazon.awssdk.services.s3.model.DeleteBucketLifecycleResponse; import software.amazon.awssdk.services.s3.model.AbortIncompleteMultipartUpload; // PUT a Lifecycle policy LifecycleRuleFilter objectExpirationFilter = LifecycleRuleFilter.builder().and(LifecycleRuleAndOperator.builder().prefix("dir1/").objectSizeGreaterThan(3L).objectSizeLessThan(20L).build()).build(); LifecycleRuleFilter mpuExpirationFilter = LifecycleRuleFilter.builder().prefix("dir2/").build(); LifecycleRule objectExpirationRule = LifecycleRule.builder().id("lc").filter(objectExpirationFilter).status("Enabled").expiration(LifecycleExpiration.builder() .days(10) .build()) .build(); LifecycleRule mpuExpirationRule = LifecycleRule.builder().id("lc-mpu").filter(mpuExpirationFilter).status("Enabled").abortIncompleteMultipartUpload(AbortIncompleteMultipartUpload.builder() .daysAfterInitiation(10) .build()) .build(); PutBucketLifecycleConfigurationRequest putLifecycleRequest = PutBucketLifecycleConfigurationRequest.builder() .bucket("amzn-s3-demo-bucket--usw2-az1--x-s3") .checksumAlgorithm(ChecksumAlgorithm.CRC32) .lifecycleConfiguration( BucketLifecycleConfiguration.builder() .rules(objectExpirationRule, mpuExpirationRule) .build() ).build(); PutBucketLifecycleConfigurationResponse resp = client.putBucketLifecycleConfiguration(putLifecycleRequest); // GET the Lifecycle policy GetBucketLifecycleConfigurationResponse getResp = client.getBucketLifecycleConfiguration(GetBucketLifecycleConfigurationRequest.builder().bucket("amzn-s3-demo-bucket--usw2-az1--x-s3").build()); // DELETE the Lifecycle policy DeleteBucketLifecycleResponse delResp = client.deleteBucketLifecycle(DeleteBucketLifecycleRequest.builder().bucket("amzn-s3-demo-bucket--usw2-az1--x-s3").build()); ``` ------ #### [ SDK for Go ] **Example** ``` package main import ( "context" "log" "github.com/aws/aws-sdk-go-v2/aws" "github.com/aws/aws-sdk-go-v2/config" "github.com/aws/aws-sdk-go-v2/service/s3" "github.com/aws/aws-sdk-go-v2/service/s3/types" ) // PUT a Lifecycle policy func putBucketLifecycleConfiguration(client *s3.Client, bucketName string ) error { lifecycleConfig := &s3.PutBucketLifecycleConfigurationInput{ Bucket: aws.String(bucketName), LifecycleConfiguration: &types.BucketLifecycleConfiguration{ Rules: []types.LifecycleRule{ { ID: aws.String("lc"), Filter: &types.LifecycleRuleFilter{ And: &types.LifecycleRuleAndOperator{ Prefix: aws.String("foo/"), ObjectSizeGreaterThan: aws.Int64(1000000), ObjectSizeLessThan: aws.Int64(100000000), }, }, Status: types.ExpirationStatusEnabled, Expiration: &types.LifecycleExpiration{ Days: aws.Int32(int32(1)), }, }, { ID: aws.String("abortmpu"), Filter: &types.LifecycleRuleFilter{ Prefix: aws.String("bar/"), }, Status: types.ExpirationStatusEnabled, AbortIncompleteMultipartUpload: &types.AbortIncompleteMultipartUpload{ DaysAfterInitiation: aws.Int32(int32(5)), }, }, }, }, } _, err := client.PutBucketLifecycleConfiguration(context.Background(), lifecycleConfig) return err } // Get the Lifecycle policy func getBucketLifecycleConfiguration(client *s3.Client, bucketName string) error { getLifecycleConfig := &s3.GetBucketLifecycleConfigurationInput{ Bucket: aws.String(bucketName), } resp, err := client.GetBucketLifecycleConfiguration(context.Background(), getLifecycleConfig) if err != nil { return err } return nil } // Delete the Lifecycle policy func deleteBucketLifecycleConfiguration(client *s3.Client, bucketName string) error { deleteLifecycleConfig := &s3.DeleteBucketLifecycleInput{ Bucket: aws.String(bucketName), } _, err := client.DeleteBucketLifecycle(context.Background(), deleteLifecycleConfig) return err } func main() { cfg, err := config.LoadDefaultConfig(context.Background(), config.WithRegion("us-west-2")) // Specify your region here if err != nil { log.Fatalf("unable to load SDK config, %v", err) } s3Client := s3.NewFromConfig(cfg) bucketName := "amzn-s3-demo-bucket--usw2-az1--x-s3" putBucketLifecycleConfiguration(s3Client, bucketName) getBucketLifecycleConfiguration(s3Client, bucketName) deleteBucketLifecycleConfiguration(s3Client, bucketName) getBucketLifecycleConfiguration(s3Client, bucketName) } ``` ------ #### [ SDK for .NET ] **Example** ``` using Amazon; using Amazon.S3; using Amazon.S3.Model; using System; using System.Collections.Generic; using System.Threading.Tasks; namespace Amazon.DocSamples.S3 { class LifecycleTest { private const string bucketName = "amzn-s3-demo-bucket--usw2-az1--x-s3"; // Specify your bucket region (an example region is shown). private static readonly RegionEndpoint bucketRegion = RegionEndpoint.USWest2; private static IAmazonS3 client; public static void Main() { client = new AmazonS3Client(bucketRegion); AddUpdateDeleteLifecycleConfigAsync().Wait(); } private static async Task AddUpdateDeleteLifecycleConfigAsync() { try { var lifeCycleConfiguration = new LifecycleConfiguration() { Rules = new List { new LifecycleRule { Id = "delete rule", Filter = new LifecycleFilter() { LifecycleFilterPredicate = new LifecyclePrefixPredicate() { Prefix = "projectdocs/" } }, Status = LifecycleRuleStatus.Enabled, Expiration = new LifecycleRuleExpiration() { Days = 10 } } } }; // Add the configuration to the bucket. await AddExampleLifecycleConfigAsync(client, lifeCycleConfiguration); // Retrieve an existing configuration. lifeCycleConfiguration = await RetrieveLifecycleConfigAsync(client); // Add a new rule. lifeCycleConfiguration.Rules.Add(new LifecycleRule { Id = "mpu abort rule", Filter = new LifecycleFilter() { LifecycleFilterPredicate = new LifecyclePrefixPredicate() { Prefix = "YearlyDocuments/" } }, Expiration = new LifecycleRuleExpiration() { Days = 10 }, AbortIncompleteMultipartUpload = new LifecycleRuleAbortIncompleteMultipartUpload() { DaysAfterInitiation = 10 } }); // Add the configuration to the bucket. await AddExampleLifecycleConfigAsync(client, lifeCycleConfiguration); // Verify that there are now two rules. lifeCycleConfiguration = await RetrieveLifecycleConfigAsync(client); Console.WriteLine("Expected # of rulest=2; found:{0}", lifeCycleConfiguration.Rules.Count); // Delete the configuration. await RemoveLifecycleConfigAsync(client); // Retrieve a nonexistent configuration. lifeCycleConfiguration = await RetrieveLifecycleConfigAsync(client); } 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); } } static async Task AddExampleLifecycleConfigAsync(IAmazonS3 client, LifecycleConfiguration configuration) { PutLifecycleConfigurationRequest request = new PutLifecycleConfigurationRequest { BucketName = bucketName, Configuration = configuration }; var response = await client.PutLifecycleConfigurationAsync(request); } static async Task RetrieveLifecycleConfigAsync(IAmazonS3 client) { GetLifecycleConfigurationRequest request = new GetLifecycleConfigurationRequest { BucketName = bucketName }; var response = await client.GetLifecycleConfigurationAsync(request); var configuration = response.Configuration; return configuration; } static async Task RemoveLifecycleConfigAsync(IAmazonS3 client) { DeleteLifecycleConfigurationRequest request = new DeleteLifecycleConfigurationRequest { BucketName = bucketName }; await client.DeleteLifecycleConfigurationAsync(request); } } } ``` ------ #### [ SDK for Python ] **Example** ``` import boto3 client = boto3.client("s3", region_name="us-west-2") bucket_name = 'amzn-s3-demo-bucket--usw2-az1--x-s3' client.put_bucket_lifecycle_configuration( Bucket=bucket_name, ChecksumAlgorithm='CRC32', LifecycleConfiguration={ 'Rules': [ { 'ID': 'lc', 'Filter': { 'And': { 'Prefix': 'foo/', 'ObjectSizeGreaterThan': 1000000, 'ObjectSizeLessThan': 100000000, } }, 'Status': 'Enabled', 'Expiration': { 'Days': 1 } }, { 'ID': 'abortmpu', 'Filter': { 'Prefix': 'bar/' }, 'Status': 'Enabled', 'AbortIncompleteMultipartUpload': { 'DaysAfterInitiation': 5 } } ] } ) result = client.get_bucket_lifecycle_configuration( Bucket=bucket_name ) client.delete_bucket_lifecycle( Bucket=bucket_name ) ``` ------ # 對適用於目錄儲存貯體的 S3 生命週期問題進行故障診斷 **Topics** + [我設定了生命週期組態，但目錄儲存貯體中的物件未能過期](#troubleshoot-directory-bucket-lifecycle-1) + [如何監控生命週期規則採取的動作？](#troubleshoot-directory-bucket-lifecycle-2) ## 我設定了生命週期組態，但目錄儲存貯體中的物件未能過期適用於目錄儲存貯體的 S3 生命週期會使用公有 API 來刪除 S3 Express One Zone 中的物件。若要使用物件層級公有 API，您必須授予 `CreateSession` 許可，並允許 S3 生命週期許可來刪除您的物件。如果您有拒絕刪除的作用中政策，此政策將使您無法允許 S3 生命週期代表您刪除物件。請務必正確設定儲存貯體政策，以確保要刪除的物件符合過期資格。您可以在 AWS CloudTrail 中檢查`AccessDenied`追蹤 `CreateSession` API 調用的 CloudTrail 日誌，以驗證存取是否遭拒。檢查 CloudTrail 日誌可協助您對存取問題進行故障診斷，並找出存取遭拒錯誤的根本原因。然後，您可以透過更新相關政策來修正不正確的存取控制。如果您確認儲存貯體政策設定正確，但仍遇到問題，建議您檢閱生命週期規則，確保已將其套用至正確的物件子集。 ## 如何監控生命週期規則採取的動作？您可以使用 AWS CloudTrail 資料事件日誌來監控 S3 生命週期在目錄儲存貯體中採取的動作。如需詳細資訊，請參閱 [CloudTrail 日誌檔案範例](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-log-files.html)。 # 使用 Batch Operations 搭配目錄儲存貯體您可以使用 Amazon S3 Batch Operations 對存放在 S3 儲存貯體中的物件執行操作。若要深入了解 S3 Batch Operations，請參閱[在 Amazon S3 物件上執行大規模批次操作](https://docs.aws.amazon.com/AmazonS3/latest/userguide/batch-ops.html)。下列主題討論如何對儲存在目錄貯體中 S3 Express One Zone 儲存類別的物件執行批次操作。 **Topics** + [使用 Batch Operations 搭配目錄儲存貯體](#UsingBOPsDirectoryBuckets) + [主要差異](#UsingBOPsDirectoryBucketsKeyDiffs) ## 使用 Batch Operations 搭配目錄儲存貯體您可以對儲存在目錄儲存貯體中的物件執行**複製**操作和**調用 AWS Lambda 函數**操作。您可以使用**複製**，在相同類型的儲存貯體之間複製物件 (例如從一個目錄儲存貯體複製到另一個目錄儲存貯體)。您也可以在一般用途儲存貯體和目錄儲存貯體之間進行複製。使用**叫用 AWS Lambda 函數**，您可以使用 Lambda 函數，透過您定義的程式碼對目錄儲存貯體中的物件執行動作。 **複製物件** 您可以在相同的儲存貯體類型之間，或目錄儲存貯體與一般用途儲存貯體之間進行複製。當您複製到目錄儲存貯體時，必須針對此儲存貯體類型使用正確的 Amazon Resource Name (ARN) 格式。目錄儲存貯體的 ARN 格式為 `arn:aws:s3express:region:account-id:bucket/bucket-base-name--x-s3`。 **注意** 當來源或目的地儲存貯體位於 AWS 本機區域時， AWS 區域不支援跨不同複製物件。來源儲存貯體和目的地儲存貯體必須具有相同的父 AWS 區域。來源儲存貯體和目的地儲存貯體可以是不同的儲存貯體位置類型 (可用區域或本機區域)。您也可以使用 S3 主控台中的**匯入**動作，將資料填入目錄儲存貯體。**匯入**是用來建立 Batch Operations 任務的簡化方法，可將物件從一般用途儲存貯體複製到目錄儲存貯體。針對從一般用途儲存貯體到目錄儲存貯體的**匯入**複製任務，S3 會自動產生清單檔案。如需詳細資訊，請參閱[將物件匯入目錄儲存貯體](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-import-job.html)和[指定資訊清單](https://docs.aws.amazon.com/AmazonS3/latest/userguide/specify-batchjob-manifest.html)。 **調用 Lambda 函數 (`LambdaInvoke`)** 使用 Batch Operations 調用對目錄儲存貯體執行動作的 Lambda 函式時，須遵循特殊需求。例如，您必須使用 v2 JSON 調用結構描述來建構 Lambda 請求，並在建立作業時指定 InvocationSchemaVersion 2.0。如需詳細資訊，請參閱[調用 AWS Lambda 函數](https://docs.aws.amazon.com/AmazonS3/latest/userguide/batch-ops-invoke-lambda.html)。 ## 主要差異以下列出使用 Batch Operations 對儲存在具有 S3 Express One Zone 儲存類別之目錄儲存貯體中的物件執行大量操作時的主要差異： + 對於目錄儲存貯體，支援使用 AWS Key Management Service (AWS KMS) 金鑰 (SSE-KMS) 的 SSE-S3 和伺服器端加密。如果您提出 `CopyObject` 請求，指定在目錄儲存貯體 (來源或目的地) 上使用客戶提供的金鑰的伺服器端加密 (SSE-C)，回應會傳回 HTTP `400 (Bad Request)` 錯誤。建議儲存貯體的預設加密使用所需的加密組態，而且您不會覆寫 `CreateSession` 請求或 `PUT` 物件請求中的儲存貯體預設加密。然後，新的物件會以所需的加密設定自動加密。如需在目錄儲存貯體中覆寫加密行為，以及如何使用 SSE-KMS 加密目錄儲存貯體中新物件複本的詳細資訊，請參閱[使用指定伺服器端加密 AWS KMS 以進行新物件上傳](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-specifying-kms-encryption.html)。當您透過 [Batch Operations 中的 Copy 操作](#directory-buckets-objects-Batch-Ops)，將 SSE-KMS 加密物件從一般用途儲存貯體複製到目錄儲存貯體、從目錄儲存貯體複製到一般用途儲存貯體或在目錄儲存貯體之間複製時，不支援 S3 儲存貯體金鑰。在此情況下，Amazon S3 AWS KMS 每次對 KMS 加密物件提出複製請求時都會呼叫。如需在目錄儲存貯體上使用 SSE-KMS 的詳細資訊，請參閱[設定和監控目錄儲存貯體的預設加密](s3-express-bucket-encryption.md)和[在目錄儲存貯體中使用伺服器端加密與 AWS KMS 金鑰 (SSE-KMS)](s3-express-UsingKMSEncryption.md)。 + 目錄儲存貯體中的物件無法加上標籤。您只能指定空的標籤集。根據預設，Batch Operations 會複製標籤。如果您在一般用途儲存貯體與目錄儲存貯體之間複製具有標籤的物件，您會收到 `501 (Not Implemented)` 回應。 + S3 Express One Zone 可讓您選擇在上傳或下載期間用於驗證資料的檢查總和演算法。您可以選擇以下 Secure Hash 演算法 (SHA) 或循環宂餘檢查 (CRC) 資料完整性演算法之一：CRC32、CRC32C、SHA-1 和 SHA-256。S3 Express One Zone 儲存類別不支援 MD5 型檢查總和。 + 根據預設，所有 Amazon S3 儲存貯體都會將 S3 物件擁有權設定為儲存貯體擁有者強制執行，並停用存取控制清單 (ACL)。目錄儲存貯體的此設定無法修改。您也可以將物件從一般用途儲存貯體複製到目錄儲存貯體。不過，當您在目錄儲存貯體上來回複製時，無法覆寫預設 ACL。 + 無論您如何指定清單檔案，此清單本身都必須儲存在一般用途儲存貯體中。Batch Operations 無法從目錄儲存貯體匯入現有的資訊清單，也無法將產生的資訊清單儲存至目錄儲存貯體。不過，清單檔案內描述的物件可以儲存在目錄儲存貯體中。 + Batch Operations 無法指定目錄儲存貯體作為 S3 庫存報告中的位置。庫存報告不支援目錄儲存貯體。您可以透過使用 `ListObjectsV2` API 操作列出物件，來為目錄儲存貯體內的物件建立資訊清單。然後，您可以將清單插入 CSV 檔案。 ### 授與存取權若要執行複製任務，您必須具有下列許可： + 若要在目錄儲存貯體之間複製物件，您必須具有 `s3express:CreateSession` 許可。 + 若要將物件從目錄儲存貯體複製到一般用途儲存貯體，您必須具有 `s3express:CreateSession` 許可和 `s3:PutObject` 許可，以將複製的物件寫入目的地儲存貯體。 + 若要將物件從一般用途儲存貯體複製到目錄儲存貯體，您必須具有 `s3express:CreateSession` 許可和 `s3:GetObject` 許可，以讀取要複製的來源物件。如需詳細資訊，請參閱 Amazon Simple Storage Service API 參考**中的 [https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html)。 + 若要調用 Lambda 函數，您必須根據 Lambda 函數為資源授予許可。若要判斷需要哪些許可，請查看對應的 API 操作。 # 將資料附加至目錄儲存貯體中的物件您可以將資料新增至儲存在目錄儲存貯體中 S3 Express One Zone 儲存類別的現有物件結尾。如果資料連續寫入一段時間，或者如果您在寫入物件時需要讀取物件，建議您使用將資料附加至物件的功能。將資料附加至物件的常見使用案例包括將新的日誌項目加入日誌檔案，或是將新的影片片段加入影片檔案，以在轉碼後進行串流。透過將資料附加至物件，您可以簡化先前必須先合併本機儲存的資料，再將最終物件複製到 Amazon S3 的應用程式。您可以附加至物件的資料沒有大小下限要求。不過，您可以在單一請求中附加至物件的資料大小上限為 5 GB。這與使用任何 Amazon S3 API 上傳資料時的最大請求大小限制相同。每個成功的附加操作都會建立物件的一個組件，每個物件最多可以有 10,000 個組件。這表示您最多可以將資料附加至物件 10,000 次。如果使用 S3 分段上傳建立物件，則每個上傳的組件都會計入 10,000 個組件的總計上限。例如，您最多可以附加至透過分段上傳 1,000 個組件所建立的物件 9,000 次。 **注意** 如果達到組件數上限，則會收到 [TooManyParts](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html#API_PutObject_Errors) 錯誤。您可以使用 `CopyObject` API 來重設計數。如果您想要將多個組件平行上傳至物件，而且在上傳組件時不需要讀取組件，建議您使用 Amazon S3 分段上傳。如需詳細資訊，請參閱[使用分段上傳](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-using-multipart-upload.html)。只有儲存在 S3 Express One Zone 儲存類別之目錄儲存貯體中的物件，才支援將資料附加至物件。如需 S3 Express One Zone 的詳細資訊，請參閱[開始使用 S3 Express One Zone](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-getting-started.html)。若要開始將 AWS 資料附加至目錄儲存貯體中的物件，您可以使用 SDKs、 AWS CLI 和 `PutObject` API 。當您提出 `PutObject` 請求時，請將 `x-amz-write-offset-bytes` 標頭設定為您要附加的目的地物件大小。若要使用 `PutObject` API 操作，您必須使用 `CreateSession` API 建立臨時安全憑證，以存取目錄儲存貯體中的物件。如需詳細資訊，請參閱 Amazon S3 API 參考**中的[https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)和[https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateSession.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateSession.html)。每個成功的附加操作都會以一個 `PutObject` 請求來計費。若要進一步了解定價，請參閱[https://aws.amazon.com/s3/pricing/](https://aws.amazon.com/s3/pricing/)。 **注意** 從 1.12 版開始，適用於 Amazon S3 的掛載點支援將資料附加至儲存在 S3 Express One Zone 中的物件。若要開始使用，您必須設定 `--incremental-upload ` 旗標以選擇加入。如需掛載點的詳細資訊，請參閱[使用掛載點](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mountpoint.html)。如果您在上傳附加資料時使用 CRC (循環冗餘檢查) 演算法，您可以使用 `HeadObject` 或 `GetObject` 請求來擷取完整物件 CRC 型檢查總和。如果您在上傳附加資料時使用 SHA-1 或 SHA-256 演算法，您可以擷取附加組件的檢查總和，並使用先前 PutObject 回應傳回的 SHA 檢查總和來驗證其完整性。如需詳細資訊，請參閱[資料保護和加密](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-data-protection.html.html)。 ## 使用 CLI、 AWS SDKs AWS 和 REST API 將資料附加至物件您可以使用 AWS Command Line Interface (AWS CLI)、 AWS SDKs和 REST API 將資料附加至物件。 ### 使用 AWS CLI 下列`put-object`範例命令顯示如何使用 AWS CLI 將資料附加至物件。若要執行此命令，請以您自己的資訊取代*使用者輸入預留位置*。 ``` aws s3api put-object --bucket amzn-s3-demo-bucket--azid--x-s3 --key sampleinput/file001.bin --body bucket-seed/file001.bin --write-offset-bytes size-of-sampleinput/file001.bin ``` ### 使用 AWS SDKs ------ #### [ SDK for Java ] 您可以使用適用於 Java 的 AWS SDK 將資料附加至物件。 ``` var putObjectRequestBuilder = PutObjectRequest.builder() .key(key) .bucket(bucketName) .writeOffsetBytes(9); var response = s3Client.putObject(putObjectRequestBuilder.build()); ``` ------ #### [ SDK for Python ] ``` s3.put_object(Bucket='amzn-s3-demo-bucket--use2-az2--x-s3', Key='2024-11-05-sdk-test', Body=b'123456789', WriteOffsetBytes=9) ``` ------ ### 使用 REST API 您可以傳送 REST 請求，將資料附加至物件。如需詳細資訊，請參閱[https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html#API_PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html#API_PutObject)。 # 重新命名目錄儲存貯體中的物件您可以使用 `RenameObject` 操作，在使用 S3 Express One Zone 儲存類別的目錄儲存貯體中以原子方式重新命名現有物件，而不需移動任何資料。您可以將現有物件的名稱指定為來源，並將物件的新名稱指定為相同目錄儲存貯體中的目的地，藉以重新命名物件。`RenameObject` API 操作對於以斜線 (`/`) 分隔符號字元結尾的物件無效。如需詳細資訊，請參閱[命名 Amazon S3 物件](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html)。無論物件大小為何，`RenameObject` 操作通常以毫秒為單位完成。此功能可加速日誌檔案管理、媒體處理和資料分析等應用程式。此外，`RenameObject` 會保留所有物件中繼資料屬性，包括儲存類別、加密類型、建立日期、上次修改日期和檢查總和屬性。 **注意** `RenameObject` 僅支援儲存在 S3 Express One Zone 儲存類別中的物件。若要授予 `RenameObject` 操作的存取權，建議您使用 `CreateSession` 操作進行工作階段型授權。具體而言，您會將 `s3express:CreateSession` 許可權授予儲存貯體政策或身分型政策中的目錄儲存貯體。然後在目錄儲存貯體上進行 `CreateSession` API 呼叫，以取得工作階段字符。若使用您的請求標頭中的工作階段字符，您就可以對此操作提出 API 請求。工作階段字符過期後，您會進行另一個 `CreateSession` API 呼叫來產生新的工作階段字符以供使用。CLI 和 AWS SDKs AWS 將建立和管理工作階段，包括自動重新整理工作階段權杖，以避免工作階段過期時服務中斷。如需有關授權的詳細資訊，請參閱《Amazon S3 API 參考》**中的 [https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateSession.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateSession.html)。若要進一步了解區域端點 API 操作，請參閱[使用 `CreateSession` 授權區域端點 API 操作](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-create-session.html)。如果您不想要覆寫現有的物件，您可以在 `RenameObject` 請求中新增具有值 `‘*’` 的 `If-None-Match` 條件式標頭。如果物件名稱已存在，Amazon S3 會傳回 `412 Precondition Failed` 錯誤。如需詳細資訊，請參閱 *Amazon S3 API 參考*中的 [https://docs.aws.amazon.com/AmazonS3/latest/API/API_RenameObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_RenameObject.html)。 `RenameObject` 是一種區域端點 API 操作 (物件層級或資料平面操作)，會記錄到 AWS CloudTrail。您可以使用 CloudTrail 來收集對目錄儲存貯體中物件執行之 `RenameObject` 操作的相關資訊。如需詳細資訊，請參閱[使用記錄目錄儲存貯 AWS CloudTrail 體，](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-one-zone-logging.html)以及 [CloudTrail 記錄檔案範例記錄目錄儲存貯體](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-log-files.html)。 S3 Express One Zone 是唯一支援 `RenameObject` 的儲存類別，其定價與 S3 Express One Zone 中的 `PUT`、`COPY`、`POST` 和 `LIST` 請求 (每 1,000 個請求) 相同。如需詳細資訊，請參閱 [Simple Storage Service (Amazon S3) 定價](https://aws.amazon.com/s3/pricing/)。 ## 重新命名物件若要重新命名目錄儲存貯體中的物件，您可以使用 Amazon S3 主控台、 AWS CLI、 AWS SDKs、REST API 或 Amazon S3 掛載點 (1.19.0 版或更新版本）。 ### 使用 S3 主控台 **重新命名目錄儲存貯體中的物件** 1. 登入 AWS 管理主控台，並在 [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)：// 開啟 Amazon S3 主控台。 1. 在導覽窗格中，選擇**儲存貯體**，然後選擇**目錄儲存貯體**索引標籤。導覽至包含要重新命名之物件的 Amazon S3 目錄儲存貯體。 1. 選取您要重新命名之物件的核取方塊。 1. 在**動作**功能表上，選擇**重新命名物件**。 1. 在**新物件名稱**方塊中，輸入物件的新名稱。 **注意** 如果您指定與現有物件相同的物件名稱，操作將會失敗，Amazon S3 會傳回 `412 Precondition Failed` 錯誤。物件索引鍵名稱長度不可超過 1,024 個位元組。物件名稱中包含的字首會納入總長度計算。 1. 選擇**重新命名物件**。Amazon S3 會重新命名您的物件。 ### 使用 AWS CLI 這些 `rename-object` 範例示範如何使用 AWS CLI 重新命名物件。若要執行這些命令，請以您自己的資訊取代*使用者輸入預留位置*。下列範例示範如何對來源物件的 ETag 使用條件式檢查功能來重新命名物件。 ``` aws s3api rename-object \ --bucket amzn-s3-demo-bucket--usw2-az1--x-s3 \ --key new-file.txt \ --rename-source original-file.txt \ --source-if-match "\"a1b7c3d2e5f6\"" ``` 此命令會執行下列動作： + 在 *amzn-s3-demo-bucket--usw2-az1--x-s3*目錄儲存貯體中，將物件從 *original-file.txt* 重新命名為 *new-file.txt*。 + 只有在來源物件的 ETag 符合 "*a1b7c3d4e5f6*" 時，才會執行重新命名。如果 ETag 不相符，則操作會失敗，並顯示 `412 Precondition Failed` 錯誤。下列範例示範如何使用新指定物件名稱的條件式檢查功能來重新命名物件。 ``` aws s3api rename-object \ --bucket amzn-s3-demo-bucket--usw2-az1--x-s3 \ --key new-file.txt \ --rename-source amzn-s3-demo-bucket--usw2-az1--x-s3/original-file.txt \ --destination-if-none-match "\"e5f3g7h8i9j0\"" ``` 此命令會執行下列動作： + 在 *amzn-s3-demo-bucket--usw2-az1--x-s3*目錄儲存貯體中，將物件從 *original-file.txt* 重新命名為 *new-file.txt*。 + 只有在物件存在，且物件的 ETag 不符合 "*e5f3g7h8i9j0*" 時，才會執行重新命名操作。如果具有新指定名稱和相符 ETag 的物件已存在，則操作將會失敗，並顯示 `412 Precondition Failed` 錯誤。 ### 使用 AWS SDKs ------ #### [ SDK for Java ] 您可以使用適用於 Java 的 AWS SDK 來重新命名物件。若要使用這些範例，請以您自己的資訊取代*使用者輸入預留位置*。下列範例示範如何使用適用於 Java `RenameObjectRequest`的 AWS 開發套件建立 ``` String key = "key"; String newKey = "new-key"; String expectedETag = "e5f3g7h8i9j0"; RenameObjectRequest renameRequest = RenameObjectRequest.builder() .bucket(amzn-s3-demo-bucket--usw2-az1--x-s3) .key(newKey) .renameSource(key) .destinationIfMatch(e5f3g7h8i9j0) .build(); ``` 該程式碼會執行下列作業： + 在 *amzn-s3-demo-bucket--usw2-az1--x-s3* 目錄儲存貯體中，建立將物件從 "*key*" 重新命名為 "*new-key*" 的請求。 + 包括只有在物件的 ETag 符合 "*e5f3g7h8i9j0*" 時，才會產生重新命名的條件。 + 如果 ETag 不相符或物件不存在，操作將會失敗。下列範例示範如何使用適用於 Java 的 AWS 開發套件建立`RenameObjectRequest`具有無相符條件的。 ``` String key = "key"; String newKey = "new-key"; String noneMatchETag = "e5f3g7h8i9j0"; RenameObjectRequest renameRequest = RenameObjectRequest.builder() .bucket(amzn-s3-demo-bucket--usw2-az1--x-s3) .key(newKey) .renameSource(key) .destinationIfNoneMatch(noneMatchETag) .build(); ``` 該程式碼會執行下列作業： + 建立請求，以在 *amzn-s3-demo-bucket--usw2-az1--x-s3* 目錄儲存貯體中將物件從 "*key*" 重新命名為 "*new-key*"。 + 包含使用 `.destinationIfNoneMatch(noneMatchETag)` 的條件，確保只有在目的地物件的 ETag 不符合 "*e5f3g7h8i9j0*" 時，才會重新命名。如果具有新指定名稱的物件存在，且具有指定的 ETag，則操作會失敗，並顯示 `412 Precondition Failed` 錯誤。 ------ #### [ SDK for Python ] 您可以使用適用於 Python 的 SDK 來重新命名物件。若要使用這些範例，請以您自己的資訊取代*使用者輸入預留位置*。下列範例示範如何使用適用於 Python 的 AWS SDK (Boto3) 重新命名物件。 ``` def basic_rename(bucket, source_key, destination_key): try: s3.rename_object( Bucket=amzn-s3-demo-bucket--usw2-az1--x-s3, Key=destination_key, RenameSource=f"{source_key}" ) print(f"Successfully renamed {source_key} to {destination_key}") except ClientError as e: print(f"Error renaming object: {e}") ``` 該程式碼會執行下列作業： + 在 *amzn-s3-demo-bucket--usw2-az1--x-s3* 目錄儲存貯體中，將物件從 *source\$1key* 重新命名為 *destination\$1key*。 + 如果物件的重新命名成功，則列印成功訊息；如果失敗，則列印錯誤訊息。下列範例示範如何使用適用於 Python 的 AWS SDK (Boto3) 重新命名具有 `SourceIfMatch`和 `DestinationIfNoneMatch`條件的物件。 ``` def rename_with_conditions(bucket, source_key, destination_key, source_etag, dest_etag): try: s3.rename_object( Bucket=amzn-s3-demo-bucket--usw2-az1--x-s3, Key=destination_key, RenameSource=f"{amzn-s3-demo-bucket--usw2-az1--x-s3}/{source_key}", SourceIfMatch=source_ETag, DestinationIfNoneMatch=dest_ETag ) print(f"Successfully renamed {source_key} to {destination_key} with conditions") except ClientError as e: print(f"Error renaming object: {e}") ``` 該程式碼會執行下列作業： + 執行條件式重新命名操作，並套用兩個條件，即 `SourceIfMatch` 和 `DestinationIfNoneMatch`。這些條件的組合可確保物件尚未修改，且物件不存在，並具有新的指定名稱。 + 在 *amzn-s3-demo-bucket--usw2-az1--x-s3* 目錄儲存貯體中，將物件從 *source\$1key* 重新命名為 *destination\$1key*。 + 如果物件的重新命名成功，則列印成功訊息；如果失敗或不符合條件，則列印錯誤訊息。 ------ #### [ SDK for Rust ] 您可以使用 SDK for Rust 重新命名物件。若要使用這些範例，請以您自己的資訊取代*使用者輸入預留位置*。下列範例示範如何使用 SDK for Rust 重新命名 *amzn-s3-demo-bucket--usw2-az1--x-s3* 目錄儲存貯體中的物件。 ``` async fn basic_rename_example(client: &Client) -> Result<(), Box> { let response = client .rename_object() .bucket(" amzn-s3-demo-bucket--usw2-az1--x-s3") .key("new-name.txt") // New name/path for the object .rename_source("old-name.txt") // Original object name/path .send() .await?; Ok(()) } ``` 該程式碼會執行下列作業： + 建立請求，以在 *amzn-s3-demo-bucket--usw2-az1--x-s3* 目錄儲存貯體中，將物件從 "*old-name.tx*" 重新命名為 "*new-name.txt*"。 + 傳回可處理潛在錯誤的 `Result` 類型。 ------ ### 使用 REST API 您可以傳送 REST 請求以重新命名物件。如需詳細資訊，請參閱 *Amazon S3 API 參考*中的 [https://docs.aws.amazon.com/AmazonS3/latest/API/API_RenameObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_RenameObject.html)。 ### 使用適用於 Amazon S3 的掛載點從 1.19.0 版或更新版本開始，適用於 Amazon S3 的掛載點支援在 S3 Express One Zone 中重新命名物件。如需掛載點的詳細資訊，請參閱[使用掛載點](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mountpoint.html)。 # 將物件上傳至目錄儲存貯體建立 Amazon S3 目錄儲存貯體之後，您可以將物件上傳至其中。下列範例示範如何使用 S3 主控台和 AWS SDK 將物件上傳至目錄儲存貯體。如需使用 S3 Express One Zone 執行大量物件上傳操作的資訊，請參閱[物件管理](directory-bucket-high-performance.md#s3-express-features-object-management)。 ## 使用 S3 主控台 1. 登入 AWS 管理主控台，並在 [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)：// 開啟 Amazon S3 主控台。 1. 在左側導覽窗格中，選擇**目錄儲存貯體**。 1. 選擇您要上傳資料夾和檔案的目的地儲存貯體名稱。 1. 在**物件**清單中，選擇**上傳**。 1. 在**上傳**頁面上，執行下列任一步驟： + 將檔案和資料夾拖放至上傳區域。 + 選擇**新增檔案**或**新增資料夾**，選擇要上傳的檔案或資料夾，然後選擇**開啟**或**上傳**。 1. 在**檢查總和**下，選擇您要使用的**檢查總和函數**。 (選用) 如果您上傳的單一物件大小小於 16 MB，您也可以指定預先計算的檢查總和值。當您提供預先計算的值時，Amazon S3 會將該值與使用所選檢查總和函數計算的值進行比較。如果值不相符，則不會開始上傳。 1. **許可**和**屬性**區段中的選項會自動設定為預設設定，且無法修改。封鎖公開存取會自動啟用，且無法針對目錄儲存貯體啟用 S3 版本控制和 S3 物件鎖定。 (選用) 如果您要以金鑰/值對的形式將中繼資料新增至物件，請展開**屬性**區段，然後在**中繼資料**區段中選擇**新增中繼資料**。 1. 若要上傳列出的檔案和資料夾，請選擇**上傳**。 Amazon S3 會上傳您的物件和資料夾。上傳完成後，您可以在**上傳：狀態**頁面上看到成功訊息。 ## 使用 AWS SDKs ------ #### [ SDK for Java 2.x ] **Example** ``` public static void putObject(S3Client s3Client, String bucketName, String objectKey, Path filePath) { //Using File Path to avoid loading the whole file into memory try { PutObjectRequest putObj = PutObjectRequest.builder() .bucket(bucketName) .key(objectKey) //.metadata(metadata) .build(); s3Client.putObject(putObj, filePath); System.out.println("Successfully placed " + objectKey +" into bucket "+bucketName); } catch (S3Exception e) { System.err.println(e.getMessage()); System.exit(1); } } ``` ------ #### [ SDK for Python ] **Example** ``` import boto3 import botocore from botocore.exceptions import ClientError def put_object(s3_client, bucket_name, key_name, object_bytes): """ Upload data to a directory bucket. :param s3_client: The boto3 S3 client :param bucket_name: The bucket that will contain the object :param key_name: The key of the object to be uploaded :param object_bytes: The data to upload """ try: response = s3_client.put_object(Bucket=bucket_name, Key=key_name, Body=object_bytes) print(f"Upload object '{key_name}' to bucket '{bucket_name}'.") return response except ClientError: print(f"Couldn't upload object '{key_name}' to bucket '{bucket_name}'.") raise def main(): # Share the client session with functions and objects to benefit from S3 Express One Zone auth key s3_client = boto3.client('s3') # Directory bucket name must end with --zone-id--x-s3 resp = put_object(s3_client, 'doc-bucket-example--use1-az5--x-s3', 'sample.txt', b'Hello, World!') print(resp) if __name__ == "__main__": main() ``` ------ ## 使用 AWS CLI 下列 `put-object` 範例命令示範如何使用 AWS CLI 將物件上傳至 Amazon S3。若要執行此命令，請以您自己的資訊取代 `user input placeholders`。 ``` aws s3api put-object --bucket bucket-base-name--zone-id--x-s3 --key sampleinut/file001.bin --body bucket-seed/file001.bin ``` 如需詳細資訊，請參閱《AWS CLI 命令參考》**中的 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/put-object.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/put-object.html)。 **Topics** + [搭配目錄儲存貯體使用分段上傳](s3-express-using-multipart-upload.md) # 搭配目錄儲存貯體使用分段上傳您可以使用分段上傳程序，將單一物件以一組組件進行上傳。每個組件都是物件資料的接續部分。您可依任何順序分別上傳這些物件組件。若任何組件的傳輸失敗，您可再次傳輸該組件，而不會影響其他組件。當物件的所有組件都全部上傳完後，Amazon S3 會將這些組件組合起來建立該物件。一般而言，當物件大小達到 100 MB 時，應考慮使用分段上傳，而不是以單次操作上傳物件。使用分段上傳具備下列優勢： + **改善輸送量** - 您可平行上傳各組件以改進輸送量。 + **快速從任何網路問題復原** – 組件大小若較小，對於重新開始因為網路發生錯誤而上傳失敗的影響可降到最低。 + **暫停及繼續上傳物件** - 您可在一段時間內上傳物件組件。啟動分段上傳之後，就沒有過期日。您必須明確完成或中止分段上傳。 + **在您知道最終物件大小前開始上傳** - 您可在建立物件的同時上傳物件。建議您依照下列方式使用分段上傳： + 如果您透過穩定的高頻寬網路上傳大型物件，使用分段上傳可同時上傳多個物件組件以取得多執行緒效能，因而充分利用可用的頻寬。 + 如果您透過不穩定的網路進行上傳，使用分段上傳可避免上傳重新開始，因而更快從網路錯誤中復原。使用分段上傳時，只有上傳期間遭到中斷的組件才需要重試上傳。您不需要從頭開始重新上傳物件。當您使用分段上傳將物件上傳至目錄儲存貯體中的 Amazon S3 Express One Zone 儲存類別時，分段上傳程序類似於使用分段上傳將物件上傳至一般用途儲存貯體的程序。不過，還是有一些顯著的差異。如需使用分段上傳將物件上傳至 S3 Express One Zone 的詳細資訊，請參閱下列主題。 **Topics** + [分段上傳程序](#s3-express-mpu-process) + [使用分段上傳操作的檢查總和](#s3-express-mpuchecksums) + [並行分段上傳操作](#s3-express-distributedmpupload) + [分段上傳與定價](#s3-express-mpuploadpricing) + [分段上傳 API 操作與許可](#s3-express-mpuAndPermissions) + [範例](#directory-buckets-multipart-upload-examples) ## 分段上傳程序分段上傳是三個步驟的程序： + 啟動上傳。 + 上傳物件組件。 + 上傳所有組件之後，即完成分段上傳。 Amazon S3 一收到完成分段上傳請求，就會從上傳的組件建構物件，然後您即可像存取儲存貯體中的任何其他物件一樣存取該物件。 **啟動分段上傳** 當您傳送要求要啟動分段上傳時，Amazon S3 會傳回具有上傳 ID 的回應，其為分段上傳的唯一識別符。每次上傳分段各組件、列出各組件、完成上傳或中止上傳時，都必須納入此上傳 ID。 **組件上傳** 上傳某個分段組件時，除了上傳 ID 之外，還必須指定組件編號。搭配 S3 Express One Zone 使用分段上傳時，分段組件編號必須是連續的組件編號。如果您嘗試使用非連續的組件編號完成分段上傳請求，則會產生 `HTTP 400 Bad Request` 錯誤 (組件順序無效)。組件編號可找出獨特的某個組件，以及其在上傳中物件內的位置。若使用和前一個上傳組件相同的組件編號上傳新的組件，將會覆寫前一個已上傳的組件。每次上傳一個組件時，Amazon S3 會在其回應中傳回企業標籤 (ETag) 標頭。您必須記錄每個上傳組件的組件編號與 ETag 值。所有物件組件上傳的 ETag 值將保持不變，但每個組件將獲指派不同的組件編號。後續的要求中必須包含這些值，才能完成分段上傳。 Amazon S3 會自動加密上傳到 S3 儲存貯體的所有新物件。進行分段上傳時，若您未在請求中指定加密資訊，所上傳分段的加密設定會設為目的地儲存貯體的預設加密組態。Amazon S3 儲存貯體的預設加密組態一律為啟用狀態，且最低限度設定為使用 Amazon S3 受管金鑰 (SSE-S3) 的伺服器端加密。對於目錄儲存貯體，支援 SSE-S3 和伺服器端加密與 AWS KMS 金鑰 (SSE-KMS)。如需詳細資訊，請參閱[資料保護和加密](s3-express-data-protection.md)。 **完成分段上傳** 當您完成分段上傳時，Amazon S3 會根據組件編號以遞增順序串連各個組件，建立物件。成功*完成*請求之後，這些片段就不再存在。您的「完成分段上傳」**請求必須包含上傳 ID，以及組件編號和其對應 ETag 值的清單。Amazon S3 回應包含的 ETag 可識別獨特的物件資料組合。這個 ETag 不是物件資料的 MD5 雜湊。 **分段上傳清單** 您可列出特定分段上傳的組件或所有進行中之分段上傳。列出組件操作會傳回特定分段上傳之已上傳組件的資訊。Amazon S3 會為每項列出的組件要求，傳回指定分段上傳組件的資訊，上限為 1,000 個組件。若分段上傳中有超過 1,000 個分段，您必須使用分頁來擷取所有分段。傳回的組件清單不會包含尚未完成上傳的組件。使用*列出分段上傳*操作，即可取得正在進行中的分段上傳清單。進行中的分段上傳是您已啟動但尚未完成或已中止的上傳。每個要求最多可傳回 1,000 個分段上傳。若正在進行超過 1,000 個的分段上傳，您必須另行傳送請求以擷取剩餘的分段上傳。傳回的清單僅用於進行驗證。傳送*完成分段上傳*請求時，請不要使用此清單的結果。而是在上傳 Amazon S3 傳回的組件與相對應之 ETag 值時，保有您自己的組件編號清單。如需分段上傳清單的詳細資訊，請參閱 Amazon Simple Storage Service API 參考**中的[https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListParts.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListParts.html)。 ## 使用分段上傳操作的檢查總和當您上傳物件時，可以指定檢查總和演算法來檢查物件完整性。目錄儲存貯體不支援 MD5。您可以指定以下 Secure Hash 演算法 (SHA) 或循環冗餘檢查 (CRC) 資料完整性演算法之一： + CRC32 + CRC32C + SHA-1 + SHA-256 您可以使用 Amazon S3 REST API 或 AWS SDKs，使用 `GetObject`或擷取個別組件的檢查總和值`HeadObject`。如果想要擷取分段上傳 (仍在進行中) 之個別部分的總和檢查值，您可以使用 `ListParts`。 **重要** 使用上述檢查總和演算法時，分段上傳組件編號必須使用連續的組件編號。如果您嘗試使用非連續的組件編號完成分段上傳請求，則 Amazon S3 會產生 `HTTP 400 Bad Request` (組件順序無效) 錯誤。如需如何搭配分段上傳物件使用檢查總和的詳細資訊，請參閱[在 Amazon S3 中檢查物件完整性](checking-object-integrity.md)。 ## 並行分段上傳操作在分散式開發環境中，您的應用程式可以同時對相同的物件啟動數項更新。例如，您的應用程式可能使用相同的物件金鑰啟動數個分段上傳。然後針對這些每一個上傳，應用程式會上傳各組件，並對 Amazon S3 傳送完成上傳要求，以建立物件。對於 S3 Express One Zone 來說，物件建立時間是指分段上傳的完成日期。 **重要** 儲存在目錄儲存貯體中的物件不支援版本控制。 ## 分段上傳與定價啟動分段上傳之後，Amazon S3 就會保留所有分段，直到您完成或中止上傳為止。在其整個生命週期內，您都要支付此分段上傳及其相關組件的儲存體、頻寬與要求之費用。如果您中止分段上傳，Amazon S3 會刪除上傳成品及任何已上傳的組件，而且您不需要再支付其費用。無論指定的儲存類別為何，刪除未完成的分段上傳都不會收取提前刪除費用。如需定價的詳細資訊，請參閱 [Amazon S3 定價](https://aws.amazon.com/s3/pricing/)。 **重要** 若未能成功傳送完成分段上傳請求，就不會組合物件組件，也不會建立物件。系統會向您收取與已上傳部分相關的所有儲存空間費用。請務必完成分段上傳以建立物件，或者中止分段上傳以刪除任何已上傳的組件。刪除目錄儲存貯體之前，您必須先完成或中止所有進行中的分段上傳。目錄儲存貯體不支援 S3 生命週期組態。如有需要，您可以列出作用中分段上傳，然後中止上傳，再刪除儲存貯體。 ## 分段上傳 API 操作與許可若要允許存取目錄儲存貯體上的物件管理 API 操作，您可以在儲存貯體政策或 AWS Identity and Access Management (IAM) 身分型政策中授予 `s3express:CreateSession` 許可。您必須要有必要許可，才可使用分段上傳操作。您可以使用儲存貯體政策或 IAM 身分型政策，授予 IAM 主體執行這些操作的許可。下表列出各種分段上傳操作所需的許可。您可以透過 `Initiator` 元素識別分段上傳的啟動者。如果啟動器是 AWS 帳戶，此元素會提供與 `Owner`元素相同的資訊。若啟動者是 IAM 使用者，此元素會提供使用者 ARN 與顯示名稱。 | Action | 所需的許可 | | --- | --- | | 建立分段上傳 | 若要建立分段上傳，您必須能夠對目錄儲存貯體執行 `s3express:CreateSession` 動作。 | | 啟動分段上傳 | 若要啟動分段上傳，您必須能夠對目錄儲存貯體執行 `s3express:CreateSession` 動作。 | | 上傳組件 | 若要上傳組件，您必須能夠對目錄儲存貯體執行 `s3express:CreateSession` 動作。若要讓啟動者上傳組件，儲存貯體擁有者必須允許啟動者對目錄儲存貯體執行 `s3express:CreateSession` 動作。 | | 上傳組件 (複製) | 若要上傳組件，您必須能夠對目錄儲存貯體執行 `s3express:CreateSession` 動作。啟動者若要分段上傳該物件，儲存貯體擁有者必須允許啟動者對物件執行 `s3express:CreateSession` 動作。 | | 完成分段上傳 | 若要完成分段上傳，您必須能夠對目錄儲存貯體執行 `s3express:CreateSession` 動作。若要讓啟動者完成分段上傳，儲存貯體擁有者必須允許啟動者對物件執行 `s3express:CreateSession` 動作。 | | 中止分段上傳 | 若要中止分段上傳，您必須能夠執行 `s3express:CreateSession` 動作。若要讓啟動者中止分段上載，必須明確授權允許啟動者執行 `s3express:CreateSession` 動作。 | | 列出組件 | 若要列出分段上傳的組件，您必須能夠對目錄儲存貯體執行 `s3express:CreateSession` 動作。 | | 列出進行中的分段上傳 | 若要列出對儲存貯體的進行中分段上傳，您必須能夠對該儲存貯體執行 `s3:ListBucketMultipartUploads` 動作。 | ### 分段上傳的 API 操作支援 Amazon Simple Storage Service API 參考中的下列各節將描述用於分段上傳的 Amazon S3 REST API 操作。 + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateMultipartUpload.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateMultipartUpload.html) + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPart.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPart.html) + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPartCopy.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPartCopy.html) + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html) + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_AbortMultipartUpload.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_AbortMultipartUpload.html) + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListParts.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListParts.html) + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListMultipartUploads.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListMultipartUploads.html) ## 範例若要使用分段上傳將物件上傳至目錄儲存貯體中的 S3 Express One Zone，請參閱下列範例。 **Topics** + [建立分段上傳](#directory-buckets-multipart-upload-examples-create) + [上傳分段上傳的組件](#directory-buckets-multipart-upload-examples-upload-part) + [完成分段上傳](#directory-buckets-multipart-upload-examples-complete) + [中止分段上傳](#directory-buckets-multipart-upload-examples-abort) + [建立分段上傳複製操作](#directory-buckets-multipart-upload-examples-upload-part-copy) + [列出進行中的分段上傳](#directory-buckets-multipart-upload-examples-list) + [列出分段上傳的分段](#directory-buckets-multipart-upload-examples-list-parts) ### 建立分段上傳 **注意** 對於目錄儲存貯體，當您執行 `CreateMultipartUpload` 操作和 `UploadPartCopy` 操作時，儲存貯體的預設加密必須使用所需的加密組態，而且您在 `CreateMultipartUpload` 請求中提供的請求標頭必須符合目的地儲存貯體的預設加密組態。下列範例示範如何建立分段上傳。 #### 使用 AWS SDKs ------ #### [ SDK for Java 2.x ] **Example** ``` /** * This method creates a multipart upload request that generates a unique upload ID that is used to track * all the upload parts * * @param s3 * @param bucketName - for example, 'doc-example-bucket--use1-az4--x-s3' * @param key * @return */ private static String createMultipartUpload(S3Client s3, String bucketName, String key) { CreateMultipartUploadRequest createMultipartUploadRequest = CreateMultipartUploadRequest.builder() .bucket(bucketName) .key(key) .build(); String uploadId = null; try { CreateMultipartUploadResponse response = s3.createMultipartUpload(createMultipartUploadRequest); uploadId = response.uploadId(); } catch (S3Exception e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } return uploadId; ``` ------ #### [ SDK for Python ] **Example** ``` def create_multipart_upload(s3_client, bucket_name, key_name): ''' Create a multipart upload to a directory bucket :param s3_client: boto3 S3 client :param bucket_name: The destination bucket for the multipart upload :param key_name: The key name for the object to be uploaded :return: The UploadId for the multipart upload if created successfully, else None ''' try: mpu = s3_client.create_multipart_upload(Bucket = bucket_name, Key = key_name) return mpu['UploadId'] except ClientError as e: logging.error(e) return None ``` ------ #### 使用 AWS CLI 此範例示範如何使用 AWS CLI建立對目錄儲存貯體的分段上傳。此命令會開始將物件 *KEY\$1NAME* 分段上傳至目錄儲存貯體 *bucket-base-name*--*zone-id*--x-s3。若要使用此命令，請以您自己的資訊取代*使用者輸入預留位置*。 ``` aws s3api create-multipart-upload --bucket bucket-base-name--zone-id--x-s3 --key KEY_NAME ``` 如需詳細資訊，請參閱 AWS Command Line Interface中的 [create-multipart-upload](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/create-multipart-upload.html)。 ### 上傳分段上傳的組件下列範例示範如何上傳分段上傳的組件。 #### 使用 AWS SDKs ------ #### [ SDK for Java 2.x ] 下列範例示範如何將單一物件分成多個組件，然後使用適用於 Java 2.x 的 SDK 將這些組件上傳至目錄儲存貯體。 **Example** ``` /** * This method creates part requests and uploads individual parts to S3 and then returns all the completed parts * * @param s3 * @param bucketName * @param key * @param uploadId * @throws IOException */ private static ListCompletedPartmultipartUpload(S3Client s3, String bucketName, String key, String uploadId, String filePath) throws IOException { int partNumber = 1; ListCompletedPart completedParts = new ArrayList<>(); ByteBuffer bb = ByteBuffer.allocate(1024 * 1024 * 5); // 5 MB byte buffer // read the local file, breakdown into chunks and process try (RandomAccessFile file = new RandomAccessFile(filePath, "r")) { long fileSize = file.length(); int position = 0; while (position < fileSize) { file.seek(position); int read = file.getChannel().read(bb); bb.flip(); // Swap position and limit before reading from the buffer. UploadPartRequest uploadPartRequest = UploadPartRequest.builder() .bucket(bucketName) .key(key) .uploadId(uploadId) .partNumber(partNumber) .build(); UploadPartResponse partResponse = s3.uploadPart( uploadPartRequest, RequestBody.fromByteBuffer(bb)); CompletedPart part = CompletedPart.builder() .partNumber(partNumber) .eTag(partResponse.eTag()) .build(); completedParts.add(part); bb.clear(); position += read; partNumber++; } } catch (IOException e) { throw e; } return completedParts; } ``` ------ #### [ SDK for Python ] 下列範例示範如何將單一物件分成多個組件，然後使用適用於 Python 的 SDK 將這些組件上傳至目錄儲存貯體。 **Example** ``` def multipart_upload(s3_client, bucket_name, key_name, mpu_id, part_size): ''' Break up a file into multiple parts and upload those parts to a directory bucket :param s3_client: boto3 S3 client :param bucket_name: Destination bucket for the multipart upload :param key_name: Key name for object to be uploaded and for the local file that's being uploaded :param mpu_id: The UploadId returned from the create_multipart_upload call :param part_size: The size parts that the object will be broken into, in bytes. Minimum 5 MiB, Maximum 5 GiB. There is no minimum size for the last part of your multipart upload. :return: part_list for the multipart upload if all parts are uploaded successfully, else None ''' part_list = [] try: with open(key_name, 'rb') as file: part_counter = 1 while True: file_part = file.read(part_size) if not len(file_part): break upload_part = s3_client.upload_part( Bucket = bucket_name, Key = key_name, UploadId = mpu_id, Body = file_part, PartNumber = part_counter ) part_list.append({'PartNumber': part_counter, 'ETag': upload_part['ETag']}) part_counter += 1 except ClientError as e: logging.error(e) return None return part_list ``` ------ #### 使用 AWS CLI 此範例示範如何將單一物件分成多個組件，然後使用 AWS CLI將這些組件上傳至目錄儲存貯體。若要使用此命令，請以您自己的資訊取代*使用者輸入預留位置*。 ``` aws s3api upload-part --bucket bucket-base-name--zone-id--x-s3 --key KEY_NAME --part-number 1 --body LOCAL_FILE_NAME --upload-id "AS_mgt9RaQE9GEaifATue15dAAAAAAAAAAEMAAAAAAAAADQwNzI4MDU0MjUyMBYAAAAAAAAAAA0AAAAAAAAAAAH2AfYAAAAAAAAEBSD0WBKMAQAAAABneY9yBVsK89iFkvWdQhRCcXohE8RbYtc9QvBOG8tNpA" ``` 如需詳細資訊，請參閱 AWS Command Line Interface中的 [upload-part](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/upload-part.html)。 ### 完成分段上傳下列範例示範如何完成分段上傳。 #### 使用 AWS SDKs ------ #### [ SDK for Java 2.x ] 下列範例示範如何使用適用於 Java 2.x 的 SDK 完成分段上傳。 **Example** ``` /** * This method completes the multipart upload request by collating all the upload parts * @param s3 * @param bucketName - for example, 'doc-example-bucket--usw2-az1--x-s3' * @param key * @param uploadId * @param uploadParts */ private static void completeMultipartUpload(S3Client s3, String bucketName, String key, String uploadId, ListCompletedPart uploadParts) { CompletedMultipartUpload completedMultipartUpload = CompletedMultipartUpload.builder() .parts(uploadParts) .build(); CompleteMultipartUploadRequest completeMultipartUploadRequest = CompleteMultipartUploadRequest.builder() .bucket(bucketName) .key(key) .uploadId(uploadId) .multipartUpload(completedMultipartUpload) .build(); s3.completeMultipartUpload(completeMultipartUploadRequest); } public static void multipartUploadTest(S3Client s3, String bucketName, String key, String localFilePath) { System.out.println("Starting multipart upload for: " + key); try { String uploadId = createMultipartUpload(s3, bucketName, key); System.out.println(uploadId); ListCompletedPart parts = multipartUpload(s3, bucketName, key, uploadId, localFilePath); completeMultipartUpload(s3, bucketName, key, uploadId, parts); System.out.println("Multipart upload completed for: " + key); } catch (Exception e) { System.err.println(e.getMessage()); System.exit(1); } } ``` ------ #### [ SDK for Python ] 下列範例示範如何使用適用於 Python 的 SDK 完成分段上傳。 **Example** ``` def complete_multipart_upload(s3_client, bucket_name, key_name, mpu_id, part_list): ''' Completes a multipart upload to a directory bucket :param s3_client: boto3 S3 client :param bucket_name: The destination bucket for the multipart upload :param key_name: The key name for the object to be uploaded :param mpu_id: The UploadId returned from the create_multipart_upload call :param part_list: The list of uploaded part numbers with their associated ETags :return: True if the multipart upload was completed successfully, else False ''' try: s3_client.complete_multipart_upload( Bucket = bucket_name, Key = key_name, UploadId = mpu_id, MultipartUpload = { 'Parts': part_list } ) except ClientError as e: logging.error(e) return False return True if __name__ == '__main__': MB = 1024 ** 2 region = 'us-west-2' bucket_name = 'BUCKET_NAME' key_name = 'OBJECT_NAME' part_size = 10 * MB s3_client = boto3.client('s3', region_name = region) mpu_id = create_multipart_upload(s3_client, bucket_name, key_name) if mpu_id is not None: part_list = multipart_upload(s3_client, bucket_name, key_name, mpu_id, part_size) if part_list is not None: if complete_multipart_upload(s3_client, bucket_name, key_name, mpu_id, part_list): print (f'{key_name} successfully uploaded through a ultipart upload to {bucket_name}') else: print (f'Could not upload {key_name} hrough a multipart upload to {bucket_name}') ``` ------ #### 使用 AWS CLI 此範例示範如何使用 AWS CLI完成目錄儲存貯體的分段上傳。若要使用此命令，請以您自己的資訊取代*使用者輸入預留位置*。 ``` aws s3api complete-multipart-upload --bucket bucket-base-name--zone-id--x-s3 --key KEY_NAME --upload-id "AS_mgt9RaQE9GEaifATue15dAAAAAAAAAAEMAAAAAAAAADQwNzI4MDU0MjUyMBYAAAAAAAAAAA0AAAAAAAAAAAH2AfYAAAAAAAAEBSD0WBKMAQAAAABneY9yBVsK89iFkvWdQhRCcXohE8RbYtc9QvBOG8tNpA" --multipart-upload file://parts.json ``` 此範例採用 JSON 結構，描述應重新組合成完整檔案的分段上傳組件。在此範例中，`file://` 字首用於從本機資料夾中名為 `parts` 的檔案載入 JSON 結構。 parts.json： ``` parts.json { "Parts": [ { "ETag": "6b78c4a64dd641a58dac8d9258b88147", "PartNumber": 1 } ] } ``` 如需詳細資訊，請參閱 AWS Command Line Interface中的 [complete-multipart-upload](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/complete-multipart-upload.html)。 ### 中止分段上傳下列範例示範如何中止分段上傳。 #### 使用 AWS SDKs ------ #### [ SDK for Java 2.x ] 下列範例示範如何使用適用於 Java 2.x 的 SDK 中止分段上傳。 **Example** ``` public static void abortMultiPartUploads( S3Client s3, String bucketName ) { try { ListMultipartUploadsRequest listMultipartUploadsRequest = ListMultipartUploadsRequest.builder() .bucket(bucketName) .build(); ListMultipartUploadsResponse response = s3.listMultipartUploads(listMultipartUploadsRequest); ListMultipartUpload uploads = response.uploads(); AbortMultipartUploadRequest abortMultipartUploadRequest; for (MultipartUpload upload: uploads) { abortMultipartUploadRequest = AbortMultipartUploadRequest.builder() .bucket(bucketName) .key(upload.key()) .uploadId(upload.uploadId()) .build(); s3.abortMultipartUpload(abortMultipartUploadRequest); } } catch (S3Exception e) { System.err.println(e.getMessage()); System.exit(1); } } ``` ------ #### [ SDK for Python ] 下列範例示範如何使用適用於 Python 的 SDK 中止分段上傳。 **Example** ``` import logging import boto3 from botocore.exceptions import ClientError def abort_multipart_upload(s3_client, bucket_name, key_name, upload_id): ''' Aborts a partial multipart upload in a directory bucket. :param s3_client: boto3 S3 client :param bucket_name: Bucket where the multipart upload was initiated - for example, 'doc-example-bucket--usw2-az1--x-s3' :param key_name: Name of the object for which the multipart upload needs to be aborted :param upload_id: Multipart upload ID for the multipart upload to be aborted :return: True if the multipart upload was successfully aborted, False if not ''' try: s3_client.abort_multipart_upload( Bucket = bucket_name, Key = key_name, UploadId = upload_id ) except ClientError as e: logging.error(e) return False return True if __name__ == '__main__': region = 'us-west-2' bucket_name = 'BUCKET_NAME' key_name = 'KEY_NAME' upload_id = 'UPLOAD_ID' s3_client = boto3.client('s3', region_name = region) if abort_multipart_upload(s3_client, bucket_name, key_name, upload_id): print (f'Multipart upload for object {key_name} in {bucket_name} bucket has been aborted') else: print (f'Unable to abort multipart upload for object {key_name} in {bucket_name} bucket') ``` ------ #### 使用 AWS CLI 下列範例示範如何使用 AWS CLI中止分段上傳。若要使用此命令，請以您自己的資訊取代*使用者輸入預留位置*。 ``` aws s3api abort-multipart-upload --bucket bucket-base-name--zone-id--x-s3 --key KEY_NAME --upload-id "AS_mgt9RaQE9GEaifATue15dAAAAAAAAAAEMAAAAAAAAADQwNzI4MDU0MjUyMBYAAAAAAAAAAA0AAAAAAAAAAAH2AfYAAAAAAAAEAX5hFw-MAQAAAAB0OxUFeA7LTbWWFS8WYwhrxDxTIDN-pdEEq_agIHqsbg" ``` 如需詳細資訊，請參閱 AWS Command Line Interface中的 [abort-multipart-upload](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/abort-multipart-upload.html)。 ### 建立分段上傳複製操作 **注意** 若要使用 SSE-KMS 加密目錄儲存貯體中的新物件組件複本，您必須使用 KMS 金鑰 (特別是[客戶自管金鑰](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk)) 將 SSE-KMS 指定為目錄儲存貯體的預設加密組態。不支援 [AWS 受管金鑰](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-managed-cmk) (`aws/s3`)。您的 SSE-KMS 組態在儲存貯體的生命週期內，每個目錄儲存貯體只能支援 1 個[客戶自管金鑰](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk)。為 SSE-KMS 指定客戶自管金鑰之後，即無法覆寫儲存貯體 SSE-KMS 組態的客戶自管金鑰。您無法在 [UploadPartCopy](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPartCopy.html) 請求標頭中，使用 SSE-KMS 為新的物件組件複本指定伺服器端加密設定。此外，您在 `CreateMultipartUpload` 請求中提供的請求標頭必須符合目的地儲存貯體的預設加密組態。當您透過 [https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPartCopy.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPartCopy.html)，將 SSE-KMS 加密物件從一般用途儲存貯體複製到目錄儲存貯體、從目錄儲存貯體複製到一般用途儲存貯體或在目錄儲存貯體之間複製時，不支援 S3 儲存貯體金鑰。在此情況下，Amazon S3 AWS KMS 每次對 KMS 加密物件提出複製請求時都會呼叫。下列範例示範如何使用分段上傳，將物件從一個儲存貯體複製到另一個。 #### 使用 AWS SDKs ------ #### [ SDK for Java 2.x ] 下列範例示範如何透過適用於 Java 2.x 的 SDK，使用分段上傳以程式設計方式將物件從一個儲存貯體複製到另一個。 **Example** ``` /** * This method creates a multipart upload request that generates a unique upload ID that is used to track * all the upload parts. * * @param s3 * @param bucketName * @param key * @return */ private static String createMultipartUpload(S3Client s3, String bucketName, String key) { CreateMultipartUploadRequest createMultipartUploadRequest = CreateMultipartUploadRequest.builder() .bucket(bucketName) .key(key) .build(); String uploadId = null; try { CreateMultipartUploadResponse response = s3.createMultipartUpload(createMultipartUploadRequest); uploadId = response.uploadId(); } catch (S3Exception e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } return uploadId; } /** * Creates copy parts based on source object size and copies over individual parts * * @param s3 * @param sourceBucket * @param sourceKey * @param destnBucket * @param destnKey * @param uploadId * @return * @throws IOException */ public static ListCompletedPart multipartUploadCopy(S3Client s3, String sourceBucket, String sourceKey, String destnBucket, String destnKey, String uploadId) throws IOException { // Get the object size to track the end of the copy operation. HeadObjectRequest headObjectRequest = HeadObjectRequest .builder() .bucket(sourceBucket) .key(sourceKey) .build(); HeadObjectResponse response = s3.headObject(headObjectRequest); Long objectSize = response.contentLength(); System.out.println("Source Object size: " + objectSize); // Copy the object using 20 MB parts. long partSize = 20 * 1024 * 1024; long bytePosition = 0; int partNum = 1; ListCompletedPart completedParts = new ArrayList<>(); while (bytePosition < objectSize) { // The last part might be smaller than partSize, so check to make sure // that lastByte isn't beyond the end of the object. long lastByte = Math.min(bytePosition + partSize - 1, objectSize - 1); System.out.println("part no: " + partNum + ", bytePosition: " + bytePosition + ", lastByte: " + lastByte); // Copy this part. UploadPartCopyRequest req = UploadPartCopyRequest.builder() .uploadId(uploadId) .sourceBucket(sourceBucket) .sourceKey(sourceKey) .destinationBucket(destnBucket) .destinationKey(destnKey) .copySourceRange("bytes="+bytePosition+"-"+lastByte) .partNumber(partNum) .build(); UploadPartCopyResponse res = s3.uploadPartCopy(req); CompletedPart part = CompletedPart.builder() .partNumber(partNum) .eTag(res.copyPartResult().eTag()) .build(); completedParts.add(part); partNum++; bytePosition += partSize; } return completedParts; } public static void multipartCopyUploadTest(S3Client s3, String srcBucket, String srcKey, String destnBucket, String destnKey) { System.out.println("Starting multipart copy for: " + srcKey); try { String uploadId = createMultipartUpload(s3, destnBucket, destnKey); System.out.println(uploadId); ListCompletedPart parts = multipartUploadCopy(s3, srcBucket, srcKey,destnBucket, destnKey, uploadId); completeMultipartUpload(s3, destnBucket, destnKey, uploadId, parts); System.out.println("Multipart copy completed for: " + srcKey); } catch (Exception e) { System.err.println(e.getMessage()); System.exit(1); } } ``` ------ #### [ SDK for Python ] 下列範例示範如何透過適用於 Python 的 SDK，使用分段上傳以程式設計方式將物件從一個儲存貯體複製到另一個。 **Example** ``` import logging import boto3 from botocore.exceptions import ClientError def head_object(s3_client, bucket_name, key_name): ''' Returns metadata for an object in a directory bucket :param s3_client: boto3 S3 client :param bucket_name: Bucket that contains the object to query for metadata :param key_name: Key name to query for metadata :return: Metadata for the specified object if successful, else None ''' try: response = s3_client.head_object( Bucket = bucket_name, Key = key_name ) return response except ClientError as e: logging.error(e) return None def create_multipart_upload(s3_client, bucket_name, key_name): ''' Create a multipart upload to a directory bucket :param s3_client: boto3 S3 client :param bucket_name: Destination bucket for the multipart upload :param key_name: Key name of the object to be uploaded :return: UploadId for the multipart upload if created successfully, else None ''' try: mpu = s3_client.create_multipart_upload(Bucket = bucket_name, Key = key_name) return mpu['UploadId'] except ClientError as e: logging.error(e) return None def multipart_copy_upload(s3_client, source_bucket_name, key_name, target_bucket_name, mpu_id, part_size): ''' Copy an object in a directory bucket to another bucket in multiple parts of a specified size :param s3_client: boto3 S3 client :param source_bucket_name: Bucket where the source object exists :param key_name: Key name of the object to be copied :param target_bucket_name: Destination bucket for copied object :param mpu_id: The UploadId returned from the create_multipart_upload call :param part_size: The size parts that the object will be broken into, in bytes. Minimum 5 MiB, Maximum 5 GiB. There is no minimum size for the last part of your multipart upload. :return: part_list for the multipart copy if all parts are copied successfully, else None ''' part_list = [] copy_source = { 'Bucket': source_bucket_name, 'Key': key_name } try: part_counter = 1 object_size = head_object(s3_client, source_bucket_name, key_name) if object_size is not None: object_size = object_size['ContentLength'] while (part_counter - 1) * part_size 下列範例示範如何透過 AWS CLI，使用分段上傳以程式設計方式將物件從一個儲存貯體複製到另一個。若要使用此命令，請以您自己的資訊取代*使用者輸入預留位置*。 ``` aws s3api upload-part-copy --bucket bucket-base-name--zone-id--x-s3 --key TARGET_KEY_NAME --copy-source SOURCE_BUCKET_NAME/SOURCE_KEY_NAME --part-number 1 --upload-id "AS_mgt9RaQE9GEaifATue15dAAAAAAAAAAEMAAAAAAAAADQwNzI4MDU0MjUyMBYAAAAAAAAAAA0AAAAAAAAAAAH2AfYAAAAAAAAEBnJ4cxKMAQAAAABiNXpOFVZJ1tZcKWib9YKE1C565_hCkDJ_4AfCap2svg" ``` 如需詳細資訊，請參閱 AWS Command Line Interface中的 [upload-part-copy](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/upload-part-copy.html )。 ### 列出進行中的分段上傳若要列出對目錄儲存貯體進行中的分段上傳，您可以使用 AWS SDKs或 AWS CLI。 #### 使用 AWS SDKs ------ #### [ SDK for Java 2.x ] 下列範例示範如何使用適用於 Java 2.x 的 SDK 列出進行中 (未完成) 的分段上傳。 **Example** ``` public static void listMultiPartUploads( S3Client s3, String bucketName) { try { ListMultipartUploadsRequest listMultipartUploadsRequest = ListMultipartUploadsRequest.builder() .bucket(bucketName) .build(); ListMultipartUploadsResponse response = s3.listMultipartUploads(listMultipartUploadsRequest); List MultipartUpload uploads = response.uploads(); for (MultipartUpload upload: uploads) { System.out.println("Upload in progress: Key = \"" + upload.key() + "\", id = " + upload.uploadId()); } } catch (S3Exception e) { System.err.println(e.getMessage()); System.exit(1); } } ``` ------ #### [ SDK for Python ] 下列範例示範如何使用適用於 Python 的 SDK 列出進行中 (未完成) 的分段上傳。 **Example** ``` import logging import boto3 from botocore.exceptions import ClientError def list_multipart_uploads(s3_client, bucket_name): ''' List any incomplete multipart uploads in a directory bucket in e specified gion :param s3_client: boto3 S3 client :param bucket_name: Bucket to check for incomplete multipart uploads :return: List of incomplete multipart uploads if there are any, None if not ''' try: response = s3_client.list_multipart_uploads(Bucket = bucket_name) if 'Uploads' in response.keys(): return response['Uploads'] else: return None except ClientError as e: logging.error(e) if __name__ == '__main__': bucket_name = 'BUCKET_NAME' region = 'us-west-2' s3_client = boto3.client('s3', region_name = region) multipart_uploads = list_multipart_uploads(s3_client, bucket_name) if multipart_uploads is not None: print (f'There are {len(multipart_uploads)} ncomplete multipart uploads for {bucket_name}') else: print (f'There are no incomplete multipart uploads for {bucket_name}') ``` ------ #### 使用 AWS CLI 下列範例示範如何使用 AWS CLI列出進行中 (未完成) 的分段上傳。若要使用此命令，請以您自己的資訊取代*使用者輸入預留位置*。 ``` aws s3api list-multipart-uploads --bucket bucket-base-name--zone-id--x-s3 ``` 如需詳細資訊，請參閱 AWS Command Line Interface中的 [list-multipart-uploads](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/list-multipart-uploads.html )。 ### 列出分段上傳的分段下列範例示範如何列出分段上傳至目錄儲存貯體的組件。 #### 使用 AWS SDKs ------ #### [ SDK for Java 2.x ] 下列範例示範如何使用適用於 Java 2.x 的 SDK 列出分段上傳至目錄儲存貯體的組件。 ``` public static void listMultiPartUploadsParts( S3Client s3, String bucketName, String objKey, String uploadID) { try { ListPartsRequest listPartsRequest = ListPartsRequest.builder() .bucket(bucketName) .uploadId(uploadID) .key(objKey) .build(); ListPartsResponse response = s3.listParts(listPartsRequest); ListPart parts = response.parts(); for (Part part: parts) { System.out.println("Upload in progress: Part number = \"" + part.partNumber() + "\", etag = " + part.eTag()); } } catch (S3Exception e) { System.err.println(e.getMessage()); System.exit(1); } } ``` ------ #### [ SDK for Python ] 下列範例示範如何使用適用於 Python 的 SDK 列出分段上傳至目錄儲存貯體的組件。 ``` import logging import boto3 from botocore.exceptions import ClientError def list_parts(s3_client, bucket_name, key_name, upload_id): ''' Lists the parts that have been uploaded for a specific multipart upload to a directory bucket. :param s3_client: boto3 S3 client :param bucket_name: Bucket that multipart uploads parts have been uploaded to :param key_name: Name of the object that has parts uploaded :param upload_id: Multipart upload ID that the parts are associated with :return: List of parts associated with the specified multipart upload, None if there are no parts ''' parts_list = [] next_part_marker = '' continuation_flag = True try: while continuation_flag: if next_part_marker == '': response = s3_client.list_parts( Bucket = bucket_name, Key = key_name, UploadId = upload_id ) else: response = s3_client.list_parts( Bucket = bucket_name, Key = key_name, UploadId = upload_id, NextPartMarker = next_part_marker ) if 'Parts' in response: for part in response['Parts']: parts_list.append(part) if response['IsTruncated']: next_part_marker = response['NextPartNumberMarker'] else: continuation_flag = False else: continuation_flag = False return parts_list except ClientError as e: logging.error(e) return None if __name__ == '__main__': region = 'us-west-2' bucket_name = 'BUCKET_NAME' key_name = 'KEY_NAME' upload_id = 'UPLOAD_ID' s3_client = boto3.client('s3', region_name = region) parts_list = list_parts(s3_client, bucket_name, key_name, upload_id) if parts_list is not None: print (f'{key_name} has {len(parts_list)} parts uploaded to {bucket_name}') else: print (f'There are no multipart uploads with that upload ID for {bucket_name} bucket') ``` ------ #### 使用 AWS CLI 下列範例示範如何使用 AWS CLI列出分段上傳至目錄儲存貯體的組件。若要使用此命令，請以您自己的資訊取代*使用者輸入預留位置*。 ``` aws s3api list-parts --bucket bucket-base-name--zone-id--x-s3 --key KEY_NAME --upload-id "AS_mgt9RaQE9GEaifATue15dAAAAAAAAAAEMAAAAAAAAADQwNzI4MDU0MjUyMBYAAAAAAAAAAA0AAAAAAAAAAAH2AfYAAAAAAAAEBSD0WBKMAQAAAABneY9yBVsK89iFkvWdQhRCcXohE8RbYtc9QvBOG8tNpA" ``` 如需詳細資訊，請參閱 AWS Command Line Interface中的 [list-parts](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/list-parts.html)。 # 從目錄儲存貯體複製物件或將物件複製到目錄儲存貯體該複製操作會為已存放在 Amazon S3 中的物件建立複本。您可以在目錄儲存貯體和一般用途儲存貯體之間複製物件。您也可以在儲存貯體內以及相同類型的儲存貯體之間複製物件，例如從目錄儲存貯體複製到目錄儲存貯體。 **注意** 當來源或目的地儲存貯體位於 AWS 本機區域時， AWS 區域不支援跨不同複製物件。來源儲存貯體和目的地儲存貯體必須具有相同的父 AWS 區域。來源儲存貯體和目的地儲存貯體可以是不同的儲存貯體位置類型 (可用區域或本機區域)。單一非敗即成 (atomic operation) 操作最多可以為 5 GB 的物件建立複本。但若複製的物件大於 5 GB，則必須使用分段上傳 API 操作。如需詳細資訊，請參閱[搭配目錄儲存貯體使用分段上傳](s3-express-using-multipart-upload.md)。 **許可** 若要複製物件，您必須具有下列許可： + 若要在目錄儲存貯體之間複製物件，您必須具有 `s3express:CreateSession` 許可。 + 若要將物件從目錄儲存貯體複製到一般用途儲存貯體，您必須具有 `s3express:CreateSession` 許可和 `s3:PutObject` 許可，以將複製的物件寫入目的地儲存貯體。 + 若要將物件從一般用途儲存貯體複製到目錄儲存貯體，您必須具有 `s3express:CreateSession` 許可和 `s3:GetObject` 許可，以讀取要複製的來源物件。如需詳細資訊，請參閱 Amazon Simple Storage Service API 參考**中的 [https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html)。 **加密** Amazon S3 會自動加密上傳到 S3 儲存貯體的所有新物件。S3 儲存貯體的預設加密組態一律為啟用狀態，且最低限度設定為使用 Amazon S3 受管金鑰 (SSE-S3) 的伺服器端加密。對於目錄儲存貯體，支援使用 AWS Key Management Service (AWS KMS) 金鑰 (SSE-KMS) 的 SSE-S3 和伺服器端加密。當目的地儲存貯體是目錄儲存貯體時，建議目的地儲存貯體的預設加密使用所需的加密組態，而且您不會覆寫儲存貯體的預設加密。然後，新的物件會以所需的加密設定自動加密。此外，當您透過 [https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html)，將 SSE-KMS 加密物件從一般用途儲存貯體複製到目錄儲存貯體、從目錄儲存貯體複製到一般用途儲存貯體或在目錄儲存貯體之間複製時，不支援 S3 儲存貯體金鑰。在此情況下，Amazon S3 AWS KMS 每次對 KMS 加密物件提出複製請求時都會呼叫。如需在目錄儲存貯體中覆寫加密行為的詳細資訊，請參閱[使用指定伺服器端加密 AWS KMS 以進行新物件上傳](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-specifying-kms-encryption.html)。對於一般用途儲存貯體，您可以使用 SSE-S3 （預設值）、伺服器端加密搭配 AWS Key Management Service (AWS KMS) 金鑰 (SSE-KMS)、雙層伺服器端加密搭配 AWS KMS 金鑰 (DSSE-KMS)，或伺服器端加密搭配客戶提供的金鑰 (SSE-C)。如果您提出複製請求，指定對目錄儲存貯體 (來源或目的地儲存貯體) 使用 DSSE-KMS 或 SSE-C，回應會傳回錯誤。 **Tags (標籤)** 目錄儲存貯體不支援標籤。如果您將具有標籤的物件從一般用途儲存貯體複製到目錄儲存貯體，您會收到 HTTP `501 (Not Implemented)` 回應。如需詳細資訊，請參閱 Amazon Simple Storage Service API 參考**中的 [https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html)。 **ETag** S3 Express One Zone 的實體標籤 (ETag) 是隨機的英數字串，而不是 MD5 檢查總和。為了協助確保物件完整性，請使用額外的檢查總和。 **其他檢查總和** S3 Express One Zone 可讓您選擇用於在上傳或下載過程中驗證資料的檢查總和演算法選項。您可以選擇以下 Secure Hash 演算法 (SHA) 或循環宂餘檢查 (CRC) 資料完整性演算法之一：CRC32、CRC32C、SHA-1 和 SHA-256。S3 Express One Zone 儲存類別不支援 MD5 型檢查總和。如需詳細資訊，請參閱[S3 其他檢查總和最佳實務](s3-express-optimizing-performance.md#s3-express-optimizing-performance-checksums)。 **支援的功能** 如需 S3 Express One Zone 支援哪些 Amazon S3 功能的詳細資訊，請參閱[目錄儲存貯體的不同之處](s3-express-differences.md)。 ## 使用 S3 主控台 (複製到目錄儲存貯體) **注意** 當您使用主控台將物件複製到目錄儲存貯體時，您有下列限制： `Copy` 動作會套用至指定資料夾中 (指定字首) 的所有物件。在動作進行期間加入這些資料夾的物件可能會受到影響。使用客戶提供的加密金鑰 (SSE-C) 加密的物件無法經由 S3 主控台複製。若要複製使用 SSE-C 加密的物件，請使用 AWS CLI、 AWS SDK 或 Amazon S3 REST API。複製的物件不會保留原始物件的物件鎖定設定。如果複製物件的來源儲存貯體使用儲存貯體擁有者強制執行的 S3 物件擁有權設定，則不會將物件 ACL 複製到指定的目的地。如果您想要將物件複製到使用儲存貯體擁有者強制執行的 S3 物件擁有權設定的儲存貯體，請確定來源儲存貯體也使用儲存貯體擁有者強制執行的設定，或移除任何物件 ACL 授予其他 AWS 帳戶和群組。從一般用途儲存貯體複製到目錄儲存貯體的物件不會保留物件標籤、ACL 或 Etag 值。檢查總和值可以複製，但不等同於 Etag。檢查總和值與新增時相比可能有所變更。複製到目錄儲存貯體的所有物件都會具有儲存貯體擁有者強制執行的 S3 物件擁有權設定。 **將物件從一般用途儲存貯體複製到目錄儲存貯體或從一個目錄儲存貯體複製到另一個目錄儲存貯體** 1. 登入 AWS 管理主控台並開啟位於 https：//[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/) 的 Amazon S3 主控台。 1. 在左側導覽窗格中，您要從中複製物件的儲存貯體類型： + 若要從一般用途儲存貯體進行複製，請選擇**一般用途儲存貯體**索引標籤。 + 若要從目錄儲存貯體進行複製，請選擇**目錄儲存貯體**索引標籤。 1. 選擇包含您要複製之物件的一般用途儲存貯體或目錄儲存貯體。 1. 選擇 **Objects** (物件) 索引標籤。在**物件**頁面上，選取您要複製之物件名稱左側的核取方塊。 1. 在 **Actions (動作)** 功能表上，選擇 **Copy (複製)**。 **複製**頁面隨即出現。 1. 在**目的地**下，選擇**目錄儲存貯體**作為目的地類型。若要指定目的地路徑，請選擇**瀏覽 S3**，導覽至目的地，然後選擇目的地左側的選項按鈕。選擇右下角的 **Choose destination** (選擇目的地)。或者，輸入目的地路徑。 1. 在**其他複製設定**下，選擇**複製來源設定**、**不要指定設定**或**指定設定**。**複製來源設定**是預設選項。如果您只想複製物件但不想包含來源設定屬性，請選擇**不要指定設定**。選擇**指定設定**以指定伺服器端加密、檢查總和及中繼資料的設定。 1. 選擇右下角的 **Copy** (複製)。Amazon S3 會將您的物件複製到目的地。 ## 使用 S3 主控台 (複製到一般用途儲存貯體) **注意** 當您使用主控台將物件複製到一般用途儲存貯體時，您有下列限制： `Copy` 動作會套用至指定資料夾中 (指定字首) 的所有物件。在動作進行期間加入這些資料夾的物件可能會受到影響。使用客戶提供的加密金鑰 (SSE-C) 加密的物件無法經由 S3 主控台複製。若要複製使用 SSE-C 加密的物件，請使用 AWS CLI、 AWS SDK 或 Amazon S3 REST API。複製的物件不會保留原始物件的物件鎖定設定。如果複製物件的來源儲存貯體使用儲存貯體擁有者強制執行的 S3 物件擁有權設定，則不會將物件 ACL 複製到指定的目的地。如果您想要將物件複製到使用儲存貯體擁有者強制執行的 S3 物件擁有權設定的儲存貯體，請確定來源儲存貯體也使用儲存貯體擁有者強制執行的設定，或移除任何物件 ACL 授予其他 AWS 帳戶和群組。 **將物件從目錄儲存貯體複製到一般用途儲存貯體** 1. 登入 AWS 管理主控台並開啟位於 https：//[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/) 的 Amazon S3 主控台。 1. 在左側導覽窗格中，選擇 **Buckets** (儲存貯體)。 1. 選擇**目錄儲存貯體**索引標籤。 1. 選擇包含您要複製之物件的目錄儲存貯體。 1. 選擇 **Objects** (物件) 索引標籤。在**物件**頁面上，選取您要複製之物件名稱左側的核取方塊。 1. 在 **Actions (動作)** 功能表上，選擇 **Copy (複製)**。 1. 在**目的地**下，選擇**一般用途儲存貯體**作為目的地類型。若要指定目的地路徑，請選擇**瀏覽 S3**，導覽至目的地，然後選擇目的地左側的選項按鈕。選擇右下角的 **Choose destination** (選擇目的地)。或者，輸入目的地路徑。 1. 在**其他複製設定**下，選擇**複製來源設定**、**不要指定設定**或**指定設定**。**複製來源設定**是預設選項。如果您只想複製物件但不想包含來源設定屬性，請選擇**不要指定設定**。選擇**指定設定**以指定儲存類別、ACL、物件標籤、中繼資料、伺服器端加密和額外檢查總和的設定。 1. 選擇右下角的 **Copy** (複製)。Amazon S3 會將您的物件複製到目的地。 ## 使用 AWS SDKs ------ #### [ SDK for Java 2.x ] **Example** ``` public static void copyBucketObject (S3Client s3, String sourceBucket, String objectKey, String targetBucket) { CopyObjectRequest copyReq = CopyObjectRequest.builder() .sourceBucket(sourceBucket) .sourceKey(objectKey) .destinationBucket(targetBucket) .destinationKey(objectKey) .build(); String temp = ""; try { CopyObjectResponse copyRes = s3.copyObject(copyReq); System.out.println("Successfully copied " + objectKey +" from bucket " + sourceBucket +" into bucket "+targetBucket); } catch (S3Exception e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } } ``` ------ ## 使用 AWS CLI 下列`copy-object`範例命令顯示如何使用 AWS CLI 將物件從一個儲存貯體複製到另一個儲存貯體。您可以在儲存貯體類型之間複製物件。若要執行此命令，請以您自己的資訊取代使用者輸入預留位置。 ``` aws s3api copy-object --copy-source SOURCE_BUCKET/SOURCE_KEY_NAME --key TARGET_KEY_NAME --bucket TARGET_BUCKET_NAME ``` 如需詳細資訊，請參閱《AWS CLI 命令參考》**中的 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/copy-object.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/copy-object.html)。 # 從目錄儲存貯體中刪除物件您可以使用 Amazon S3 主控台、 AWS Command Line Interface (AWS CLI) 或 AWS SDKs 從 Amazon S3 目錄儲存貯體刪除物件。如需詳細資訊，請參閱[使用目錄儲存貯體](directory-buckets-overview.md)及[S3 Express One Zone](directory-bucket-high-performance.md#s3-express-one-zone)。 **警告** 刪除物件無法復原。此動作會刪除所有指定的物件。刪除資料夾時，請等待刪除動作完成，然後再將新物件加入至資料夾。否則，系統也可能會刪除新物件。 **注意** 當您以程式設計方式從目錄儲存貯體中刪除多個物件時，請注意下列事項： `DeleteObjects` 請求中的物件索引鍵必須至少包含一個非空格字元。不支援只包含空格字元的字串。 `DeleteObjects` 請求中的物件金鑰不得包含 Unicode 控制字元，但新行字元 (`\n`)、定位字元 (`\t`) 和歸位字元 (`\r`) 則除外。 ## 使用 S3 主控台 **刪除物件** 1. 登入 AWS 管理主控台，並在 https：//[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/) 開啟 Amazon S3 主控台。 1. 在左側導覽窗格中，選擇**目錄儲存貯體**。 1. 選擇包含您要刪除之物件的目錄儲存貯體。 1. 選擇 **Objects** (物件) 索引標籤。在**物件**清單中，選取您要刪除之一或多個物件左側的核取方塊。 1. 選擇 **刪除**。 1. 在**刪除物件**頁面上的文字方塊中輸入 **permanently delete**。 1. 選擇 **Delete objects** (刪除物件)。 ## 使用 AWS SDKs ------ #### [ SDK for Java 2.x ] **Example** 下列範例使用 AWS SDK for Java 2.x刪除目錄儲存貯體中的物件。 ``` static void deleteObject(S3Client s3Client, String bucketName, String objectKey) { try { DeleteObjectRequest del = DeleteObjectRequest.builder() .bucket(bucketName) .key(objectKey) .build(); s3Client.deleteObject(del); System.out.println("Object " + objectKey + " has been deleted"); } catch (S3Exception e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } } ``` ------ #### [ SDK for Python ] **Example** 下列範例使用適用於 Python (Boto3) 的 AWS SDK刪除目錄儲存貯體中的物件。 ``` import logging import boto3 from botocore.exceptions import ClientError def delete_objects(s3_client, bucket_name, objects): ''' Delete a list of objects in a directory bucket :param s3_client: boto3 S3 client :param bucket_name: Bucket that contains objects to be deleted; for example, 'doc-example-bucket--usw2-az1--x-s3' :param objects: List of dictionaries that specify the key names to delete :return: Response output, else False ''' try: response = s3_client.delete_objects( Bucket = bucket_name, Delete = { 'Objects': objects } ) return response except ClientError as e: logging.error(e) return False if __name__ == '__main__': region = 'us-west-2' bucket_name = 'BUCKET_NAME' objects = [ { 'Key': '0.txt' }, { 'Key': '1.txt' }, { 'Key': '2.txt' }, { 'Key': '3.txt' }, { 'Key': '4.txt' } ] s3_client = boto3.client('s3', region_name = region) results = delete_objects(s3_client, bucket_name, objects) if results is not None: if 'Deleted' in results: print (f'Deleted {len(results["Deleted"])} objects from {bucket_name}') if 'Errors' in results: print (f'Failed to delete {len(results["Errors"])} objects from {bucket_name}') ``` ------ ## 使用 AWS CLI 下列 `delete-object` 範例命令示範如何使用 AWS CLI 從儲存貯體中刪除物件。若要執行此命令，請以您自己的資訊取代 `user input placeholders`。 ``` aws s3api delete-object --bucket bucket-base-name--zone-id--x-s3 --key KEY_NAME ``` 如需詳細資訊，請參閱《AWS CLI 命令參考》**中的 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/delete-object.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/delete-object.html)。下列 `delete-objects` 範例命令示範如何使用 AWS CLI 從目錄儲存貯體刪除物件。若要執行此命令，請以您自己的資訊取代 `user input placeholders`。 `delete.json` 檔案如下所示： ``` { "Objects": [ { "Key": "0.txt" }, { "Key": "1.txt" }, { "Key": "2.txt" }, { "Key": "3.txt" } ] } ``` `delete-objects` 範例命令如下所示： ``` aws s3api delete-objects --bucket bucket-base-name--zone-id--x-s3 --delete file://delete.json ``` 如需詳細資訊，請參閱《AWS CLI 命令參考》**中的 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/delete-objects.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/delete-objects.html)。 # 從目錄儲存貯體下載物件下列程式碼範例示範如何使用 `GetObject` API 操作，從 Amazon S3 目錄儲存貯體中的物件讀取 (下載) 資料。 ## 使用 AWS SDKs ------ #### [ SDK for Java 2.x ] **Example** 下列程式碼範例示範如何使用 AWS SDK for Java 2.x，從目錄儲存貯體中的物件讀取資料。 ``` public static void getObject(S3Client s3Client, String bucketName, String objectKey) { try { GetObjectRequest objectRequest = GetObjectRequest .builder() .key(objectKey) .bucket(bucketName) .build(); ResponseBytes GetObjectResponse objectBytes = s3Client.getObjectAsBytes(objectRequest); byte[] data = objectBytes.asByteArray(); //Print object contents to console String s = new String(data, StandardCharsets.UTF_8); System.out.println(s); } catch (S3Exception e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } } ``` ------ #### [ SDK for Python ] **Example** 下列程式碼範例示範如何使用適用於 Python (Boto3) 的 AWS SDK，從目錄儲存貯體中的物件讀取資料。 ``` import boto3 from botocore.exceptions import ClientError from botocore.response import StreamingBody def get_object(s3_client: boto3.client, bucket_name: str, key_name: str) -> StreamingBody: """ Gets the object. :param s3_client: :param bucket_name: The bucket that contains the object. :param key_name: The key of the object to be downloaded. :return: The object data in bytes. """ try: response = s3_client.get_object(Bucket=bucket_name, Key=key_name) body = response['Body'].read() print(f"Got object '{key_name}' from bucket '{bucket_name}'.") except ClientError: print(f"Couldn't get object '{key_name}' from bucket '{bucket_name}'.") raise else: return body def main(): s3_client = boto3.client('s3') resp = get_object(s3_client, 'doc-example-bucket--use1-az4--x-s3', 'sample.txt') print(resp) if __name__ == "__main__": main() ``` ------ ## 使用 AWS CLI 以下 `get-object` 範例命令顯示如何使用 AWS CLI 從 Amazon S3 下載物件。此命令會從目錄儲存貯體 `bucket-base-name--zone-id--x-s3` 取得物件 `KEY_NAME`。物件將下載到名為 `LOCAL_FILE_NAME` 的檔案中。若要執行此命令，請以您自己的資訊取代 `user input placeholders`。 ``` aws s3api get-object --bucket bucket-base-name--zone-id--x-s3 --key KEY_NAME LOCAL_FILE_NAME ``` 如需詳細資訊，請參閱《AWS CLI 命令參考》**中的 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/get-object.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/get-object.html)。 # 產生預先簽章的 URL 以共用物件目錄儲存貯體下列程式碼範例示範如何產生預先簽章的 URL，以從 Amazon S3 目錄儲存貯體共用物件。 ## 使用 AWS CLI 下列範例命令示範如何使用 AWS CLI ，針對 Amazon S3 的物件產生預先簽章的 URL。此命令會針對來自目錄儲存貯體 `bucket-base-name--zone-id--x-s3` 的物件 `KEY_NAME`，產生預先簽章的 URL。若要執行此命令，請以您自己的資訊取代 `user input placeholders`。 ``` aws s3 presign s3://bucket-base-name--zone-id--x-s3/KEY_NAME --expires-in 7200 ``` 如需詳細資訊，請參閱《AWS CLI 命令參考》**中的 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3/presign.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3/presign.html)。 # 從目錄儲存貯體擷取物件中繼資料下列 AWS SDK 和 AWS CLI 範例示範如何使用 `HeadObject`和 `GetObjectAttributes` API 操作，從 Amazon S3 目錄儲存貯體中的物件擷取中繼資料，而不傳回物件本身。 ## 使用 AWS SDKs ------ #### [ SDK for Java 2.x ] **Example** ``` public static void headObject(S3Client s3Client, String bucketName, String objectKey) { try { HeadObjectRequest headObjectRequest = HeadObjectRequest .builder() .bucket(bucketName) .key(objectKey) .build(); HeadObjectResponse response = s3Client.headObject(headObjectRequest); System.out.format("Amazon S3 object: \"%s\" found in bucket: \"%s\" with ETag: \"%s\"", objectKey, bucketName, response.eTag()); } catch (S3Exception e) { System.err.println(e.awsErrorDetails().errorMessage()); ``` ------ ## 使用 AWS CLI 下列`head-object`範例命令顯示如何使用從物件 AWS CLI 擷取中繼資料。若要執行此命令，請以您自己的資訊取代 `user input placeholders`。 ``` aws s3api head-object --bucket bucket-base-name--zone-id--x-s3 --key KEY_NAME ``` 如需詳細資訊，請參閱《AWS CLI 命令參考》**中的 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/head-object.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/head-object.html)。下列`get-object-attributes`範例命令顯示如何使用從物件 AWS CLI 擷取中繼資料。若要執行此命令，請以您自己的資訊取代 `user input placeholders`。 ``` aws s3api get-object-attributes --bucket bucket-base-name--zone-id--x-s3 --key KEY_NAME --object-attributes "StorageClass" "ETag" "ObjectSize" ``` 如需詳細資訊，請參閱《AWS CLI 命令參考》**中的 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/get-object-attributes.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/get-object-attributes.html)。 # 列示目錄儲存貯體中的物件下列程式碼範例示範如何使用 `ListObjectsV2` API 操作，列出 Amazon S3 目錄儲存貯體中的物件的範例。 ## 使用 AWS CLI 下列 `list-objects-v2` 範例命令示範如何使用 AWS CLI 列出來自 Amazon S3 的物件。此命令會列出目錄儲存貯體 `bucket-base-name--zone-id--x-s3` 的物件。若要執行此命令，請以您自己的資訊取代 `user input placeholders`。 ``` aws s3api list-objects-v2 --bucket bucket-base-name--zone-id--x-s3 ``` 如需詳細資訊，請參閱《AWS CLI 命令參考》**中的 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/list-objects-v2.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/list-objects-v2.html)。