文档 AWS SDK 示例 GitHub 存储库中还有更多 [S AWS DK 示例](https://github.com/awsdocs/aws-doc-sdk-examples)。
本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 使用 S3 目录存储桶的代码示例 AWS SDKs
以下代码示例向您展示了如何将 Amazon S3 目录存储桶与 AWS 软件开发套件 (SDK) 一起使用。
*基本功能*是向您展示如何在服务中执行基本操作的代码示例。
*操作*是大型程序的代码摘录，必须在上下文中运行。您可以通过操作了解如何调用单个服务函数，还可以通过函数相关场景的上下文查看操作。
*场景*是向您展示如何通过在一个服务中调用多个函数或与其他 AWS 服务服务结合来完成特定任务的代码示例。
**更多资源**
+ **[ S3 目录存储桶用户指南](https://docs.aws.amazon.com/AmazonS3/latest/userguide/directory-buckets-overview.html)**——获取有关 S3 目录存储桶的更多信息。
+ **[S3 目录存储桶 API 参考](https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html)**——所有可用 S3 目录存储桶操作的详细信息。
+ **[AWS 开发者中心](https://aws.amazon.com/developer/code-examples/?awsf.sdk-code-examples-product=product%23)** — 您可以按类别或全文搜索筛选的代码示例。
+ **[AWS SDK 示例](https://github.com/awsdocs/aws-doc-sdk-examples)** — 包含首选语言完整代码的 GitHub 存储库。包括有关设置和运行代码的说明。
**Contents**
+ [基本功能](s3-directory-buckets_code_examples_basics.md)
+ [Hello Amazon S3 目录存储桶](s3-directory-buckets_example_s3-directory-buckets_Hello_section.md)
+ [了解基本功能](s3-directory-buckets_example_s3-directory-buckets_Scenario_ExpressBasics_section.md)
+ [操作](s3-directory-buckets_code_examples_actions.md)
+ [`AbortMultipartUpload`](s3-directory-buckets_example_s3-directory-buckets_AbortMultipartUpload_section.md)
+ [`CompleteMultipartUpload`](s3-directory-buckets_example_s3-directory-buckets_CompleteMultipartUpload_section.md)
+ [`CopyObject`](s3-directory-buckets_example_s3-directory-buckets_CopyObject_section.md)
+ [`CreateBucket`](s3-directory-buckets_example_s3-directory-buckets_CreateBucket_section.md)
+ [`CreateMultipartUpload`](s3-directory-buckets_example_s3-directory-buckets_CreateMultipartUpload_section.md)
+ [`CreateSession`](s3-directory-buckets_example_s3-directory-buckets_CreateSession_section.md)
+ [`DeleteBucket`](s3-directory-buckets_example_s3-directory-buckets_DeleteBucket_section.md)
+ [`DeleteBucketEncryption`](s3-directory-buckets_example_s3-directory-buckets_DeleteBucketEncryption_section.md)
+ [`DeleteBucketPolicy`](s3-directory-buckets_example_s3-directory-buckets_DeleteBucketPolicy_section.md)
+ [`DeleteObject`](s3-directory-buckets_example_s3-directory-buckets_DeleteObject_section.md)
+ [`DeleteObjects`](s3-directory-buckets_example_s3-directory-buckets_DeleteObjects_section.md)
+ [`GetBucketEncryption`](s3-directory-buckets_example_s3-directory-buckets_GetBucketEncryption_section.md)
+ [`GetBucketPolicy`](s3-directory-buckets_example_s3-directory-buckets_GetBucketPolicy_section.md)
+ [`GetObject`](s3-directory-buckets_example_s3-directory-buckets_GetObject_section.md)
+ [`GetObjectAttributes`](s3-directory-buckets_example_s3-directory-buckets_GetObjectAttributes_section.md)
+ [`HeadBucket`](s3-directory-buckets_example_s3-directory-buckets_HeadBucket_section.md)
+ [`HeadObject`](s3-directory-buckets_example_s3-directory-buckets_HeadObject_section.md)
+ [`ListDirectoryBuckets`](s3-directory-buckets_example_s3-directory-buckets_ListDirectoryBuckets_section.md)
+ [`ListMultipartUploads`](s3-directory-buckets_example_s3-directory-buckets_ListMultipartUploads_section.md)
+ [`ListObjectsV2`](s3-directory-buckets_example_s3-directory-buckets_ListObjectsV2_section.md)
+ [`ListParts`](s3-directory-buckets_example_s3-directory-buckets_ListParts_section.md)
+ [`PutBucketEncryption`](s3-directory-buckets_example_s3-directory-buckets_PutBucketEncryption_section.md)
+ [`PutBucketPolicy`](s3-directory-buckets_example_s3-directory-buckets_PutBucketPolicy_section.md)
+ [`PutObject`](s3-directory-buckets_example_s3-directory-buckets_PutObject_section.md)
+ [`UploadPart`](s3-directory-buckets_example_s3-directory-buckets_UploadPart_section.md)
+ [`UploadPartCopy`](s3-directory-buckets_example_s3-directory-buckets_UploadPartCopy_section.md)
+ [场景](s3-directory-buckets_code_examples_scenarios.md)
+ [创建预签名 URL 以获取对象](s3-directory-buckets_example_s3-directory-buckets_GeneratePresignedGetURLForDirectoryBucket_section.md)
# 使用 S3 目录存储桶的基本示例 AWS SDKs
以下代码示例展示了如何使用 Amazon S3 目录存储桶的基础知识。 AWS SDKs
**Contents**
+ [Hello Amazon S3 目录存储桶](s3-directory-buckets_example_s3-directory-buckets_Hello_section.md)
+ [了解基本功能](s3-directory-buckets_example_s3-directory-buckets_Scenario_ExpressBasics_section.md)
+ [操作](s3-directory-buckets_code_examples_actions.md)
+ [`AbortMultipartUpload`](s3-directory-buckets_example_s3-directory-buckets_AbortMultipartUpload_section.md)
+ [`CompleteMultipartUpload`](s3-directory-buckets_example_s3-directory-buckets_CompleteMultipartUpload_section.md)
+ [`CopyObject`](s3-directory-buckets_example_s3-directory-buckets_CopyObject_section.md)
+ [`CreateBucket`](s3-directory-buckets_example_s3-directory-buckets_CreateBucket_section.md)
+ [`CreateMultipartUpload`](s3-directory-buckets_example_s3-directory-buckets_CreateMultipartUpload_section.md)
+ [`CreateSession`](s3-directory-buckets_example_s3-directory-buckets_CreateSession_section.md)
+ [`DeleteBucket`](s3-directory-buckets_example_s3-directory-buckets_DeleteBucket_section.md)
+ [`DeleteBucketEncryption`](s3-directory-buckets_example_s3-directory-buckets_DeleteBucketEncryption_section.md)
+ [`DeleteBucketPolicy`](s3-directory-buckets_example_s3-directory-buckets_DeleteBucketPolicy_section.md)
+ [`DeleteObject`](s3-directory-buckets_example_s3-directory-buckets_DeleteObject_section.md)
+ [`DeleteObjects`](s3-directory-buckets_example_s3-directory-buckets_DeleteObjects_section.md)
+ [`GetBucketEncryption`](s3-directory-buckets_example_s3-directory-buckets_GetBucketEncryption_section.md)
+ [`GetBucketPolicy`](s3-directory-buckets_example_s3-directory-buckets_GetBucketPolicy_section.md)
+ [`GetObject`](s3-directory-buckets_example_s3-directory-buckets_GetObject_section.md)
+ [`GetObjectAttributes`](s3-directory-buckets_example_s3-directory-buckets_GetObjectAttributes_section.md)
+ [`HeadBucket`](s3-directory-buckets_example_s3-directory-buckets_HeadBucket_section.md)
+ [`HeadObject`](s3-directory-buckets_example_s3-directory-buckets_HeadObject_section.md)
+ [`ListDirectoryBuckets`](s3-directory-buckets_example_s3-directory-buckets_ListDirectoryBuckets_section.md)
+ [`ListMultipartUploads`](s3-directory-buckets_example_s3-directory-buckets_ListMultipartUploads_section.md)
+ [`ListObjectsV2`](s3-directory-buckets_example_s3-directory-buckets_ListObjectsV2_section.md)
+ [`ListParts`](s3-directory-buckets_example_s3-directory-buckets_ListParts_section.md)
+ [`PutBucketEncryption`](s3-directory-buckets_example_s3-directory-buckets_PutBucketEncryption_section.md)
+ [`PutBucketPolicy`](s3-directory-buckets_example_s3-directory-buckets_PutBucketPolicy_section.md)
+ [`PutObject`](s3-directory-buckets_example_s3-directory-buckets_PutObject_section.md)
+ [`UploadPart`](s3-directory-buckets_example_s3-directory-buckets_UploadPart_section.md)
+ [`UploadPartCopy`](s3-directory-buckets_example_s3-directory-buckets_UploadPartCopy_section.md)
# Hello Amazon S3 目录存储桶
以下代码示例演示如何开始使用 Amazon S3 目录存储桶。
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket#code-examples) 中查找完整示例，了解如何进行设置和运行。
```
package com.example.s3.directorybucket;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.Bucket;
import software.amazon.awssdk.services.s3.model.BucketInfo;
import software.amazon.awssdk.services.s3.model.BucketType;
import software.amazon.awssdk.services.s3.model.CreateBucketConfiguration;
import software.amazon.awssdk.services.s3.model.CreateBucketRequest;
import software.amazon.awssdk.services.s3.model.CreateBucketResponse;
import software.amazon.awssdk.services.s3.model.DataRedundancy;
import software.amazon.awssdk.services.s3.model.DeleteBucketRequest;
import software.amazon.awssdk.services.s3.model.ListDirectoryBucketsRequest;
import software.amazon.awssdk.services.s3.model.ListDirectoryBucketsResponse;
import software.amazon.awssdk.services.s3.model.LocationInfo;
import software.amazon.awssdk.services.s3.model.LocationType;
import software.amazon.awssdk.services.s3.model.S3Exception;
import java.util.List;
import java.util.stream.Collectors;
import static com.example.s3.util.S3DirectoryBucketUtils.createS3Client;
/**
* Before running this example:
*
* The SDK must be able to authenticate AWS requests on your behalf. If you have
* not configured
* authentication for SDKs and tools, see
* https://docs.aws.amazon.com/sdkref/latest/guide/access.html in the AWS SDKs
* and Tools Reference Guide.
*
* You must have a runtime environment configured with the Java SDK.
* See
* https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup.html in
* the Developer Guide if this is not set up.
*
* To use S3 directory buckets, configure a gateway VPC endpoint. This is the
* recommended method to enable directory bucket traffic without
* requiring an internet gateway or NAT device. For more information on
* configuring VPC gateway endpoints, visit
* https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-networking.html#s3-express-networking-vpc-gateway.
*
* Directory buckets are available in specific AWS Regions and Zones. For
* details on Regions and Zones supporting directory buckets, see
* https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-networking.html#s3-express-endpoints.
*/
public class HelloS3DirectoryBuckets {
private static final Logger logger = LoggerFactory.getLogger(HelloS3DirectoryBuckets.class);
public static void main(String[] args) {
String bucketName = "test-bucket-" + System.currentTimeMillis() + "--usw2-az1--x-s3";
Region region = Region.US_WEST_2;
String zone = "usw2-az1";
S3Client s3Client = createS3Client(region);
try {
// Create the directory bucket
createDirectoryBucket(s3Client, bucketName, zone);
logger.info("Created bucket: {}", bucketName);
// List all directory buckets
List bucketNames = listDirectoryBuckets(s3Client);
bucketNames.forEach(name -> logger.info("Bucket Name: {}", name));
} catch (S3Exception e) {
logger.error("An error occurred during S3 operations: {} - Error code: {}",
e.awsErrorDetails().errorMessage(), e.awsErrorDetails().errorCode(), e);
} finally {
try {
// Delete the created bucket
deleteDirectoryBucket(s3Client, bucketName);
logger.info("Deleted bucket: {}", bucketName);
} catch (S3Exception e) {
logger.error("Failed to delete the bucket due to S3 error: {} - Error code: {}",
e.awsErrorDetails().errorMessage(), e.awsErrorDetails().errorCode(), e);
} catch (RuntimeException e) {
logger.error("Failed to delete the bucket due to unexpected error: {}", e.getMessage(), e);
} finally {
s3Client.close();
}
}
}
/**
* Creates a new S3 directory bucket in a specified Zone (For example, a
* specified Availability Zone in this code example).
*
* @param s3Client The S3 client used to create the bucket
* @param bucketName The name of the bucket to be created
* @param zone The region where the bucket will be created
* @throws S3Exception if there's an error creating the bucket
*/
public static void createDirectoryBucket(S3Client s3Client, String bucketName, String zone) throws S3Exception {
logger.info("Creating bucket: {}", bucketName);
CreateBucketConfiguration bucketConfiguration = CreateBucketConfiguration.builder()
.location(LocationInfo.builder()
.type(LocationType.AVAILABILITY_ZONE)
.name(zone).build())
.bucket(BucketInfo.builder()
.type(BucketType.DIRECTORY)
.dataRedundancy(DataRedundancy.SINGLE_AVAILABILITY_ZONE)
.build())
.build();
try {
CreateBucketRequest bucketRequest = CreateBucketRequest.builder()
.bucket(bucketName)
.createBucketConfiguration(bucketConfiguration).build();
CreateBucketResponse response = s3Client.createBucket(bucketRequest);
logger.info("Bucket created successfully with location: {}", response.location());
} catch (S3Exception e) {
logger.error("Error creating bucket: {} - Error code: {}", e.awsErrorDetails().errorMessage(),
e.awsErrorDetails().errorCode(), e);
throw e;
}
}
/**
* Lists all S3 directory buckets.
*
* @param s3Client The S3 client used to interact with S3
* @return A list of bucket names
*/
public static List listDirectoryBuckets(S3Client s3Client) {
logger.info("Listing all directory buckets");
try {
// Create a ListBucketsRequest
ListDirectoryBucketsRequest listBucketsRequest = ListDirectoryBucketsRequest.builder().build();
// Retrieve the list of buckets
ListDirectoryBucketsResponse response = s3Client.listDirectoryBuckets(listBucketsRequest);
// Extract bucket names
List bucketNames = response.buckets().stream()
.map(Bucket::name)
.collect(Collectors.toList());
return bucketNames;
} catch (S3Exception e) {
logger.error("Failed to list buckets: {} - Error code: {}", e.awsErrorDetails().errorMessage(),
e.awsErrorDetails().errorCode(), e);
throw e;
}
}
/**
* Deletes the specified S3 directory bucket.
*
* @param s3Client The S3 client used to interact with S3
* @param bucketName The name of the bucket to delete
*/
public static void deleteDirectoryBucket(S3Client s3Client, String bucketName) {
try {
DeleteBucketRequest deleteBucketRequest = DeleteBucketRequest.builder()
.bucket(bucketName)
.build();
s3Client.deleteBucket(deleteBucketRequest);
} catch (S3Exception e) {
logger.error("Failed to delete bucket: " + bucketName + " - Error code: " + e.awsErrorDetails().errorCode(),
e);
throw e;
}
}
}
```
+ 有关 API 详细信息，请参阅《AWS SDK for Java 2.x API Reference》**中的以下主题。
+ [CreateBucket](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/CreateBucket)
+ [ListDirectoryBuckets](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/ListDirectoryBuckets)
------
# 使用 SDK 学习 S3 目录存储桶的基础知识 AWS
以下代码示例演示了如何：
+ 设置 VPC 和 VPC 端点。
+ 设置策略、角色和用户，以使用 S3 目录存储桶和 S3 Express One Zone 存储类别。
+ 创建两个 S3 客户端。
+ 创建两个存储桶。
+ 创建一个对象并复制它。
+ 演示性能差异。
+ 填充存储桶以显示按字典顺序的差异。
+ 提示用户查看他们是否要清理资源。
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3#code-examples)中查找完整示例，了解如何进行设置和运行。
运行一个交互式场景，演示 Amazon S3 的功能。
```
public class S3DirectoriesScenario {
public static final String DASHES = new String(new char[80]).replace("\0", "-");
private static final Logger logger = LoggerFactory.getLogger(S3DirectoriesScenario.class);
static Scanner scanner = new Scanner(System.in);
private static S3AsyncClient mS3RegularClient;
private static S3AsyncClient mS3ExpressClient;
private static String mdirectoryBucketName;
private static String mregularBucketName;
private static String stackName = "cfn-stack-s3-express-basics--" + UUID.randomUUID();
private static String regularUser = "";
private static String vpcId = "";
private static String expressUser = "";
private static String vpcEndpointId = "";
private static final S3DirectoriesActions s3DirectoriesActions = new S3DirectoriesActions();
public static void main(String[] args) {
try {
s3ExpressScenario();
} catch (RuntimeException e) {
logger.info(e.getMessage());
}
}
// Runs the scenario.
private static void s3ExpressScenario() {
logger.info(DASHES);
logger.info("Welcome to the Amazon S3 Express Basics demo using AWS SDK for Java V2.");
logger.info("""
Let's get started! First, please note that S3 Express One Zone works best when working within the AWS infrastructure,
specifically when working in the same Availability Zone (AZ). To see the best results in this example and when you implement
directory buckets into your infrastructure, it is best to put your compute resources in the same AZ as your directory
bucket.
""");
waitForInputToContinue(scanner);
logger.info(DASHES);
// Create an optional VPC and create 2 IAM users.
UserNames userNames = createVpcUsers();
String expressUserName = userNames.getExpressUserName();
String regularUserName = userNames.getRegularUserName();
// Set up two S3 clients, one regular and one express,
// and two buckets, one regular and one directory.
setupClientsAndBuckets(expressUserName, regularUserName);
// Create an S3 session for the express S3 client and add objects to the buckets.
logger.info("Now let's add some objects to our buckets and demonstrate how to work with S3 Sessions.");
waitForInputToContinue(scanner);
String bucketObject = createSessionAddObjects();
// Demonstrate performance differences between regular and directory buckets.
demonstratePerformance(bucketObject);
// Populate the buckets to show the lexicographical difference between
// regular and express buckets.
showLexicographicalDifferences(bucketObject);
logger.info(DASHES);
logger.info("That's it for our tour of the basic operations for S3 Express One Zone.");
logger.info("Would you like to cleanUp the AWS resources? (y/n): ");
String response = scanner.next().trim().toLowerCase();
if (response.equals("y")) {
cleanUp(stackName);
}
}
/*
Delete resources created by this scenario.
*/
public static void cleanUp(String stackName) {
try {
if (mdirectoryBucketName != null) {
s3DirectoriesActions.deleteBucketAndObjectsAsync(mS3ExpressClient, mdirectoryBucketName).join();
}
logger.info("Deleted directory bucket " + mdirectoryBucketName);
mdirectoryBucketName = null;
if (mregularBucketName != null) {
s3DirectoriesActions.deleteBucketAndObjectsAsync(mS3RegularClient, mregularBucketName).join();
}
} catch (CompletionException ce) {
Throwable cause = ce.getCause();
if (cause instanceof S3Exception) {
logger.error("S3Exception occurred: {}", cause.getMessage(), ce);
} else {
logger.error("An unexpected error occurred: {}", cause.getMessage(), ce);
}
}
logger.info("Deleted regular bucket " + mregularBucketName);
mregularBucketName = null;
CloudFormationHelper.destroyCloudFormationStack(stackName);
}
private static void showLexicographicalDifferences(String bucketObject) {
logger.info(DASHES);
logger.info("""
7. Populate the buckets to show the lexicographical (alphabetical) difference
when object names are listed. Now let's explore how directory buckets store
objects in a different manner to regular buckets. The key is in the name
"Directory". Where regular buckets store their key/value pairs in a
flat manner, directory buckets use actual directories/folders.
This allows for more rapid indexing, traversing, and therefore
retrieval times!
The more segmented your bucket is, with lots of
directories, sub-directories, and objects, the more efficient it becomes.
This structural difference also causes `ListObject` operations to behave
differently, which can cause unexpected results. Let's add a few more
objects in sub-directories to see how the output of
ListObjects changes.
""");
waitForInputToContinue(scanner);
// Populate a few more files in each bucket so that we can use
// ListObjects and show the difference.
String otherObject = "other/" + bucketObject;
String altObject = "alt/" + bucketObject;
String otherAltObject = "other/alt/" + bucketObject;
try {
s3DirectoriesActions.putObjectAsync(mS3RegularClient, mregularBucketName, otherObject, "").join();
s3DirectoriesActions.putObjectAsync(mS3ExpressClient, mdirectoryBucketName, otherObject, "").join();
s3DirectoriesActions.putObjectAsync(mS3RegularClient, mregularBucketName, altObject, "").join();
s3DirectoriesActions.putObjectAsync(mS3ExpressClient, mdirectoryBucketName, altObject, "").join();
s3DirectoriesActions.putObjectAsync(mS3RegularClient, mregularBucketName, otherAltObject, "").join();
s3DirectoriesActions.putObjectAsync(mS3ExpressClient, mdirectoryBucketName, otherAltObject, "").join();
} catch (CompletionException ce) {
Throwable cause = ce.getCause();
if (cause instanceof NoSuchBucketException) {
logger.error("S3Exception occurred: {}", cause.getMessage(), ce);
} else {
logger.error("An unexpected error occurred: {}", cause.getMessage(), ce);
}
return;
}
try {
// List objects in both S3 buckets.
List dirBucketObjects = s3DirectoriesActions.listObjectsAsync(mS3ExpressClient, mdirectoryBucketName).join();
List regBucketObjects = s3DirectoriesActions.listObjectsAsync(mS3RegularClient, mregularBucketName).join();
logger.info("Directory bucket content");
for (String obj : dirBucketObjects) {
logger.info(obj);
}
logger.info("Regular bucket content");
for (String obj : regBucketObjects) {
logger.info(obj);
}
} catch (CompletionException e) {
logger.error("Async operation failed: {} ", e.getCause().getMessage());
return;
}
logger.info("""
Notice how the regular bucket lists objects in lexicographical order, while the directory bucket does not. This is
because the regular bucket considers the whole "key" to be the object identifier, while the directory bucket actually
creates directories and uses the object "key" as a path to the object.
""");
waitForInputToContinue(scanner);
}
/**
* Demonstrates the performance difference between downloading an object from a directory bucket and a regular bucket.
*
* This method:
*
* - Prompts the user to choose the number of downloads (default is 1,000).
* - Downloads the specified object from the directory bucket and measures the total time.
* - Downloads the same object from the regular bucket and measures the total time.
* - Compares the time differences and prints the results.
*
*
* Note: The performance difference will be more pronounced if this example is run on an EC2 instance
* in the same Availability Zone as the buckets.
*
* @param bucketObject the name of the object to download
*/
private static void demonstratePerformance(String bucketObject) {
logger.info(DASHES);
logger.info("6. Demonstrate the performance difference.");
logger.info("""
Now, let's do a performance test. We'll download the same object from each
bucket repeatedly and compare the total time needed.
Note: the performance difference will be much more pronounced if this
example is run in an EC2 instance in the same Availability Zone as
the bucket.
""");
waitForInputToContinue(scanner);
int downloads = 1000; // Default value.
logger.info("The default number of downloads of the same object for this example is set at " + downloads + ".");
// Ask if the user wants to download a different number.
logger.info("Would you like to download the file a different number of times? (y/n): ");
String response = scanner.next().trim().toLowerCase();
if (response.equals("y")) {
int maxDownloads = 1_000_000;
// Ask for a valid number of downloads.
while (true) {
logger.info("Enter a number between 1 and " + maxDownloads + " for the number of downloads: ");
if (scanner.hasNextInt()) {
downloads = scanner.nextInt();
if (downloads >= 1 && downloads <= maxDownloads) {
break;
} else {
logger.info("Please enter a number between 1 and " + maxDownloads + ".");
}
} else {
logger.info("Invalid input. Please enter a valid integer.");
scanner.next();
}
}
logger.info("You have chosen to download {} items.", downloads);
} else {
logger.info("No changes made. Using default downloads: {}", downloads);
}
// Simulating the download process for the directory bucket.
logger.info("Downloading from the directory bucket.");
long directoryTimeStart = System.nanoTime();
for (int index = 0; index < downloads; index++) {
if (index % 50 == 0) {
logger.info("Download " + index + " of " + downloads);
}
try {
// Get the object from the directory bucket.
s3DirectoriesActions.getObjectAsync(mS3ExpressClient, mdirectoryBucketName, bucketObject).join();
} catch (CompletionException ce) {
Throwable cause = ce.getCause();
if (cause instanceof NoSuchKeyException) {
logger.error("S3Exception occurred: {}", cause.getMessage(), ce);
} else {
logger.error("An unexpected error occurred: {}", cause.getMessage(), ce);
}
return;
}
}
long directoryTimeDifference = System.nanoTime() - directoryTimeStart;
// Download from the regular bucket.
logger.info("Downloading from the regular bucket.");
long normalTimeStart = System.nanoTime();
for (int index = 0; index < downloads; index++) {
if (index % 50 == 0) {
logger.info("Download " + index + " of " + downloads);
}
try {
s3DirectoriesActions.getObjectAsync(mS3RegularClient, mregularBucketName, bucketObject).join();
} catch (CompletionException ce) {
Throwable cause = ce.getCause();
if (cause instanceof NoSuchKeyException) {
logger.error("S3Exception occurred: {}", cause.getMessage(), ce);
} else {
logger.error("An unexpected error occurred: {}", cause.getMessage(), ce);
}
return;
}
}
long normalTimeDifference = System.nanoTime() - normalTimeStart;
logger.info("The directory bucket took " + directoryTimeDifference + " nanoseconds, while the regular bucket took " + normalTimeDifference + " nanoseconds.");
long difference = normalTimeDifference - directoryTimeDifference;
logger.info("That's a difference of " + difference + " nanoseconds, or");
logger.info(difference / 1_000_000_000.0 + " seconds.");
if (difference < 0) {
logger.info("The directory buckets were slower. This can happen if you are not running on the cloud within a VPC.");
}
waitForInputToContinue(scanner);
}
private static String createSessionAddObjects() {
logger.info(DASHES);
logger.info("""
5. Create an object and copy it.
We'll create an object consisting of some text and upload it to the
regular bucket.
""");
waitForInputToContinue(scanner);
String bucketObject = "basic-text-object.txt";
try {
s3DirectoriesActions.putObjectAsync(mS3RegularClient, mregularBucketName, bucketObject, "Look Ma, I'm a bucket!").join();
s3DirectoriesActions.createSessionAsync(mS3ExpressClient, mdirectoryBucketName).join();
// Copy the object to the destination S3 bucket.
s3DirectoriesActions.copyObjectAsync(mS3ExpressClient, mregularBucketName, bucketObject, mdirectoryBucketName, bucketObject).join();
} catch (CompletionException ce) {
Throwable cause = ce.getCause();
if (cause instanceof S3Exception) {
logger.error("S3Exception occurred: {}", cause.getMessage(), ce);
} else {
logger.error("An unexpected error occurred: {}", cause.getMessage(), ce);
}
}
logger.info("""
It worked! This is because the S3Client that performed the copy operation
is the expressClient using the credentials for the user with permission to
work with directory buckets.
It's important to remember the user permissions when interacting with
directory buckets. Instead of validating permissions on every call as
regular buckets do, directory buckets utilize the user credentials and session
token to validate. This allows for much faster connection speeds on every call.
For single calls, this is low, but for many concurrent calls
this adds up to a lot of time saved.
""");
waitForInputToContinue(scanner);
return bucketObject;
}
/**
* Creates VPC users for the S3 Express One Zone scenario.
*
* This method performs the following steps:
*
* - Optionally creates a new VPC and VPC Endpoint if the application is running in an EC2 instance in the same Availability Zone as the directory buckets.
* - Creates two IAM users: one with S3 Express One Zone permissions and one without.
*
*
* @return a {@link UserNames} object containing the names of the created IAM users
*/
public static UserNames createVpcUsers() {
/*
Optionally create a VPC.
Create two IAM users, one with S3 Express One Zone permissions and one without.
*/
logger.info(DASHES);
logger.info("""
1. First, we'll set up a new VPC and VPC Endpoint if this program is running in an EC2 instance in the same AZ as your\s
directory buckets will be. Are you running this in an EC2 instance located in the same AZ as your intended directory buckets?
""");
logger.info("Do you want to setup a VPC Endpoint? (y/n)");
String endpointAns = scanner.nextLine().trim();
if (endpointAns.equalsIgnoreCase("y")) {
logger.info("""
Great! Let's set up a VPC, retrieve the Route Table from it, and create a VPC Endpoint to connect the S3 Client to.
""");
try {
s3DirectoriesActions.setupVPCAsync().join();
} catch (CompletionException ce) {
Throwable cause = ce.getCause();
if (cause instanceof Ec2Exception) {
logger.error("IamException occurred: {}", cause.getMessage(), ce);
} else {
logger.error("An unexpected error occurred: {}", cause.getMessage(), ce);
}
}
waitForInputToContinue(scanner);
} else {
logger.info("Skipping the VPC setup. Don't forget to use this in production!");
}
logger.info(DASHES);
logger.info("""
2. Create a RegularUser and ExpressUser by using the AWS CDK.
One IAM User, named RegularUser, will have permissions to work only
with regular buckets and one IAM user, named ExpressUser, will have
permissions to work only with directory buckets.
""");
waitForInputToContinue(scanner);
// Create two users required for this scenario.
Map stackOutputs = createUsersUsingCDK(stackName);
regularUser = stackOutputs.get("RegularUser");
expressUser = stackOutputs.get("ExpressUser");
UserNames names = new UserNames();
names.setRegularUserName(regularUser);
names.setExpressUserName(expressUser);
return names;
}
/**
* Creates users using AWS CloudFormation.
*
* @return a {@link Map} of String keys and String values representing the stack outputs,
* which may include user-related information such as user names and IDs.
*/
public static Map createUsersUsingCDK(String stackName) {
logger.info("We'll use an AWS CloudFormation template to create the IAM users and policies.");
CloudFormationHelper.deployCloudFormationStack(stackName);
return CloudFormationHelper.getStackOutputsAsync(stackName).join();
}
/**
* Sets up the necessary clients and buckets for the S3 Express service.
*
* @param expressUserName the username for the user with S3 Express permissions
* @param regularUserName the username for the user with regular S3 permissions
*/
public static void setupClientsAndBuckets(String expressUserName, String regularUserName) {
Scanner locscanner = new Scanner(System.in);
String accessKeyIdforRegUser;
String secretAccessforRegUser;
try {
CreateAccessKeyResponse keyResponse = s3DirectoriesActions.createAccessKeyAsync(regularUserName).join();
accessKeyIdforRegUser = keyResponse.accessKey().accessKeyId();
secretAccessforRegUser = keyResponse.accessKey().secretAccessKey();
} catch (CompletionException ce) {
Throwable cause = ce.getCause();
if (cause instanceof IamException) {
logger.error("IamException occurred: {}", cause.getMessage(), ce);
} else {
logger.error("An unexpected error occurred: {}", cause.getMessage(), ce);
}
return;
}
String accessKeyIdforExpressUser;
String secretAccessforExpressUser;
try {
CreateAccessKeyResponse keyResponseExpress = s3DirectoriesActions.createAccessKeyAsync(expressUserName).join();
accessKeyIdforExpressUser = keyResponseExpress.accessKey().accessKeyId();
secretAccessforExpressUser = keyResponseExpress.accessKey().secretAccessKey();
} catch (CompletionException ce) {
Throwable cause = ce.getCause();
if (cause instanceof IamException) {
logger.error("IamException occurred: {}", cause.getMessage(), ce);
} else {
logger.error("An unexpected error occurred: {}", cause.getMessage(), ce);
}
return;
}
logger.info(DASHES);
logger.info("""
3. Create two S3Clients; one uses the ExpressUser's credentials and one uses the RegularUser's credentials.
The 2 S3Clients will use different credentials.
""");
waitForInputToContinue(locscanner);
try {
mS3RegularClient = createS3ClientWithAccessKeyAsync(accessKeyIdforRegUser, secretAccessforRegUser).join();
mS3ExpressClient = createS3ClientWithAccessKeyAsync(accessKeyIdforExpressUser, secretAccessforExpressUser).join();
} catch (CompletionException ce) {
Throwable cause = ce.getCause();
if (cause instanceof IllegalArgumentException) {
logger.error("An invalid argument exception occurred: {}", cause.getMessage(), ce);
} else {
logger.error("An unexpected error occurred: {}", cause.getMessage(), ce);
}
return;
}
logger.info("""
We can now use the ExpressUser client to make calls to S3 Express operations.
""");
waitForInputToContinue(locscanner);
logger.info(DASHES);
logger.info("""
4. Create two buckets.
Now we will create a directory bucket which is the linchpin of the S3 Express One Zone service. Directory buckets
behave differently from regular S3 buckets which we will explore here. We'll also create a regular bucket, put
an object into the regular bucket, and copy it to the directory bucket.
""");
logger.info("""
Now, let's choose an availability zone (AZ) for the directory bucket.
We'll choose one that is supported.
""");
String zoneId;
String regularBucketName;
try {
zoneId = s3DirectoriesActions.selectAvailabilityZoneIdAsync().join();
regularBucketName = "reg-bucket-" + System.currentTimeMillis();
} catch (CompletionException ce) {
Throwable cause = ce.getCause();
if (cause instanceof Ec2Exception) {
logger.error("EC2Exception occurred: {}", cause.getMessage(), ce);
} else {
logger.error("An unexpected error occurred: {}", cause.getMessage(), ce);
}
return;
}
logger.info("""
Now, let's create the actual directory bucket, as well as a regular bucket."
""");
String directoryBucketName = "test-bucket-" + System.currentTimeMillis() + "--" + zoneId + "--x-s3";
try {
s3DirectoriesActions.createDirectoryBucketAsync(mS3ExpressClient, directoryBucketName, zoneId).join();
logger.info("Created directory bucket {}", directoryBucketName);
} catch (CompletionException ce) {
Throwable cause = ce.getCause();
if (cause instanceof BucketAlreadyExistsException) {
logger.error("The bucket already exists. Moving on: {}", cause.getMessage(), ce);
} else {
logger.error("An unexpected error occurred: {}", cause.getMessage(), ce);
return;
}
}
// Assign to the data member.
mdirectoryBucketName = directoryBucketName;
try {
s3DirectoriesActions.createBucketAsync(mS3RegularClient, regularBucketName).join();
logger.info("Created regular bucket {} ", regularBucketName);
mregularBucketName = regularBucketName;
} catch (CompletionException ce) {
Throwable cause = ce.getCause();
if (cause instanceof BucketAlreadyExistsException) {
logger.error("The bucket already exists. Moving on: {}", cause.getMessage(), ce);
} else {
logger.error("An unexpected error occurred: {}", cause.getMessage(), ce);
return;
}
}
logger.info("Great! Both buckets were created.");
waitForInputToContinue(locscanner);
}
/**
* Creates an asynchronous S3 client with the specified access key and secret access key.
*
* @param accessKeyId the AWS access key ID
* @param secretAccessKey the AWS secret access key
* @return a {@link CompletableFuture} that asynchronously creates the S3 client
* @throws IllegalArgumentException if the access key ID or secret access key is null
*/
public static CompletableFuture createS3ClientWithAccessKeyAsync(String accessKeyId, String secretAccessKey) {
return CompletableFuture.supplyAsync(() -> {
// Validate input parameters
if (accessKeyId == null || accessKeyId.isBlank() || secretAccessKey == null || secretAccessKey.isBlank()) {
throw new IllegalArgumentException("Access Key ID and Secret Access Key must not be null or empty");
}
AwsBasicCredentials awsCredentials = AwsBasicCredentials.create(accessKeyId, secretAccessKey);
return S3AsyncClient.builder()
.credentialsProvider(StaticCredentialsProvider.create(awsCredentials))
.region(Region.US_WEST_2)
.build();
});
}
private static void waitForInputToContinue(Scanner scanner) {
while (true) {
logger.info("");
logger.info("Enter 'c' followed by to continue:");
String input = scanner.nextLine();
if (input.trim().equalsIgnoreCase("c")) {
logger.info("Continuing with the program...");
logger.info("");
break;
} else {
logger.info("Invalid input. Please try again.");
}
}
}
}
```
Amazon S3 SDK 方法的包装器类。
```
public class S3DirectoriesActions {
private static IamAsyncClient iamAsyncClient;
private static Ec2AsyncClient ec2AsyncClient;
private static final Logger logger = LoggerFactory.getLogger(S3DirectoriesActions.class);
private static IamAsyncClient getIAMAsyncClient() {
if (iamAsyncClient == null) {
SdkAsyncHttpClient httpClient = NettyNioAsyncHttpClient.builder()
.maxConcurrency(100)
.connectionTimeout(Duration.ofSeconds(60))
.readTimeout(Duration.ofSeconds(60))
.writeTimeout(Duration.ofSeconds(60))
.build();
ClientOverrideConfiguration overrideConfig = ClientOverrideConfiguration.builder()
.apiCallTimeout(Duration.ofMinutes(2))
.apiCallAttemptTimeout(Duration.ofSeconds(90))
.retryStrategy(RetryMode.STANDARD)
.build();
iamAsyncClient = IamAsyncClient.builder()
.httpClient(httpClient)
.overrideConfiguration(overrideConfig)
.build();
}
return iamAsyncClient;
}
private static Ec2AsyncClient getEc2AsyncClient() {
if (ec2AsyncClient == null) {
SdkAsyncHttpClient httpClient = NettyNioAsyncHttpClient.builder()
.maxConcurrency(100)
.connectionTimeout(Duration.ofSeconds(60))
.readTimeout(Duration.ofSeconds(60))
.writeTimeout(Duration.ofSeconds(60))
.build();
ClientOverrideConfiguration overrideConfig = ClientOverrideConfiguration.builder()
.apiCallTimeout(Duration.ofMinutes(2))
.apiCallAttemptTimeout(Duration.ofSeconds(90))
.retryStrategy(RetryMode.STANDARD)
.build();
ec2AsyncClient = Ec2AsyncClient.builder()
.httpClient(httpClient)
.region(Region.US_WEST_2)
.overrideConfiguration(overrideConfig)
.build();
}
return ec2AsyncClient;
}
/**
* Deletes the specified S3 bucket and all the objects within it asynchronously.
*
* @param s3AsyncClient the S3 asynchronous client to use for the operations
* @param bucketName the name of the S3 bucket to be deleted
* @return a {@link CompletableFuture} that completes with a {@link WaiterResponse} containing the
* {@link HeadBucketResponse} when the bucket has been successfully deleted
* @throws CompletionException if there was an error deleting the bucket or its objects
*/
public CompletableFuture> deleteBucketAndObjectsAsync(S3AsyncClient s3AsyncClient, String bucketName) {
ListObjectsV2Request listRequest = ListObjectsV2Request.builder()
.bucket(bucketName)
.build();
return s3AsyncClient.listObjectsV2(listRequest)
.thenCompose(listResponse -> {
if (!listResponse.contents().isEmpty()) {
List objectIdentifiers = listResponse.contents().stream()
.map(s3Object -> ObjectIdentifier.builder().key(s3Object.key()).build())
.collect(Collectors.toList());
DeleteObjectsRequest deleteRequest = DeleteObjectsRequest.builder()
.bucket(bucketName)
.delete(Delete.builder().objects(objectIdentifiers).build())
.build();
return s3AsyncClient.deleteObjects(deleteRequest)
.thenAccept(deleteResponse -> {
if (!deleteResponse.errors().isEmpty()) {
deleteResponse.errors().forEach(error ->
logger.error("Couldn't delete object " + error.key() + ". Reason: " + error.message()));
}
});
}
return CompletableFuture.completedFuture(null);
})
.thenCompose(ignored -> {
DeleteBucketRequest deleteBucketRequest = DeleteBucketRequest.builder()
.bucket(bucketName)
.build();
return s3AsyncClient.deleteBucket(deleteBucketRequest);
})
.thenCompose(ignored -> {
S3AsyncWaiter waiter = s3AsyncClient.waiter();
HeadBucketRequest headBucketRequest = HeadBucketRequest.builder().bucket(bucketName).build();
return waiter.waitUntilBucketNotExists(headBucketRequest);
})
.whenComplete((ignored, exception) -> {
if (exception != null) {
Throwable cause = exception.getCause();
if (cause instanceof S3Exception) {
throw new CompletionException("Error deleting bucket: " + bucketName, cause);
}
throw new CompletionException("Failed to delete bucket and objects: " + bucketName, exception);
}
logger.info("Bucket deleted successfully: " + bucketName);
});
}
/**
* Lists the objects in an S3 bucket asynchronously.
*
* @param s3Client the S3 async client to use for the operation
* @param bucketName the name of the S3 bucket containing the objects to list
* @return a {@link CompletableFuture} that contains the list of object keys in the specified bucket
*/
public CompletableFuture> listObjectsAsync(S3AsyncClient s3Client, String bucketName) {
ListObjectsV2Request request = ListObjectsV2Request.builder()
.bucket(bucketName)
.build();
return s3Client.listObjectsV2(request)
.thenApply(response -> response.contents().stream()
.map(S3Object::key)
.toList())
.whenComplete((result, exception) -> {
if (exception != null) {
throw new CompletionException("Couldn't list objects in bucket: " + bucketName, exception);
}
});
}
/**
* Retrieves an object from an Amazon S3 bucket asynchronously.
*
* @param s3Client the S3 async client to use for the operation
* @param bucketName the name of the S3 bucket containing the object
* @param keyName the unique identifier (key) of the object to retrieve
* @return a {@link CompletableFuture} that, when completed, contains the object's content as a {@link ResponseBytes} of {@link GetObjectResponse}
*/
public CompletableFuture> getObjectAsync(S3AsyncClient s3Client, String bucketName, String keyName) {
GetObjectRequest objectRequest = GetObjectRequest.builder()
.key(keyName)
.bucket(bucketName)
.build();
// Get the object asynchronously and transform it into a byte array
return s3Client.getObject(objectRequest, AsyncResponseTransformer.toBytes())
.exceptionally(exception -> {
Throwable cause = exception.getCause();
if (cause instanceof NoSuchKeyException) {
throw new CompletionException("Failed to get the object. Reason: " + ((S3Exception) cause).awsErrorDetails().errorMessage(), cause);
}
throw new CompletionException("Failed to get the object", exception);
});
}
/**
* Asynchronously copies an object from one S3 bucket to another.
*
* @param s3Client the S3 async client to use for the copy operation
* @param sourceBucket the name of the source bucket
* @param sourceKey the key of the object to be copied in the source bucket
* @param destinationBucket the name of the destination bucket
* @param destinationKey the key of the copied object in the destination bucket
* @return a {@link CompletableFuture} that completes when the copy operation is finished
*/
public CompletableFuture copyObjectAsync(S3AsyncClient s3Client, String sourceBucket, String sourceKey, String destinationBucket, String destinationKey) {
CopyObjectRequest copyRequest = CopyObjectRequest.builder()
.sourceBucket(sourceBucket)
.sourceKey(sourceKey)
.destinationBucket(destinationBucket)
.destinationKey(destinationKey)
.build();
return s3Client.copyObject(copyRequest)
.thenRun(() -> logger.info("Copied object '" + sourceKey + "' from bucket '" + sourceBucket + "' to bucket '" + destinationBucket + "'"))
.whenComplete((ignored, exception) -> {
if (exception != null) {
Throwable cause = exception.getCause();
if (cause instanceof S3Exception) {
throw new CompletionException("Couldn't copy object '" + sourceKey + "' from bucket '" + sourceBucket + "' to bucket '" + destinationBucket + "'. Reason: " + ((S3Exception) cause).awsErrorDetails().errorMessage(), cause);
}
throw new CompletionException("Failed to copy object", exception);
}
});
}
/**
* Asynchronously creates a session for the specified S3 bucket.
*
* @param s3Client the S3 asynchronous client to use for creating the session
* @param bucketName the name of the S3 bucket for which to create the session
* @return a {@link CompletableFuture} that completes when the session is created, or throws a {@link CompletionException} if an error occurs
*/
public CompletableFuture createSessionAsync(S3AsyncClient s3Client, String bucketName) {
CreateSessionRequest request = CreateSessionRequest.builder()
.bucket(bucketName)
.build();
return s3Client.createSession(request)
.whenComplete((response, exception) -> {
if (exception != null) {
Throwable cause = exception.getCause();
if (cause instanceof S3Exception) {
throw new CompletionException("Couldn't create the session. Reason: " + ((S3Exception) cause).awsErrorDetails().errorMessage(), cause);
}
throw new CompletionException("Unexpected error occurred while creating session", exception);
}
logger.info("Created session for bucket: " + bucketName);
});
}
/**
* Creates a new S3 directory bucket in a specified Zone (For example, a
* specified Availability Zone in this code example).
*
* @param s3Client The asynchronous S3 client used to create the bucket
* @param bucketName The name of the bucket to be created
* @param zone The Availability Zone where the bucket will be created
* @throws CompletionException if there's an error creating the bucket
*/
public CompletableFuture createDirectoryBucketAsync(S3AsyncClient s3Client, String bucketName, String zone) {
logger.info("Creating bucket: " + bucketName);
CreateBucketConfiguration bucketConfiguration = CreateBucketConfiguration.builder()
.location(LocationInfo.builder()
.type(LocationType.AVAILABILITY_ZONE)
.name(zone)
.build())
.bucket(BucketInfo.builder()
.type(BucketType.DIRECTORY)
.dataRedundancy(DataRedundancy.SINGLE_AVAILABILITY_ZONE)
.build())
.build();
CreateBucketRequest bucketRequest = CreateBucketRequest.builder()
.bucket(bucketName)
.createBucketConfiguration(bucketConfiguration)
.build();
return s3Client.createBucket(bucketRequest)
.whenComplete((response, exception) -> {
if (exception != null) {
Throwable cause = exception.getCause();
if (cause instanceof BucketAlreadyExistsException) {
throw new CompletionException("The bucket already exists: " + ((S3Exception) cause).awsErrorDetails().errorMessage(), cause);
}
throw new CompletionException("Unexpected error occurred while creating bucket", exception);
}
logger.info("Bucket created successfully with location: " + response.location());
});
}
/**
* Creates an S3 bucket asynchronously.
*
* @param s3Client the S3 async client to use for the bucket creation
* @param bucketName the name of the S3 bucket to create
* @return a {@link CompletableFuture} that completes with the {@link WaiterResponse} containing the {@link HeadBucketResponse}
* when the bucket is successfully created
* @throws CompletionException if there's an error creating the bucket
*/
public CompletableFuture> createBucketAsync(S3AsyncClient s3Client, String bucketName) {
CreateBucketRequest bucketRequest = CreateBucketRequest.builder()
.bucket(bucketName)
.build();
return s3Client.createBucket(bucketRequest)
.thenCompose(response -> {
S3AsyncWaiter s3Waiter = s3Client.waiter();
HeadBucketRequest bucketRequestWait = HeadBucketRequest.builder()
.bucket(bucketName)
.build();
return s3Waiter.waitUntilBucketExists(bucketRequestWait);
})
.whenComplete((response, exception) -> {
if (exception != null) {
Throwable cause = exception.getCause();
if (cause instanceof BucketAlreadyExistsException) {
throw new CompletionException("The S3 bucket exists: " + cause.getMessage(), cause);
} else {
throw new CompletionException("Failed to create access key: " + exception.getMessage(), exception);
}
}
logger.info(bucketName + " is ready");
});
}
/**
* Uploads an object to an Amazon S3 bucket asynchronously.
*
* @param s3Client the S3 async client to use for the upload
* @param bucketName the destination S3 bucket name
* @param bucketObject the name of the object to be uploaded
* @param text the content to be uploaded as the object
*/
public CompletableFuture putObjectAsync(S3AsyncClient s3Client, String bucketName, String bucketObject, String text) {
PutObjectRequest objectRequest = PutObjectRequest.builder()
.bucket(bucketName)
.key(bucketObject)
.build();
return s3Client.putObject(objectRequest, AsyncRequestBody.fromString(text))
.whenComplete((response, exception) -> {
if (exception != null) {
Throwable cause = exception.getCause();
if (cause instanceof NoSuchBucketException) {
throw new CompletionException("The S3 bucket does not exist: " + cause.getMessage(), cause);
} else {
throw new CompletionException("Failed to create access key: " + exception.getMessage(), exception);
}
}
});
}
/**
* Creates an AWS IAM access key asynchronously for the specified user name.
*
* @param userName the name of the IAM user for whom to create the access key
* @return a {@link CompletableFuture} that completes with the {@link CreateAccessKeyResponse} containing the created access key
*/
public CompletableFuture createAccessKeyAsync(String userName) {
CreateAccessKeyRequest request = CreateAccessKeyRequest.builder()
.userName(userName)
.build();
return getIAMAsyncClient().createAccessKey(request)
.whenComplete((response, exception) -> {
if (response != null) {
logger.info("Access Key Created.");
} else {
if (exception == null) {
Throwable cause = exception.getCause();
if (cause instanceof IamException) {
throw new CompletionException("IAM error while creating access key: " + cause.getMessage(), cause);
} else {
throw new CompletionException("Failed to create access key: " + exception.getMessage(), exception);
}
}
}
});
}
/**
* Asynchronously selects an Availability Zone ID from the available EC2 zones.
*
* @return A {@link CompletableFuture} that resolves to the selected Availability Zone ID.
* @throws CompletionException if an error occurs during the request or processing.
*/
public CompletableFuture selectAvailabilityZoneIdAsync() {
DescribeAvailabilityZonesRequest zonesRequest = DescribeAvailabilityZonesRequest.builder()
.build();
return getEc2AsyncClient().describeAvailabilityZones(zonesRequest)
.thenCompose(response -> {
List zonesList = response.availabilityZones();
if (zonesList.isEmpty()) {
logger.info("No availability zones found.");
return CompletableFuture.completedFuture(null); // Return null if no zones are found
}
List zoneIds = zonesList.stream()
.map(AvailabilityZone::zoneId) // Get the zoneId (e.g., "usw2-az1")
.toList();
return CompletableFuture.supplyAsync(() -> promptUserForZoneSelection(zonesList, zoneIds))
.thenApply(selectedZone -> {
// Return only the selected Zone ID (e.g., "usw2-az1").
return selectedZone.zoneId();
});
})
.whenComplete((result, exception) -> {
if (exception == null) {
if (result != null) {
logger.info("Selected Availability Zone ID: " + result);
} else {
logger.info("No availability zone selected.");
}
} else {
Throwable cause = exception.getCause();
if (cause instanceof Ec2Exception) {
throw new CompletionException("EC2 error while selecting availability zone: " + cause.getMessage(), cause);
}
throw new CompletionException("Failed to select availability zone: " + exception.getMessage(), exception);
}
});
}
/**
* Prompts the user to select an Availability Zone from the given list.
*
* @param zonesList the list of Availability Zones
* @param zoneIds the list of zone IDs
* @return the selected Availability Zone
*/
private static AvailabilityZone promptUserForZoneSelection(List zonesList, List zoneIds) {
Scanner scanner = new Scanner(System.in);
int index = -1;
while (index < 0 || index >= zoneIds.size()) {
logger.info("Select an availability zone:");
IntStream.range(0, zoneIds.size()).forEach(i ->
logger.info(i + ": " + zoneIds.get(i))
);
logger.info("Enter the number corresponding to your choice: ");
if (scanner.hasNextInt()) {
index = scanner.nextInt();
} else {
scanner.next();
}
}
AvailabilityZone selectedZone = zonesList.get(index);
logger.info("You selected: " + selectedZone.zoneId());
return selectedZone;
}
/**
* Asynchronously sets up a new VPC, including creating the VPC, finding the associated route table, and
* creating a VPC endpoint for the S3 service.
*
* @return a {@link CompletableFuture} that, when completed, contains a AbstractMap with the
* VPC ID and VPC endpoint ID.
*/
public CompletableFuture> setupVPCAsync() {
String cidr = "10.0.0.0/16";
CreateVpcRequest vpcRequest = CreateVpcRequest.builder()
.cidrBlock(cidr)
.build();
return getEc2AsyncClient().createVpc(vpcRequest)
.thenCompose(vpcResponse -> {
String vpcId = vpcResponse.vpc().vpcId();
logger.info("VPC Created: {}", vpcId);
Ec2AsyncWaiter waiter = getEc2AsyncClient().waiter();
DescribeVpcsRequest request = DescribeVpcsRequest.builder()
.vpcIds(vpcId)
.build();
return waiter.waitUntilVpcAvailable(request)
.thenApply(waiterResponse -> vpcId);
})
.thenCompose(vpcId -> {
Filter filter = Filter.builder()
.name("vpc-id")
.values(vpcId)
.build();
DescribeRouteTablesRequest describeRouteTablesRequest = DescribeRouteTablesRequest.builder()
.filters(filter)
.build();
return getEc2AsyncClient().describeRouteTables(describeRouteTablesRequest)
.thenApply(routeTablesResponse -> {
if (routeTablesResponse.routeTables().isEmpty()) {
throw new CompletionException("No route tables found for VPC: " + vpcId, null);
}
String routeTableId = routeTablesResponse.routeTables().get(0).routeTableId();
logger.info("Route table found: {}", routeTableId);
return new AbstractMap.SimpleEntry<>(vpcId, routeTableId);
});
})
.thenCompose(vpcAndRouteTable -> {
String vpcId = vpcAndRouteTable.getKey();
String routeTableId = vpcAndRouteTable.getValue();
Region region = getEc2AsyncClient().serviceClientConfiguration().region();
String serviceName = String.format("com.amazonaws.%s.s3express", region.id());
CreateVpcEndpointRequest endpointRequest = CreateVpcEndpointRequest.builder()
.vpcId(vpcId)
.routeTableIds(routeTableId)
.serviceName(serviceName)
.build();
return getEc2AsyncClient().createVpcEndpoint(endpointRequest)
.thenApply(vpcEndpointResponse -> {
String vpcEndpointId = vpcEndpointResponse.vpcEndpoint().vpcEndpointId();
logger.info("VPC Endpoint created: {}", vpcEndpointId);
return new AbstractMap.SimpleEntry<>(vpcId, vpcEndpointId);
});
})
.exceptionally(exception -> {
Throwable cause = exception.getCause() != null ? exception.getCause() : exception;
if (cause instanceof Ec2Exception) {
logger.error("EC2 error during VPC setup: {}", cause.getMessage(), cause);
throw new CompletionException("EC2 error during VPC setup: " + cause.getMessage(), cause);
}
logger.error("VPC setup failed: {}", cause.getMessage(), cause);
throw new CompletionException("VPC setup failed: " + cause.getMessage(), cause);
});
}
}
```
+ 有关 API 详细信息，请参阅《AWS SDK for Java 2.x API Reference》**中的以下主题。
+ [CopyObject](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/CopyObject)
+ [CreateBucket](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/CreateBucket)
+ [DeleteBucket](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/DeleteBucket)
+ [DeleteObject](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/DeleteObject)
+ [GetObject](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/GetObject)
+ [ListObjects](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/ListObjects)
+ [PutObject](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/PutObject)
------
#### [ PHP ]
**适用于 PHP 的 SDK**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code/s3/express#code-examples)中查找完整示例，了解如何进行设置和运行。
运行一个用于演示 Amazon S3 目录存储桶和 S3 Express One Zone 的基础知识的场景。
```
echo "\n";
echo "--------------------------------------\n";
echo "Welcome to the Amazon S3 Express Basics demo using PHP!\n";
echo "--------------------------------------\n";
// Change these both of these values to use a different region/availability zone.
$region = "us-west-2";
$az = "usw2-az1";
$this->s3Service = new S3Service(new S3Client(['region' => $region]));
$this->iamService = new IAMService(new IamClient(['region' => $region]));
$uuid = uniqid();
echo <<ec2Service = new EC2Service(new Ec2Client(['region' => $region]));
$cidr = "10.0.0.0/16";
$vpc = $this->ec2Service->createVpc($cidr);
$this->resources['vpcId'] = $vpc['VpcId'];
$this->ec2Service->waitForVpcAvailable($vpc['VpcId']);
$routeTable = $this->ec2Service->describeRouteTables([], [
[
'Name' => "vpc-id",
'Values' => [$vpc['VpcId']],
],
]);
$serviceName = "com.amazonaws." . $this->ec2Service->getRegion() . ".s3express";
$vpcEndpoint = $this->ec2Service->createVpcEndpoint($serviceName, $vpc['VpcId'], [$routeTable[0]]);
$this->resources['vpcEndpointId'] = $vpcEndpoint['VpcEndpointId'];
}else{
echo "Skipping the VPC setup. Don't forget to use this in production!\n";
}
// 2. Policies, user, and roles with CDK.
echo "\n";
echo "2. Policies, users, and roles with CDK.\n";
echo "Now, we'll set up some policies, roles, and a user. This user will only have permissions to do S3 Express One Zone actions.\n";
pressEnter();
$this->cloudFormationClient = new CloudFormationClient([]);
$stackName = "cfn-stack-s3-express-basics-" . uniqid();
$file = file_get_contents(__DIR__ . "/../../../../resources/cfn/s3_express_basics/s3_express_template.yml");
$result = $this->cloudFormationClient->createStack([
'StackName' => $stackName,
'TemplateBody' => $file,
'Capabilities' => ['CAPABILITY_IAM'],
]);
$waiter = $this->cloudFormationClient->getWaiter("StackCreateComplete", ['StackName' => $stackName]);
try {
$waiter->promise()->wait();
}catch(CloudFormationException $caught){
echo "Error waiting for the CloudFormation stack to create: {$caught->getAwsErrorMessage()}\n";
throw $caught;
}
$this->resources['stackName'] = $stackName;
$stackInfo = $this->cloudFormationClient->describeStacks([
'StackName' => $result['StackId'],
]);
$expressUserName = "";
$regularUserName = "";
foreach($stackInfo['Stacks'][0]['Outputs'] as $output) {
if ($output['OutputKey'] == "RegularUser") {
$regularUserName = $output['OutputValue'];
}
if ($output['OutputKey'] == "ExpressUser") {
$expressUserName = $output['OutputValue'];
}
}
$regularKey = $this->iamService->createAccessKey($regularUserName);
$regularCredentials = new Credentials($regularKey['AccessKeyId'], $regularKey['SecretAccessKey']);
$expressKey = $this->iamService->createAccessKey($expressUserName);
$expressCredentials = new Credentials($expressKey['AccessKeyId'], $expressKey['SecretAccessKey']);
// 3. Create an additional client using the credentials with S3 Express permissions.
echo "\n";
echo "3. Create an additional client using the credentials with S3 Express permissions.\n";
echo "This client is created with the credentials associated with the user account with the S3 Express policy attached, so it can perform S3 Express operations.\n";
pressEnter();
$s3RegularClient = new S3Client([
'Region' => $region,
'Credentials' => $regularCredentials,
]);
$s3RegularService = new S3Service($s3RegularClient);
$s3ExpressClient = new S3Client([
'Region' => $region,
'Credentials' => $expressCredentials,
]);
$s3ExpressService = new S3Service($s3ExpressClient);
echo "All the roles and policies were created an attached to the user. Then, a new S3 Client and Service were created using that user's credentials.\n";
echo "We can now use this client to make calls to S3 Express operations. Keeping permissions in mind (and adhering to least-privilege) is crucial to S3 Express.\n";
pressEnter();
// 4. Create two buckets.
echo "\n";
echo "3. Create two buckets.\n";
echo "Now we will create a Directory bucket, which is the linchpin of the S3 Express One Zone service.\n";
echo "Directory buckets behave in different ways from regular S3 buckets, which we will explore here.\n";
echo "We'll also create a normal bucket, put an object into the normal bucket, and copy it over to the Directory bucket.\n";
pressEnter();
// Create a directory bucket. These are different from normal S3 buckets in subtle ways.
$directoryBucketName = "s3-express-demo-directory-bucket-$uuid--$az--x-s3";
echo "Now, let's create the actual Directory bucket, as well as a regular bucket.\n";
pressEnter();
$s3ExpressService->createBucket($directoryBucketName, [
'CreateBucketConfiguration' => [
'Bucket' => [
'Type' => "Directory", // This is what causes S3 to create a Directory bucket as opposed to a normal bucket.
'DataRedundancy' => "SingleAvailabilityZone",
],
'Location' => [
'Name' => $az,
'Type' => "AvailabilityZone",
],
],
]);
$this->resources['directoryBucketName'] = $directoryBucketName;
// Create a normal bucket.
$normalBucketName = "normal-bucket-$uuid";
$s3RegularService->createBucket($normalBucketName);
$this->resources['normalBucketName'] = $normalBucketName;
echo "Great! Both buckets were created.\n";
pressEnter();
// 5. Create an object and copy it over.
echo "\n";
echo "5. Create an object and copy it over.\n";
echo "We'll create a basic object consisting of some text and upload it to the normal bucket.\n";
echo "Next, we'll copy the object into the Directory bucket using the regular client.\n";
echo "This works fine, because Copy operations are not restricted for Directory buckets.\n";
pressEnter();
$objectKey = "basic-text-object";
$s3RegularService->putObject($normalBucketName, $objectKey, $args = ['Body' => "Look Ma, I'm a bucket!"]);
$this->resources['objectKey'] = $objectKey;
// Create a session to access the directory bucket. The SDK Client will automatically refresh this as needed.
$s3ExpressService->createSession($directoryBucketName);
$s3ExpressService->copyObject($directoryBucketName, $objectKey, "$normalBucketName/$objectKey");
echo "It worked! It's important to remember the user permissions when interacting with Directory buckets.\n";
echo "Instead of validating permissions on every call as normal buckets do, Directory buckets utilize the user credentials and session token to validate.\n";
echo "This allows for much faster connection speeds on every call. For single calls, this is low, but for many concurrent calls, this adds up to a lot of time saved.\n";
pressEnter();
// 6. Demonstrate performance difference.
echo "\n";
echo "6. Demonstrate performance difference.\n";
$downloads = 1000;
echo "Now, let's do a performance test. We'll download the same object from each bucket $downloads times and compare the total time needed. Note: the performance difference will be much more pronounced if this example is run in an EC2 instance in the same AZ as the bucket.\n";
$downloadChoice = testable_readline("If you would like to download each object $downloads times, press enter. Otherwise, enter a custom amount and press enter.");
if($downloadChoice && is_numeric($downloadChoice) && $downloadChoice < 1000000){ // A million is enough. I promise.
$downloads = $downloadChoice;
}
// Download the object $downloads times from each bucket and time it to demonstrate the speed difference.
$directoryStartTime = hrtime(true);
for($i = 0; $i < $downloads; ++$i){
$s3ExpressService->getObject($directoryBucketName, $objectKey);
}
$directoryEndTime = hrtime(true);
$directoryTimeDiff = $directoryEndTime - $directoryStartTime;
$normalStartTime = hrtime(true);
for($i = 0; $i < $downloads; ++$i){
$s3RegularService->getObject($normalBucketName, $objectKey);
}
$normalEndTime = hrtime(true);
$normalTimeDiff = $normalEndTime - $normalStartTime;
echo "The directory bucket took $directoryTimeDiff nanoseconds, while the normal bucket took $normalTimeDiff.\n";
echo "That's a difference of " . ($normalTimeDiff - $directoryTimeDiff) . " nanoseconds, or " . (($normalTimeDiff - $directoryTimeDiff)/1000000000) . " seconds.\n";
pressEnter();
// 7. Populate the buckets to show the lexicographical difference.
echo "\n";
echo "7. Populate the buckets to show the lexicographical difference.\n";
echo "Now let's explore how Directory buckets store objects in a different manner to regular buckets.\n";
echo "The key is in the name \"Directory!\"\n";
echo "Where regular buckets store their key/value pairs in a flat manner, Directory buckets use actual directories/folders.\n";
echo "This allows for more rapid indexing, traversing, and therefore retrieval times!\n";
echo "The more segmented your bucket is, with lots of directories, sub-directories, and objects, the more efficient it becomes.\n";
echo "This structural difference also causes ListObjects to behave differently, which can cause unexpected results.\n";
echo "Let's add a few more objects with layered directories as see how the output of ListObjects changes.\n";
pressEnter();
// Populate a few more files in each bucket so that we can use ListObjects and show the difference.
$otherObject = "other/$objectKey";
$altObject = "alt/$objectKey";
$otherAltObject = "other/alt/$objectKey";
$s3ExpressService->putObject($directoryBucketName, $otherObject);
$s3RegularService->putObject($normalBucketName, $otherObject);
$this->resources['otherObject'] = $otherObject;
$s3ExpressService->putObject($directoryBucketName, $altObject);
$s3RegularService->putObject($normalBucketName, $altObject);
$this->resources['altObject'] = $altObject;
$s3ExpressService->putObject($directoryBucketName, $otherAltObject);
$s3RegularService->putObject($normalBucketName, $otherAltObject);
$this->resources['otherAltObject'] = $otherAltObject;
$listDirectoryBucket = $s3ExpressService->listObjects($directoryBucketName);
$listNormalBucket = $s3RegularService->listObjects($normalBucketName);
// Directory bucket content
echo "Directory bucket content\n";
foreach($listDirectoryBucket['Contents'] as $result){
echo $result['Key'] . "\n";
}
// Normal bucket content
echo "\nNormal bucket content\n";
foreach($listNormalBucket['Contents'] as $result){
echo $result['Key'] . "\n";
}
echo "Notice how the normal bucket lists objects in lexicographical order, while the directory bucket does not. This is because the normal bucket considers the whole \"key\" to be the object identifies, while the directory bucket actually creates directories and uses the object \"key\" as a path to the object.\n";
pressEnter();
echo "\n";
echo "That's it for our tour of the basic operations for S3 Express One Zone.\n";
$cleanUp = testable_readline("Would you like to delete all the resources created during this demo? Enter Y/y to delete all the resources.");
if($cleanUp){
$this->cleanUp();
}
namespace S3;
use Aws\CommandInterface;
use Aws\Exception\AwsException;
use Aws\Result;
use Aws\S3\Exception\S3Exception;
use Aws\S3\S3Client;
use AwsUtilities\AWSServiceClass;
use DateTimeInterface;
class S3Service extends AWSServiceClass
{
protected S3Client $client;
protected bool $verbose;
public function __construct(S3Client $client = null, $verbose = false)
{
if ($client) {
$this->client = $client;
} else {
$this->client = new S3Client([
'version' => 'latest',
'region' => 'us-west-2',
]);
}
$this->verbose = $verbose;
}
public function setVerbose($verbose)
{
$this->verbose = $verbose;
}
public function isVerbose(): bool
{
return $this->verbose;
}
public function getClient(): S3Client
{
return $this->client;
}
public function setClient(S3Client $client)
{
$this->client = $client;
}
public function emptyAndDeleteBucket($bucketName, array $args = [])
{
try {
$objects = $this->listAllObjects($bucketName, $args);
$this->deleteObjects($bucketName, $objects, $args);
if ($this->verbose) {
echo "Deleted all objects and folders from $bucketName.\n";
}
$this->deleteBucket($bucketName, $args);
} catch (AwsException $exception) {
if ($this->verbose) {
echo "Failed to delete $bucketName with error: {$exception->getMessage()}\n";
echo "\nPlease fix error with bucket deletion before continuing.\n";
}
throw $exception;
}
}
public function createBucket(string $bucketName, array $args = [])
{
$parameters = array_merge(['Bucket' => $bucketName], $args);
try {
$this->client->createBucket($parameters);
if ($this->verbose) {
echo "Created the bucket named: $bucketName.\n";
}
} catch (AwsException $exception) {
if ($this->verbose) {
echo "Failed to create $bucketName with error: {$exception->getMessage()}\n";
echo "Please fix error with bucket creation before continuing.";
}
throw $exception;
}
}
public function putObject(string $bucketName, string $key, array $args = [])
{
$parameters = array_merge(['Bucket' => $bucketName, 'Key' => $key], $args);
try {
$this->client->putObject($parameters);
if ($this->verbose) {
echo "Uploaded the object named: $key to the bucket named: $bucketName.\n";
}
} catch (AwsException $exception) {
if ($this->verbose) {
echo "Failed to create $key in $bucketName with error: {$exception->getMessage()}\n";
echo "Please fix error with object uploading before continuing.";
}
throw $exception;
}
}
public function getObject(string $bucketName, string $key, array $args = []): Result
{
$parameters = array_merge(['Bucket' => $bucketName, 'Key' => $key], $args);
try {
$object = $this->client->getObject($parameters);
if ($this->verbose) {
echo "Downloaded the object named: $key to the bucket named: $bucketName.\n";
}
} catch (AwsException $exception) {
if ($this->verbose) {
echo "Failed to download $key from $bucketName with error: {$exception->getMessage()}\n";
echo "Please fix error with object downloading before continuing.";
}
throw $exception;
}
return $object;
}
public function copyObject($bucketName, $key, $copySource, array $args = [])
{
$parameters = array_merge(['Bucket' => $bucketName, 'Key' => $key, "CopySource" => $copySource], $args);
try {
$this->client->copyObject($parameters);
if ($this->verbose) {
echo "Copied the object from: $copySource in $bucketName to: $key.\n";
}
} catch (AwsException $exception) {
if ($this->verbose) {
echo "Failed to copy $copySource in $bucketName with error: {$exception->getMessage()}\n";
echo "Please fix error with object copying before continuing.";
}
throw $exception;
}
}
public function listObjects(string $bucketName, $start = 0, $max = 1000, array $args = [])
{
$parameters = array_merge(['Bucket' => $bucketName, 'Marker' => $start, "MaxKeys" => $max], $args);
try {
$objects = $this->client->listObjectsV2($parameters);
if ($this->verbose) {
echo "Retrieved the list of objects from: $bucketName.\n";
}
} catch (AwsException $exception) {
if ($this->verbose) {
echo "Failed to retrieve the objects from $bucketName with error: {$exception->getMessage()}\n";
echo "Please fix error with list objects before continuing.";
}
throw $exception;
}
return $objects;
}
public function listAllObjects($bucketName, array $args = [])
{
$parameters = array_merge(['Bucket' => $bucketName], $args);
$contents = [];
$paginator = $this->client->getPaginator("ListObjectsV2", $parameters);
foreach ($paginator as $result) {
if($result['KeyCount'] == 0){
break;
}
foreach ($result['Contents'] as $object) {
$contents[] = $object;
}
}
return $contents;
}
public function deleteObjects(string $bucketName, array $objects, array $args = [])
{
$listOfObjects = array_map(
function ($object) {
return ['Key' => $object];
},
array_column($objects, 'Key')
);
if(!$listOfObjects){
return;
}
$parameters = array_merge(['Bucket' => $bucketName, 'Delete' => ['Objects' => $listOfObjects]], $args);
try {
$this->client->deleteObjects($parameters);
if ($this->verbose) {
echo "Deleted the list of objects from: $bucketName.\n";
}
} catch (AwsException $exception) {
if ($this->verbose) {
echo "Failed to delete the list of objects from $bucketName with error: {$exception->getMessage()}\n";
echo "Please fix error with object deletion before continuing.";
}
throw $exception;
}
}
public function deleteBucket(string $bucketName, array $args = [])
{
$parameters = array_merge(['Bucket' => $bucketName], $args);
try {
$this->client->deleteBucket($parameters);
if ($this->verbose) {
echo "Deleted the bucket named: $bucketName.\n";
}
} catch (AwsException $exception) {
if ($this->verbose) {
echo "Failed to delete $bucketName with error: {$exception->getMessage()}\n";
echo "Please fix error with bucket deletion before continuing.";
}
throw $exception;
}
}
public function deleteObject(string $bucketName, string $fileName, array $args = [])
{
$parameters = array_merge(['Bucket' => $bucketName, 'Key' => $fileName], $args);
try {
$this->client->deleteObject($parameters);
if ($this->verbose) {
echo "Deleted the object named: $fileName from $bucketName.\n";
}
} catch (AwsException $exception) {
if ($this->verbose) {
echo "Failed to delete $fileName from $bucketName with error: {$exception->getMessage()}\n";
echo "Please fix error with object deletion before continuing.";
}
throw $exception;
}
}
public function listBuckets(array $args = [])
{
try {
$buckets = $this->client->listBuckets($args);
if ($this->verbose) {
echo "Retrieved all " . count($buckets) . "\n";
}
} catch (AwsException $exception) {
if ($this->verbose) {
echo "Failed to retrieve bucket list with error: {$exception->getMessage()}\n";
echo "Please fix error with bucket lists before continuing.";
}
throw $exception;
}
return $buckets;
}
public function preSignedUrl(CommandInterface $command, DateTimeInterface|int|string $expires, array $options = [])
{
$request = $this->client->createPresignedRequest($command, $expires, $options);
try {
$presignedUrl = (string)$request->getUri();
} catch (AwsException $exception) {
if ($this->verbose) {
echo "Failed to create a presigned url: {$exception->getMessage()}\n";
echo "Please fix error with presigned urls before continuing.";
}
throw $exception;
}
return $presignedUrl;
}
public function createSession(string $bucketName)
{
try{
$result = $this->client->createSession([
'Bucket' => $bucketName,
]);
return $result;
}catch(S3Exception $caught){
if($caught->getAwsErrorType() == "NoSuchBucket"){
echo "The specified bucket does not exist.";
}
throw $caught;
}
}
}
```
+ 有关 API 详细信息，请参阅《适用于 PHP 的 AWS SDK API Reference》**中的以下主题。
+ [CopyObject](https://docs.aws.amazon.com/goto/SdkForPHPV3/s3-2006-03-01/CopyObject)
+ [CreateBucket](https://docs.aws.amazon.com/goto/SdkForPHPV3/s3-2006-03-01/CreateBucket)
+ [DeleteBucket](https://docs.aws.amazon.com/goto/SdkForPHPV3/s3-2006-03-01/DeleteBucket)
+ [DeleteObject](https://docs.aws.amazon.com/goto/SdkForPHPV3/s3-2006-03-01/DeleteObject)
+ [GetObject](https://docs.aws.amazon.com/goto/SdkForPHPV3/s3-2006-03-01/GetObject)
+ [ListObjects](https://docs.aws.amazon.com/goto/SdkForPHPV3/s3-2006-03-01/ListObjects)
+ [PutObject](https://docs.aws.amazon.com/goto/SdkForPHPV3/s3-2006-03-01/PutObject)
------
#### [ Python ]
**适用于 Python 的 SDK（Boto3）**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3-directory-buckets/#code-examples)中查找完整示例，了解如何进行设置和运行。
运行一个用于演示 Amazon S3 目录存储桶和 S3 Express One Zone 的基础知识的场景。
```
class S3ExpressScenario:
"""Runs an interactive scenario that shows how to get started with S3 Express."""
def __init__(
self,
cloud_formation_resource: ServiceResource,
ec2_client: client,
iam_client: client,
):
self.cloud_formation_resource = cloud_formation_resource
self.ec2_client = ec2_client
self.iam_client = iam_client
self.region = ec2_client.meta.region_name
self.stack = None
self.vpc_id = None
self.vpc_endpoint_id = None
self.regular_bucket_name = None
self.directory_bucket_name = None
self.s3_express_wrapper = None
self.s3_regular_wrapper = None
def s3_express_scenario(self):
"""
Runs the scenario.
"""
print("")
print_dashes()
print("Welcome to the Amazon S3 Express Basics demo using Python (Boto 3)!")
print_dashes()
print(
"""
Let's get started! First, please note that S3 Express One Zone works best when working within the AWS infrastructure,
specifically when working in the same Availability Zone. To see the best results in this example and when you implement
Directory buckets into your infrastructure, it is best to put your compute resources in the same AZ as your Directory
bucket.
"""
)
press_enter_to_continue()
# Create an optional VPC and create 2 IAM users.
express_user_name, regular_user_name = self.create_vpc_and_users()
# Set up two S3 clients, one regular and one express, and two buckets, one regular and one express.
self.setup_clients_and_buckets(express_user_name, regular_user_name)
# Create an S3 session for the express S3 client and add objects to the buckets.
bucket_object = self.create_session_and_add_objects()
# Demonstrate performance differences between regular and express buckets.
self.demonstrate_performance(bucket_object)
# Populate the buckets to show the lexicographical difference between regular and express buckets.
self.show_lexicographical_differences(bucket_object)
print("")
print("That's it for our tour of the basic operations for S3 Express One Zone.")
if q.ask(
"Would you like to delete all the resources created during this demo (y/n)? ",
q.is_yesno,
):
self.cleanup()
def create_vpc_and_users(self) -> None:
"""
Optionally create a VPC.
Create two IAM users, one with S3 Express One Zone permissions and one without.
"""
# Configure a gateway VPC endpoint. This is the recommended method to allow S3 Express One Zone traffic without
# the need to pass through an internet gateway or NAT device.
print(
"""
1. First, we'll set up a new VPC and VPC Endpoint if this program is running in an EC2 instance in the same AZ as your
Directory buckets will be. Are you running this in an EC2 instance located in the same AZ as your intended Directory buckets?
"""
)
if q.ask("Do you want to setup a VPC Endpoint? (y/n) ", q.is_yesno):
print(
"Great! Let's set up a VPC, retrieve the Route Table from it, and create a VPC Endpoint to connect the S3 Client to."
)
self.setup_vpc()
press_enter_to_continue()
else:
print("Skipping the VPC setup. Don't forget to use this in production!")
print(
"""
2. Policies, users, and roles with CDK.
Now, we'll set up some policies, roles, and a user. This user will only have permissions to do S3 Express One Zone actions.
"""
)
press_enter_to_continue()
stack_name = f"cfn-stack-s3-express-basics--{uuid.uuid4()}"
template_as_string = S3ExpressScenario.get_template_as_string()
self.stack = self.deploy_cloudformation_stack(stack_name, template_as_string)
regular_user_name = None
express_user_name = None
outputs = self.stack.outputs
for output in outputs:
if output.get("OutputKey") == "RegularUser":
regular_user_name = output.get("OutputValue")
elif output.get("OutputKey") == "ExpressUser":
express_user_name = output.get("OutputValue")
if not regular_user_name or not express_user_name:
error_string = f"""
Failed to retrieve required outputs from CloudFormation stack.
'regular_user_name'={regular_user_name}, 'express_user_name'={express_user_name}
"""
logger.error(error_string)
raise ValueError(error_string)
return express_user_name, regular_user_name
def setup_clients_and_buckets(
self, express_user_name: str, regular_user_name: str
) -> None:
"""
Set up two S3 clients, one regular and one express, and two buckets, one regular and one express.
:param express_user_name: The name of the user with S3 Express permissions.
:param regular_user_name: The name of the user with regular S3 permissions.
"""
regular_credentials = self.create_access_key(regular_user_name)
express_credentials = self.create_access_key(express_user_name)
# 3. Create an additional client using the credentials with S3 Express permissions.
print(
"""
3. Create an additional client using the credentials with S3 Express permissions. This client is created with the
credentials associated with the user account with the S3 Express policy attached, so it can perform S3 Express operations.
"""
)
press_enter_to_continue()
s3_regular_client = self.create_s3__client_with_access_key_credentials(
regular_credentials
)
self.s3_regular_wrapper = S3ExpressWrapper(s3_regular_client)
s3_express_client = self.create_s3__client_with_access_key_credentials(
express_credentials
)
self.s3_express_wrapper = S3ExpressWrapper(s3_express_client)
print(
"""
All the roles and policies were created and attached to the user. Then a new S3 Client were created using
that user's credentials. We can now use this client to make calls to S3 Express operations. Keeping permissions in mind
(and adhering to least-privilege) is crucial to S3 Express.
"""
)
press_enter_to_continue()
# 4. Create two buckets.
print(
"""
3. Create two buckets.
Now we will create a Directory bucket which is the linchpin of the S3 Express One Zone service. Directory buckets
behave in different ways from regular S3 buckets which we will explore here. We'll also create a normal bucket, put
an object into the normal bucket, and copy it over to the Directory bucket.
"""
)
# Create a directory bucket. These are different from normal S3 buckets in subtle ways.
bucket_prefix = q.ask(
"Enter a bucket name prefix that will be used for both buckets: ",
q.re_match(r"[a-z0-9](?:[a-z0-9-\.]*)[a-z0-9]$"),
)
# Some availability zones are not supported for Directory buckets. We'll choose one that is supported.
print(
"Now, let's choose an availability zone for the Directory bucket. We'll choose one that is supported."
)
while True:
availability_zone = self.select_availability_zone_id(self.region)
# Construct the parts of a directory bucket name that is made unique with a UUID string.
directory_bucket_suffix = f"--{availability_zone['ZoneId']}--x-s3"
max_uuid_length = 63 - len(bucket_prefix) - len(directory_bucket_suffix) - 1
bucket_uuid = str(uuid.uuid4()).replace("-", "")[:max_uuid_length]
directory_bucket_name = (
f"{bucket_prefix}-{bucket_uuid}{directory_bucket_suffix}"
)
regular_bucket_name = f"{bucket_prefix}-regular-{bucket_uuid}"
configuration = {
"Bucket": {
"Type": "Directory",
"DataRedundancy": "SingleAvailabilityZone",
},
"Location": {
"Name": availability_zone["ZoneId"],
"Type": "AvailabilityZone",
},
}
press_enter_to_continue()
print(
"Now, let's create the actual Directory bucket, as well as a regular bucket."
)
press_enter_to_continue()
try:
self.s3_express_wrapper.create_bucket(
directory_bucket_name, configuration
)
break
except ClientError as client_error:
if client_error.response["Error"]["Code"] == "InvalidBucketName":
print(
f"Bucket '{directory_bucket_name}' is invalid. This may be because of selected availability zone."
)
if q.ask(
"Would you like to select a different availability zone? ",
q.is_yesno,
):
continue
else:
raise
else:
raise
print(f"Created directory bucket, '{directory_bucket_name}'")
self.directory_bucket_name = directory_bucket_name
self.s3_regular_wrapper.create_bucket(regular_bucket_name)
print(f"Created regular bucket, '{regular_bucket_name}'")
self.regular_bucket_name = regular_bucket_name
print("Great! Both buckets were created.")
press_enter_to_continue()
def create_session_and_add_objects(self) -> None:
"""
Create a session for the express S3 client and add objects to the buckets.
"""
print(
"""
5. Create an object and copy it over.
We'll create a basic object consisting of some text and upload it to the normal bucket. Next we'll copy the object
into the Directory bucket using the regular client. This works fine because copy operations are not restricted for
Directory buckets.
"""
)
press_enter_to_continue()
bucket_object = "basic-text-object"
self.s3_regular_wrapper.put_object(
self.regular_bucket_name, bucket_object, "Look Ma, I'm a bucket!"
)
self.s3_express_wrapper.create_session(self.directory_bucket_name)
self.s3_express_wrapper.copy_object(
self.regular_bucket_name,
bucket_object,
self.directory_bucket_name,
bucket_object,
)
print(
"""
It worked! It's important to remember the user permissions when interacting with Directory buckets. Instead of validating
permissions on every call as normal buckets do, Directory buckets utilize the user credentials and session token to validate.
This allows for much faster connection speeds on every call. For single calls, this is low, but for many concurrent calls
this adds up to a lot of time saved.
"""
)
press_enter_to_continue()
return bucket_object
def demonstrate_performance(self, bucket_object: str) -> None:
"""
Demonstrate performance differences between regular and Directory buckets.
:param bucket_object: The name of the object to download from each bucket.
"""
print("")
print("6. Demonstrate performance difference.")
print(
"""
Now, let's do a performance test. We'll download the same object from each bucket 'downloads' times
and compare the total time needed. Note: the performance difference will be much more pronounced if this
example is run in an EC2 instance in the same Availability Zone as the bucket.
"""
)
downloads = 1000
print(
f"The number of downloads of the same object for this example is set at {downloads}."
)
if q.ask("Would you like to download a different number? (y/n) ", q.is_yesno):
max_downloads = 1000000
downloads = q.ask(
f"Enter a number between 1 and {max_downloads} for the number of downloads: ",
q.is_int,
q.in_range(1, max_downloads),
)
# Download the object 'downloads' times from each bucket and time it to demonstrate the speed difference.
print("Downloading from the Directory bucket.")
directory_time_start = time.time_ns()
for index in range(downloads):
if index % 10 == 0:
print(f"Download {index} of {downloads}")
self.s3_express_wrapper.get_object(
self.directory_bucket_name, bucket_object
)
directory_time_difference = time.time_ns() - directory_time_start
print("Downloading from the normal bucket.")
normal_time_start = time.time_ns()
for index in range(downloads):
if index % 10 == 0:
print(f"Download {index} of {downloads}")
self.s3_regular_wrapper.get_object(self.regular_bucket_name, bucket_object)
normal_time_difference = time.time_ns() - normal_time_start
print(
f"The directory bucket took {directory_time_difference} nanoseconds, while the normal bucket took {normal_time_difference}."
)
difference = normal_time_difference - directory_time_difference
print(f"That's a difference of {difference} nanoseconds, or")
print(f"{(difference) / 1000000000} seconds.")
if difference < 0:
print(
"The directory buckets were slower. This can happen if you are not running on the cloud within a vpc."
)
press_enter_to_continue()
def show_lexicographical_differences(self, bucket_object: str) -> None:
"""
Show the lexicographical difference between Directory buckets and regular buckets.
This is done by creating a few objects in each bucket and listing them to show the difference.
:param bucket_object: The object to use for the listing operations.
"""
print(
"""
7. Populate the buckets to show the lexicographical difference.
Now let's explore how Directory buckets store objects in a different manner to regular buckets. The key is in the name
"Directory". Where regular buckets store their key/value pairs in a flat manner, Directory buckets use actual
directories/folders. This allows for more rapid indexing, traversing, and therefore retrieval times! The more segmented
your bucket is, with lots of directories, sub-directories, and objects, the more efficient it becomes. This structural
difference also causes ListObjects to behave differently, which can cause unexpected results. Let's add a few more
objects with layered directories to see how the output of ListObjects changes.
"""
)
press_enter_to_continue()
# Populate a few more files in each bucket so that we can use ListObjects and show the difference.
other_object = f"other/{bucket_object}"
alt_object = f"alt/{bucket_object}"
other_alt_object = f"other/alt/{bucket_object}"
self.s3_regular_wrapper.put_object(self.regular_bucket_name, other_object, "")
self.s3_express_wrapper.put_object(self.directory_bucket_name, other_object, "")
self.s3_regular_wrapper.put_object(self.regular_bucket_name, alt_object, "")
self.s3_express_wrapper.put_object(self.directory_bucket_name, alt_object, "")
self.s3_regular_wrapper.put_object(
self.regular_bucket_name, other_alt_object, ""
)
self.s3_express_wrapper.put_object(
self.directory_bucket_name, other_alt_object, ""
)
directory_bucket_objects = self.s3_express_wrapper.list_objects(
self.directory_bucket_name
)
regular_bucket_objects = self.s3_regular_wrapper.list_objects(
self.regular_bucket_name
)
print("Directory bucket content")
for bucket_object in directory_bucket_objects:
print(f" {bucket_object['Key']}")
print("Normal bucket content")
for bucket_object in regular_bucket_objects:
print(f" {bucket_object['Key']}")
print(
"""
Notice how the normal bucket lists objects in lexicographical order, while the directory bucket does not. This is
because the normal bucket considers the whole "key" to be the object identifier, while the directory bucket actually
creates directories and uses the object "key" as a path to the object.
"""
)
press_enter_to_continue()
def cleanup(self) -> None:
"""
Delete resources created by this scenario.
"""
if self.directory_bucket_name is not None:
self.s3_express_wrapper.delete_bucket_and_objects(
self.directory_bucket_name
)
print(f"Deleted directory bucket, '{self.directory_bucket_name}'")
self.directory_bucket_name = None
if self.regular_bucket_name is not None:
self.s3_regular_wrapper.delete_bucket_and_objects(self.regular_bucket_name)
print(f"Deleted regular bucket, '{self.regular_bucket_name}'")
self.regular_bucket_name = None
if self.stack is not None:
self.destroy_cloudformation_stack(self.stack)
self.stack = None
self.tear_done_vpc()
def create_access_key(self, user_name: str) -> dict[str, any]:
"""
Creates an access key for the user.
:param user_name: The name of the user.
:return: The access key for the user.
"""
try:
access_key = self.iam_client.create_access_key(UserName=user_name)
return access_key["AccessKey"]
except ClientError as client_error:
logging.error(
"Couldn't create the access key. Here's why: %s",
client_error.response["Error"]["Message"],
)
raise
def create_s3__client_with_access_key_credentials(
self, access_key: dict[str, any]
) -> client:
"""
Creates an S3 client with access key credentials.
:param access_key: The access key for the user.
:return: The S3 Express One Zone client.
"""
try:
s3_express_client = boto3.client(
"s3",
aws_access_key_id=access_key["AccessKeyId"],
aws_secret_access_key=access_key["SecretAccessKey"],
region_name=self.region,
)
return s3_express_client
except ClientError as client_error:
logging.error(
"Couldn't create the S3 Express One Zone client. Here's why: %s",
client_error.response["Error"]["Message"],
)
raise
def select_availability_zone_id(self, region: str) -> dict[str, any]:
"""
Selects an availability zone.
:param region: The region to select the availability zone from.
:return: The availability zone dictionary.
"""
try:
response = self.ec2_client.describe_availability_zones(
Filters=[{"Name": "region-name", "Values": [region]}]
)
availability_zones = response["AvailabilityZones"]
zone_names = [zone["ZoneName"] for zone in availability_zones]
index = q.choose("Select an availability zone: ", zone_names)
return availability_zones[index]
except ClientError as client_error:
logging.error(
"Couldn't describe availability zones. Here's why: %s",
client_error.response["Error"]["Message"],
)
raise
def deploy_cloudformation_stack(
self, stack_name: str, cfn_template: str
) -> ServiceResource:
"""
Deploys prerequisite resources used by the scenario. The resources are
defined in the associated `cfn_template.yaml` AWS CloudFormation script and are deployed
as a CloudFormation stack, so they can be easily managed and destroyed.
:param stack_name: The name of the CloudFormation stack.
:param cfn_template: The CloudFormation template as a string.
:return: The CloudFormation stack resource.
"""
print(f"Deploying CloudFormation stack: {stack_name}.")
stack = self.cloud_formation_resource.create_stack(
StackName=stack_name,
TemplateBody=cfn_template,
Capabilities=["CAPABILITY_NAMED_IAM"],
)
print(f"CloudFormation stack creation started: {stack_name}")
print("Waiting for CloudFormation stack creation to complete...")
waiter = self.cloud_formation_resource.meta.client.get_waiter(
"stack_create_complete"
)
waiter.wait(StackName=stack.name)
stack.load()
print("CloudFormation stack creation complete.")
return stack
def destroy_cloudformation_stack(self, stack: ServiceResource) -> None:
"""
Destroys the resources managed by the CloudFormation stack, and the CloudFormation
stack itself.
:param stack: The CloudFormation stack that manages the example resources.
"""
try:
print(
f"CloudFormation stack '{stack.name}' is being deleted. This may take a few minutes."
)
stack.delete()
waiter = self.cloud_formation_resource.meta.client.get_waiter(
"stack_delete_complete"
)
waiter.wait(StackName=stack.name)
print(f"CloudFormation stack '{stack.name}' has been deleted.")
except ClientError as client_error:
logging.error(
"Couldn't delete the CloudFormation stack. Here's why: %s",
client_error.response["Error"]["Message"],
)
@staticmethod
def get_template_as_string() -> str:
"""
Returns a string containing this scenario's CloudFormation template.
"""
script_directory = os.path.dirname(os.path.abspath(__file__))
template_file_path = os.path.join(script_directory, "s3_express_template.yaml")
file = open(template_file_path, "r")
return file.read()
def setup_vpc(self):
cidr = "10.0.0.0/16"
try:
response = self.ec2_client.create_vpc(CidrBlock=cidr)
self.vpc_id = response["Vpc"]["VpcId"]
waiter = self.ec2_client.get_waiter("vpc_available")
waiter.wait(VpcIds=[self.vpc_id])
print(f"Created vpc {self.vpc_id}")
except ClientError as client_error:
logging.error(
"Couldn't create the vpc. Here's why: %s",
client_error.response["Error"]["Message"],
)
raise
try:
response = self.ec2_client.describe_route_tables(
Filters=[{"Name": "vpc-id", "Values": [self.vpc_id]}]
)
route_table_id = response["RouteTables"][0]["RouteTableId"]
service_name = f"com.amazonaws.{self.ec2_client.meta.region_name}.s3express"
response = self.ec2_client.create_vpc_endpoint(
VpcId=self.vpc_id,
RouteTableIds=[route_table_id],
ServiceName=service_name,
)
self.vpc_endpoint_id = response["VpcEndpoint"]["VpcEndpointId"]
print(f"Created vpc endpoint {self.vpc_endpoint_id}")
except ClientError as client_error:
logging.error(
"Couldn't create the vpc endpoint. Here's why: %s",
client_error.response["Error"]["Message"],
)
raise
def tear_done_vpc(self) -> None:
if self.vpc_endpoint_id is not None:
try:
self.ec2_client.delete_vpc_endpoints(
VpcEndpointIds=[self.vpc_endpoint_id]
)
print(f"Deleted vpc endpoint {self.vpc_endpoint_id}.")
self.vpc_endpoint_id = None
except ClientError as client_error:
logging.error(
"Couldn't delete the vpc endpoint %s. Here's why: %s",
self.vpc_endpoint_id,
client_error.response["Error"]["Message"],
)
if self.vpc_id is not None:
try:
self.ec2_client.delete_vpc(VpcId=self.vpc_id)
print(f"Deleted vpc {self.vpc_id}")
self.vpc_id = None
except ClientError as client_error:
logging.error(
"Couldn't delete the vpc %s. Here's why: %s",
self.vpc_id,
client_error.response["Error"]["Message"],
)
```
Amazon S3 Express SDK 函数的包装器类。
```
class S3ExpressWrapper:
"""Encapsulates Amazon S3 Express One Zone actions using the client interface."""
def __init__(self, s3_client: Any) -> None:
"""
Initializes the S3ExpressWrapper with an S3 client.
:param s3_client: A Boto3 Amazon S3 client. This client provides low-level
access to AWS S3 services.
"""
self.s3_client = s3_client
@classmethod
def from_client(cls) -> "S3ExpressWrapper":
"""
Creates an S3ExpressWrapper instance with a default s3 client.
:return: An instance of S3ExpressWrapper initialized with the default S3 client.
"""
s3_client = boto3.client("s3")
return cls(s3_client)
def create_bucket(
self, bucket_name: str, bucket_configuration: dict[str, any] = None
) -> None:
"""
Creates a bucket.
:param bucket_name: The name of the bucket.
:param bucket_configuration: The optional configuration for the bucket.
"""
try:
params = {"Bucket": bucket_name}
if bucket_configuration:
params["CreateBucketConfiguration"] = bucket_configuration
self.s3_client.create_bucket(**params)
except ClientError as client_error:
# Do not log InvalidBucketName error because it is logged elsewhere.
if client_error.response["Error"]["Code"] != "InvalidBucketName":
logging.error(
"Couldn't create the bucket %s. Here's why: %s",
bucket_name,
client_error.response["Error"]["Message"],
)
raise
def delete_bucket_and_objects(self, bucket_name: str) -> None:
"""
Deletes a bucket and its objects.
:param bucket_name: The name of the bucket.
"""
try:
# Delete the objects in the bucket first. This is required for a bucket to be deleted.
paginator = self.s3_client.get_paginator("list_objects_v2")
page_iterator = paginator.paginate(Bucket=bucket_name)
for page in page_iterator:
if "Contents" in page:
delete_keys = {
"Objects": [{"Key": obj["Key"]} for obj in page["Contents"]]
}
response = self.s3_client.delete_objects(
Bucket=bucket_name, Delete=delete_keys
)
if "Errors" in response:
for error in response["Errors"]:
logging.error(
"Couldn't delete object %s. Here's why: %s",
error["Key"],
error["Message"],
)
self.s3_client.delete_bucket(Bucket=bucket_name)
except ClientError as client_error:
logging.error(
"Couldn't delete the bucket %s. Here's why: %s",
bucket_name,
client_error.response["Error"]["Message"],
)
def put_object(self, bucket_name: str, object_key: str, content: str) -> None:
"""
Puts an object into a bucket.
:param bucket_name: The name of the bucket.
:param object_key: The key of the object.
:param content: The content of the object.
"""
try:
self.s3_client.put_object(Body=content, Bucket=bucket_name, Key=object_key)
except ClientError as client_error:
logging.error(
"Couldn't put the object %s into bucket %s. Here's why: %s",
object_key,
bucket_name,
client_error.response["Error"]["Message"],
)
raise
def list_objects(self, bucket: str) -> list[str]:
"""
Lists objects in a bucket.
:param bucket: The name of the bucket.
:return: The list of objects in the bucket.
"""
try:
response = self.s3_client.list_objects_v2(Bucket=bucket)
return response.get("Contents", [])
except ClientError as client_error:
logging.error(
"Couldn't list objects in bucket %s. Here's why: %s",
bucket,
client_error.response["Error"]["Message"],
)
raise
def copy_object(
self,
source_bucket: str,
source_key: str,
destination_bucket: str,
destination_key: str,
) -> None:
"""
Copies an object from one bucket to another.
:param source_bucket: The source bucket.
:param source_key: The source key.
:param destination_bucket: The destination bucket.
:param destination_key: The destination key.
:return: None
"""
try:
self.s3_client.copy_object(
CopySource={"Bucket": source_bucket, "Key": source_key},
Bucket=destination_bucket,
Key=destination_key,
)
except ClientError as client_error:
logging.error(
"Couldn't copy object %s from bucket %s to bucket %s. Here's why: %s",
source_key,
source_bucket,
destination_bucket,
client_error.response["Error"]["Message"],
)
raise
def create_session(self, bucket_name: str) -> None:
"""
Creates an express session.
:param bucket_name: The name of the bucket.
"""
try:
self.s3_client.create_session(Bucket=bucket_name)
except ClientError as client_error:
logging.error(
"Couldn't create the express session for bucket %s. Here's why: %s",
bucket_name,
client_error.response["Error"]["Message"],
)
raise
def get_object(self, bucket_name: str, object_key: str) -> None:
"""
Gets an object from a bucket.
:param bucket_name: The name of the bucket.
:param object_key: The key of the object.
"""
try:
self.s3_client.get_object(Bucket=bucket_name, Key=object_key)
except ClientError as client_error:
logging.error(
"Couldn't get the object %s from bucket %s. Here's why: %s",
object_key,
bucket_name,
client_error.response["Error"]["Message"],
)
raise
```
+ 有关 API 详细信息，请参阅《AWS SDK for Python (Boto3) API Reference》**中的以下主题。
+ [CopyObject](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/CopyObject)
+ [CreateBucket](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/CreateBucket)
+ [DeleteBucket](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/DeleteBucket)
+ [DeleteObject](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/DeleteObject)
+ [GetObject](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/GetObject)
+ [ListObjects](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/ListObjects)
+ [PutObject](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/PutObject)
------
# 使用 S3 目录存储桶执行的操作 AWS SDKs
以下代码示例演示了如何使用执行单个 S3 目录存储桶操作。 AWS SDKs每个示例都包含一个指向的链接 GitHub，您可以在其中找到有关设置和运行代码的说明。
这些代码节选调用了 S3 Directory Buckets API，是必须在上下文中运行的大型程序的代码节选。您可以在[使用 S3 目录存储桶的场景 AWS SDKs](s3-directory-buckets_code_examples_scenarios.md)中结合上下文查看操作。
以下示例仅包括最常用的操作。有关完整列表，请参阅《[Amazon S3 Directory Buckets API Reference](https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html)》。
**Topics**
+ [`AbortMultipartUpload`](s3-directory-buckets_example_s3-directory-buckets_AbortMultipartUpload_section.md)
+ [`CompleteMultipartUpload`](s3-directory-buckets_example_s3-directory-buckets_CompleteMultipartUpload_section.md)
+ [`CopyObject`](s3-directory-buckets_example_s3-directory-buckets_CopyObject_section.md)
+ [`CreateBucket`](s3-directory-buckets_example_s3-directory-buckets_CreateBucket_section.md)
+ [`CreateMultipartUpload`](s3-directory-buckets_example_s3-directory-buckets_CreateMultipartUpload_section.md)
+ [`CreateSession`](s3-directory-buckets_example_s3-directory-buckets_CreateSession_section.md)
+ [`DeleteBucket`](s3-directory-buckets_example_s3-directory-buckets_DeleteBucket_section.md)
+ [`DeleteBucketEncryption`](s3-directory-buckets_example_s3-directory-buckets_DeleteBucketEncryption_section.md)
+ [`DeleteBucketPolicy`](s3-directory-buckets_example_s3-directory-buckets_DeleteBucketPolicy_section.md)
+ [`DeleteObject`](s3-directory-buckets_example_s3-directory-buckets_DeleteObject_section.md)
+ [`DeleteObjects`](s3-directory-buckets_example_s3-directory-buckets_DeleteObjects_section.md)
+ [`GetBucketEncryption`](s3-directory-buckets_example_s3-directory-buckets_GetBucketEncryption_section.md)
+ [`GetBucketPolicy`](s3-directory-buckets_example_s3-directory-buckets_GetBucketPolicy_section.md)
+ [`GetObject`](s3-directory-buckets_example_s3-directory-buckets_GetObject_section.md)
+ [`GetObjectAttributes`](s3-directory-buckets_example_s3-directory-buckets_GetObjectAttributes_section.md)
+ [`HeadBucket`](s3-directory-buckets_example_s3-directory-buckets_HeadBucket_section.md)
+ [`HeadObject`](s3-directory-buckets_example_s3-directory-buckets_HeadObject_section.md)
+ [`ListDirectoryBuckets`](s3-directory-buckets_example_s3-directory-buckets_ListDirectoryBuckets_section.md)
+ [`ListMultipartUploads`](s3-directory-buckets_example_s3-directory-buckets_ListMultipartUploads_section.md)
+ [`ListObjectsV2`](s3-directory-buckets_example_s3-directory-buckets_ListObjectsV2_section.md)
+ [`ListParts`](s3-directory-buckets_example_s3-directory-buckets_ListParts_section.md)
+ [`PutBucketEncryption`](s3-directory-buckets_example_s3-directory-buckets_PutBucketEncryption_section.md)
+ [`PutBucketPolicy`](s3-directory-buckets_example_s3-directory-buckets_PutBucketPolicy_section.md)
+ [`PutObject`](s3-directory-buckets_example_s3-directory-buckets_PutObject_section.md)
+ [`UploadPart`](s3-directory-buckets_example_s3-directory-buckets_UploadPart_section.md)
+ [`UploadPartCopy`](s3-directory-buckets_example_s3-directory-buckets_UploadPartCopy_section.md)
# `AbortMultipartUpload`与 AWS SDK 一起使用
以下代码示例演示了如何使用 `AbortMultipartUpload`。
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket#code-examples)中查找完整示例，了解如何进行设置和运行。
中止目录存储桶中的分段上传。
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.AbortMultipartUploadRequest;
import software.amazon.awssdk.services.s3.model.S3Exception;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucketMultipartUpload;
import static com.example.s3.util.S3DirectoryBucketUtils.createS3Client;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteDirectoryBucket;
/**
* Aborts a specific multipart upload for the specified S3 directory bucket.
*
* @param s3Client The S3 client used to interact with S3
* @param bucketName The name of the directory bucket
* @param objectKey The key (name) of the object to be uploaded
* @param uploadId The upload ID of the multipart upload to abort
* @return True if the multipart upload is successfully aborted, false otherwise
*/
public static boolean abortDirectoryBucketMultipartUpload(S3Client s3Client, String bucketName,
String objectKey, String uploadId) {
logger.info("Aborting multipart upload: {} for bucket: {}", uploadId, bucketName);
try {
// Abort the multipart upload
AbortMultipartUploadRequest abortMultipartUploadRequest = AbortMultipartUploadRequest.builder()
.bucket(bucketName)
.key(objectKey)
.uploadId(uploadId)
.build();
s3Client.abortMultipartUpload(abortMultipartUploadRequest);
logger.info("Aborted multipart upload: {} for object: {}", uploadId, objectKey);
return true;
} catch (S3Exception e) {
logger.error("Failed to abort multipart upload: {} - Error code: {}", e.awsErrorDetails().errorMessage(),
e.awsErrorDetails().errorCode(), e);
return false;
}
}
```
+ 有关 API 的详细信息，请参阅 *AWS SDK for Java 2.x API 参考[AbortMultipartUpload](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/AbortMultipartUpload)*中的。
------
# `CompleteMultipartUpload`与 AWS SDK 一起使用
以下代码示例演示了如何使用 `CompleteMultipartUpload`。
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket#code-examples)中查找完整示例，了解如何进行设置和运行。
完成目录存储桶中的分段上传。
```
import com.example.s3.util.S3DirectoryBucketUtils;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.CompleteMultipartUploadRequest;
import software.amazon.awssdk.services.s3.model.CompleteMultipartUploadResponse;
import software.amazon.awssdk.services.s3.model.CompletedMultipartUpload;
import software.amazon.awssdk.services.s3.model.CompletedPart;
import software.amazon.awssdk.services.s3.model.S3Exception;
import java.io.IOException;
import java.nio.file.Path;
import java.util.List;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucketMultipartUpload;
import static com.example.s3.util.S3DirectoryBucketUtils.createS3Client;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteAllObjectsInDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.getFilePath;
import static com.example.s3.util.S3DirectoryBucketUtils.multipartUploadForDirectoryBucket;
/**
* This method completes the multipart upload request by collating all the
* upload parts.
*
* @param s3Client The S3 client used to interact with S3
* @param bucketName The name of the directory bucket
* @param objectKey The key (name) of the object to be uploaded
* @param uploadId The upload ID used to track the multipart upload
* @param uploadParts The list of completed parts
* @return True if the multipart upload is successfully completed, false
* otherwise
*/
public static boolean completeDirectoryBucketMultipartUpload(S3Client s3Client, String bucketName, String objectKey,
String uploadId, List uploadParts) {
try {
CompletedMultipartUpload completedMultipartUpload = CompletedMultipartUpload.builder()
.parts(uploadParts)
.build();
CompleteMultipartUploadRequest completeMultipartUploadRequest = CompleteMultipartUploadRequest.builder()
.bucket(bucketName)
.key(objectKey)
.uploadId(uploadId)
.multipartUpload(completedMultipartUpload)
.build();
CompleteMultipartUploadResponse response = s3Client.completeMultipartUpload(completeMultipartUploadRequest);
logger.info("Multipart upload completed. ETag: {}", response.eTag());
return true;
} catch (S3Exception e) {
logger.error("Failed to complete multipart upload: {} - Error code: {}", e.awsErrorDetails().errorMessage(),
e.awsErrorDetails().errorCode(), e);
return false;
}
}
```
+ 有关 API 的详细信息，请参阅 *AWS SDK for Java 2.x API 参考[CompleteMultipartUpload](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/CompleteMultipartUpload)*中的。
------
# `CopyObject`与 AWS SDK 一起使用
以下代码示例演示了如何使用 `CopyObject`。
操作示例是大型程序的代码摘录，必须在上下文中运行。在以下代码示例中，您可以查看此操作的上下文：
+ [了解基本功能](s3-directory-buckets_example_s3-directory-buckets_Scenario_ExpressBasics_section.md)
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket#code-examples)中查找完整示例，了解如何进行设置和运行。
将对象从目录存储桶复制到目录存储桶。
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.CopyObjectRequest;
import software.amazon.awssdk.services.s3.model.CopyObjectResponse;
import software.amazon.awssdk.services.s3.model.S3Exception;
import java.nio.file.Path;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.createS3Client;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteAllObjectsInDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.getFilePath;
import static com.example.s3.util.S3DirectoryBucketUtils.putDirectoryBucketObject;
/**
* Copies an object from one S3 general purpose bucket to one S3 directory
* bucket.
*
* @param s3Client The S3 client used to interact with S3
* @param sourceBucket The name of the source bucket
* @param objectKey The key (name) of the object to be copied
* @param targetBucket The name of the target bucket
*/
public static void copyDirectoryBucketObject(S3Client s3Client, String sourceBucket, String objectKey,
String targetBucket) {
logger.info("Copying object: {} from bucket: {} to bucket: {}", objectKey, sourceBucket, targetBucket);
try {
// Create a CopyObjectRequest
CopyObjectRequest copyReq = CopyObjectRequest.builder()
.sourceBucket(sourceBucket)
.sourceKey(objectKey)
.destinationBucket(targetBucket)
.destinationKey(objectKey)
.build();
// Copy the object
CopyObjectResponse copyRes = s3Client.copyObject(copyReq);
logger.info("Successfully copied {} from bucket {} into bucket {}. CopyObjectResponse: {}",
objectKey, sourceBucket, targetBucket, copyRes.copyObjectResult().toString());
} catch (S3Exception e) {
logger.error("Failed to copy object: {} - Error code: {}", e.awsErrorDetails().errorMessage(),
e.awsErrorDetails().errorCode(), e);
throw e;
}
}
```
+ 有关 API 的详细信息，请参阅 *AWS SDK for Java 2.x API 参考[CopyObject](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/CopyObject)*中的。
------
# 与 AWS SDK `CreateBucket` 配合使用
以下代码示例演示了如何使用 `CreateBucket`。
操作示例是大型程序的代码摘录，必须在上下文中运行。在以下代码示例中，您可以查看此操作的上下文：
+ [了解基本功能](s3-directory-buckets_example_s3-directory-buckets_Scenario_ExpressBasics_section.md)
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket#code-examples)中查找完整示例，了解如何进行设置和运行。
创建 S3 目录存储桶。
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.BucketInfo;
import software.amazon.awssdk.services.s3.model.BucketType;
import software.amazon.awssdk.services.s3.model.CreateBucketConfiguration;
import software.amazon.awssdk.services.s3.model.CreateBucketRequest;
import software.amazon.awssdk.services.s3.model.CreateBucketResponse;
import software.amazon.awssdk.services.s3.model.DataRedundancy;
import software.amazon.awssdk.services.s3.model.LocationInfo;
import software.amazon.awssdk.services.s3.model.LocationType;
import software.amazon.awssdk.services.s3.model.S3Exception;
import static com.example.s3.util.S3DirectoryBucketUtils.createS3Client;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteDirectoryBucket;
/**
* Creates a new S3 directory bucket in a specified Zone (For example, a
* specified Availability Zone in this code example).
*
* @param s3Client The S3 client used to create the bucket
* @param bucketName The name of the bucket to be created
* @param zone The region where the bucket will be created
* @throws S3Exception if there's an error creating the bucket
*/
public static void createDirectoryBucket(S3Client s3Client, String bucketName, String zone) throws S3Exception {
logger.info("Creating bucket: {}", bucketName);
CreateBucketConfiguration bucketConfiguration = CreateBucketConfiguration.builder()
.location(LocationInfo.builder()
.type(LocationType.AVAILABILITY_ZONE)
.name(zone).build())
.bucket(BucketInfo.builder()
.type(BucketType.DIRECTORY)
.dataRedundancy(DataRedundancy.SINGLE_AVAILABILITY_ZONE)
.build())
.build();
try {
CreateBucketRequest bucketRequest = CreateBucketRequest.builder()
.bucket(bucketName)
.createBucketConfiguration(bucketConfiguration).build();
CreateBucketResponse response = s3Client.createBucket(bucketRequest);
logger.info("Bucket created successfully with location: {}", response.location());
} catch (S3Exception e) {
logger.error("Error creating bucket: {} - Error code: {}", e.awsErrorDetails().errorMessage(),
e.awsErrorDetails().errorCode(), e);
throw e;
}
}
```
+ 有关 API 的详细信息，请参阅 *AWS SDK for Java 2.x API 参考[CreateBucket](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/CreateBucket)*中的。
------
# 与 AWS SDK `CreateMultipartUpload` 配合使用
以下代码示例演示了如何使用 `CreateMultipartUpload`。
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket#code-examples)中查找完整示例，了解如何进行设置和运行。
在目录存储桶中创建分段上传。
```
import com.example.s3.util.S3DirectoryBucketUtils;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.CreateMultipartUploadRequest;
import software.amazon.awssdk.services.s3.model.CreateMultipartUploadResponse;
import software.amazon.awssdk.services.s3.model.S3Exception;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.createS3Client;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteDirectoryBucket;
/**
* This method creates a multipart upload request that generates a unique upload
* ID used to track
* all the upload parts.
*
* @param s3Client The S3 client used to interact with S3
* @param bucketName The name of the directory bucket
* @param objectKey The key (name) of the object to be uploaded
* @return The upload ID used to track the multipart upload
*/
public static String createDirectoryBucketMultipartUpload(S3Client s3Client, String bucketName, String objectKey) {
logger.info("Creating multipart upload for object: {} in bucket: {}", objectKey, bucketName);
try {
// Create a CreateMultipartUploadRequest
CreateMultipartUploadRequest createMultipartUploadRequest = CreateMultipartUploadRequest.builder()
.bucket(bucketName)
.key(objectKey)
.build();
// Initiate the multipart upload
CreateMultipartUploadResponse response = s3Client.createMultipartUpload(createMultipartUploadRequest);
String uploadId = response.uploadId();
logger.info("Multipart upload initiated. Upload ID: {}", uploadId);
return uploadId;
} catch (S3Exception e) {
logger.error("Failed to create multipart upload: {} - Error code: {}", e.awsErrorDetails().errorMessage(),
e.awsErrorDetails().errorCode(), e);
throw e;
}
}
```
+ 有关 API 的详细信息，请参阅 *AWS SDK for Java 2.x API 参考[CreateMultipartUpload](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/CreateMultipartUpload)*中的。
------
# 与 AWS SDK `CreateSession` 配合使用
以下代码示例演示了如何使用 `CreateSession`。
------
#### [ Python ]
**适用于 Python 的 SDK（Boto3）**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/s3-directory-buckets#code-examples)中查找完整示例，了解如何进行设置和运行。
```
class S3ExpressWrapper:
"""Encapsulates Amazon S3 Express One Zone actions using the client interface."""
def __init__(self, s3_client: Any) -> None:
"""
Initializes the S3ExpressWrapper with an S3 client.
:param s3_client: A Boto3 Amazon S3 client. This client provides low-level
access to AWS S3 services.
"""
self.s3_client = s3_client
@classmethod
def from_client(cls) -> "S3ExpressWrapper":
"""
Creates an S3ExpressWrapper instance with a default s3 client.
:return: An instance of S3ExpressWrapper initialized with the default S3 client.
"""
s3_client = boto3.client("s3")
return cls(s3_client)
def create_session(self, bucket_name: str) -> None:
"""
Creates an express session.
:param bucket_name: The name of the bucket.
"""
try:
self.s3_client.create_session(Bucket=bucket_name)
except ClientError as client_error:
logging.error(
"Couldn't create the express session for bucket %s. Here's why: %s",
bucket_name,
client_error.response["Error"]["Message"],
)
raise
```
+ 有关 API 的详细信息，请参阅适用[CreateSession](https://docs.aws.amazon.com/goto/boto3/s3-2006-03-01/CreateSession)于 *Python 的AWS SDK (Boto3) API 参考*。
------
# 与 AWS SDK `DeleteBucket` 配合使用
以下代码示例演示了如何使用 `DeleteBucket`。
操作示例是大型程序的代码摘录，必须在上下文中运行。在以下代码示例中，您可以查看此操作的上下文：
+ [了解基本功能](s3-directory-buckets_example_s3-directory-buckets_Scenario_ExpressBasics_section.md)
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket#code-examples)中查找完整示例，了解如何进行设置和运行。
删除 S3 目录存储桶。
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.DeleteBucketRequest;
import software.amazon.awssdk.services.s3.model.S3Exception;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.createS3Client;
/**
* Deletes the specified S3 directory bucket.
*
* @param s3Client The S3 client used to interact with S3
* @param bucketName The name of the directory bucket to delete
*/
public static void deleteDirectoryBucket(S3Client s3Client, String bucketName) {
logger.info("Deleting bucket: {}", bucketName);
try {
// Create a DeleteBucketRequest
DeleteBucketRequest deleteBucketRequest = DeleteBucketRequest.builder()
.bucket(bucketName)
.build();
// Delete the bucket
s3Client.deleteBucket(deleteBucketRequest);
logger.info("Successfully deleted bucket: {}", bucketName);
} catch (S3Exception e) {
logger.error("Failed to delete bucket: {} - Error code: {}", e.awsErrorDetails().errorMessage(),
e.awsErrorDetails().errorCode(), e);
throw e;
}
}
```
+ 有关 API 的详细信息，请参阅 *AWS SDK for Java 2.x API 参考[DeleteBucket](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/DeleteBucket)*中的。
------
# 与 AWS SDK `DeleteBucketEncryption` 配合使用
以下代码示例演示了如何使用 `DeleteBucketEncryption`。
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket#code-examples)中查找完整示例，了解如何进行设置和运行。
删除目录存储桶的加密配置。
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.DeleteBucketEncryptionRequest;
import software.amazon.awssdk.services.s3.model.S3Exception;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.createS3Client;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteDirectoryBucket;
/**
* Deletes the encryption configuration from an S3 bucket.
*
* @param s3Client The S3 client used to interact with S3
* @param bucketName The name of the directory bucket
*/
public static void deleteDirectoryBucketEncryption(S3Client s3Client, String bucketName) {
DeleteBucketEncryptionRequest deleteRequest = DeleteBucketEncryptionRequest.builder()
.bucket(bucketName)
.build();
try {
s3Client.deleteBucketEncryption(deleteRequest);
logger.info("Bucket encryption deleted for bucket: {}", bucketName);
} catch (S3Exception e) {
logger.error("Failed to delete bucket encryption: {} - Error code: {}", e.awsErrorDetails().errorMessage(),
e.awsErrorDetails().errorCode(), e);
throw e;
}
}
```
+ 有关 API 的详细信息，请参阅 *AWS SDK for Java 2.x API 参考[DeleteBucketEncryption](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/DeleteBucketEncryption)*中的。
------
# 与 AWS SDK `DeleteBucketPolicy` 配合使用
以下代码示例演示了如何使用 `DeleteBucketPolicy`。
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket#code-examples)中查找完整示例，了解如何进行设置和运行。
删除目录存储桶的存储桶策略。
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.DeleteBucketPolicyRequest;
import software.amazon.awssdk.services.s3.model.S3Exception;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.createS3Client;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.getAwsAccountId;
import static com.example.s3.util.S3DirectoryBucketUtils.putDirectoryBucketPolicy;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
/**
* Deletes the bucket policy for the specified S3 directory bucket.
*
* @param s3Client The S3 client used to interact with S3
* @param bucketName The name of the directory bucket
*/
public static void deleteDirectoryBucketPolicy(S3Client s3Client, String bucketName) {
logger.info("Deleting policy for bucket: {}", bucketName);
try {
// Create a DeleteBucketPolicyRequest
DeleteBucketPolicyRequest deletePolicyReq = DeleteBucketPolicyRequest.builder()
.bucket(bucketName)
.build();
// Delete the bucket policy
s3Client.deleteBucketPolicy(deletePolicyReq);
logger.info("Successfully deleted bucket policy");
} catch (S3Exception e) {
logger.error("Failed to delete bucket policy: {} - Error code: {}", e.awsErrorDetails().errorMessage(),
e.awsErrorDetails().errorCode(), e);
throw e;
}
}
```
+ 有关 API 的详细信息，请参阅 *AWS SDK for Java 2.x API 参考[DeleteBucketPolicy](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/DeleteBucketPolicy)*中的。
------
# 与 AWS SDK `DeleteObject` 配合使用
以下代码示例演示了如何使用 `DeleteObject`。
操作示例是大型程序的代码摘录，必须在上下文中运行。在以下代码示例中，您可以查看此操作的上下文：
+ [了解基本功能](s3-directory-buckets_example_s3-directory-buckets_Scenario_ExpressBasics_section.md)
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket#code-examples)中查找完整示例，了解如何进行设置和运行。
删除目录存储桶中的一个对象。
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.DeleteObjectRequest;
import software.amazon.awssdk.services.s3.model.S3Exception;
import java.nio.file.Path;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.createS3Client;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.getFilePath;
import static com.example.s3.util.S3DirectoryBucketUtils.putDirectoryBucketObject;
/**
* Deletes an object from the specified S3 directory bucket.
*
* @param s3Client The S3 client used to interact with S3
* @param bucketName The name of the directory bucket
* @param objectKey The key (name) of the object to be deleted
*/
public static void deleteDirectoryBucketObject(S3Client s3Client, String bucketName, String objectKey) {
logger.info("Deleting object: {} from bucket: {}", objectKey, bucketName);
try {
// Create a DeleteObjectRequest
DeleteObjectRequest deleteObjectRequest = DeleteObjectRequest.builder()
.bucket(bucketName)
.key(objectKey)
.build();
// Delete the object
s3Client.deleteObject(deleteObjectRequest);
logger.info("Object {} has been deleted", objectKey);
} catch (S3Exception e) {
logger.error("Failed to delete object: {} - Error code: {}", e.awsErrorDetails().errorMessage(),
e.awsErrorDetails().errorCode(), e);
throw e;
}
}
```
+ 有关 API 的详细信息，请参阅 *AWS SDK for Java 2.x API 参考[DeleteObject](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/DeleteObject)*中的。
------
# 与 AWS SDK `DeleteObjects` 配合使用
以下代码示例演示了如何使用 `DeleteObjects`。
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket#code-examples)中查找完整示例，了解如何进行设置和运行。
删除目录存储桶中的多个对象。
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.Delete;
import software.amazon.awssdk.services.s3.model.DeleteObjectsRequest;
import software.amazon.awssdk.services.s3.model.DeleteObjectsResponse;
import software.amazon.awssdk.services.s3.model.ObjectIdentifier;
import software.amazon.awssdk.services.s3.model.S3Exception;
import java.net.URISyntaxException;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.List;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.createS3Client;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.getFilePath;
import static com.example.s3.util.S3DirectoryBucketUtils.putDirectoryBucketObject;
/**
* Deletes multiple objects from the specified S3 directory bucket.
*
* @param s3Client The S3 client used to interact with S3
* @param bucketName The name of the directory bucket
* @param objectKeys The list of keys (names) of the objects to be deleted
*/
public static void deleteDirectoryBucketObjects(S3Client s3Client, String bucketName, List objectKeys) {
logger.info("Deleting objects from bucket: {}", bucketName);
try {
// Create a list of ObjectIdentifier.
List identifiers = objectKeys.stream()
.map(key -> ObjectIdentifier.builder().key(key).build())
.toList();
Delete delete = Delete.builder()
.objects(identifiers)
.build();
DeleteObjectsRequest deleteObjectsRequest = DeleteObjectsRequest.builder()
.bucket(bucketName)
.delete(delete)
.build();
DeleteObjectsResponse deleteObjectsResponse = s3Client.deleteObjects(deleteObjectsRequest);
deleteObjectsResponse.deleted().forEach(deleted -> logger.info("Deleted object: {}", deleted.key()));
} catch (S3Exception e) {
logger.error("Failed to delete objects: {} - Error code: {}", e.awsErrorDetails().errorMessage(),
e.awsErrorDetails().errorCode(), e);
throw e;
}
}
```
+ 有关 API 的详细信息，请参阅 *AWS SDK for Java 2.x API 参考[DeleteObjects](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/DeleteObjects)*中的。
------
# 与 AWS SDK `GetBucketEncryption` 配合使用
以下代码示例演示了如何使用 `GetBucketEncryption`。
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket#code-examples)中查找完整示例，了解如何进行设置和运行。
获取目录存储桶的加密配置。
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.GetBucketEncryptionRequest;
import software.amazon.awssdk.services.s3.model.GetBucketEncryptionResponse;
import software.amazon.awssdk.services.s3.model.S3Exception;
import software.amazon.awssdk.services.s3.model.ServerSideEncryptionRule;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.createS3Client;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteDirectoryBucket;
/**
* Retrieves the encryption configuration for an S3 directory bucket.
*
* @param s3Client The S3 client used to interact with S3
* @param bucketName The name of the directory bucket
* @return The type of server-side encryption applied to the bucket (e.g.,
* AES256, aws:kms)
*/
public static String getDirectoryBucketEncryption(S3Client s3Client, String bucketName) {
try {
// Create a GetBucketEncryptionRequest
GetBucketEncryptionRequest getRequest = GetBucketEncryptionRequest.builder()
.bucket(bucketName)
.build();
// Retrieve the bucket encryption configuration
GetBucketEncryptionResponse response = s3Client.getBucketEncryption(getRequest);
ServerSideEncryptionRule rule = response.serverSideEncryptionConfiguration().rules().get(0);
String encryptionType = rule.applyServerSideEncryptionByDefault().sseAlgorithmAsString();
logger.info("Bucket encryption algorithm: {}", encryptionType);
logger.info("KMS Customer Managed Key ID: {}", rule.applyServerSideEncryptionByDefault().kmsMasterKeyID());
logger.info("Bucket Key Enabled: {}", rule.bucketKeyEnabled());
return encryptionType;
} catch (S3Exception e) {
logger.error("Failed to get bucket encryption: {} - Error code: {}", e.awsErrorDetails().errorMessage(),
e.awsErrorDetails().errorCode(), e);
throw e;
}
}
```
+ 有关 API 的详细信息，请参阅 *AWS SDK for Java 2.x API 参考[GetBucketEncryption](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/GetBucketEncryption)*中的。
------
# 与 AWS SDK `GetBucketPolicy` 配合使用
以下代码示例演示了如何使用 `GetBucketPolicy`。
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket#code-examples)中查找完整示例，了解如何进行设置和运行。
获取目录存储桶的策略。
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.GetBucketPolicyRequest;
import software.amazon.awssdk.services.s3.model.GetBucketPolicyResponse;
import software.amazon.awssdk.services.s3.model.S3Exception;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.createS3Client;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.getAwsAccountId;
import static com.example.s3.util.S3DirectoryBucketUtils.putDirectoryBucketPolicy;
/**
* Retrieves the bucket policy for the specified S3 directory bucket.
*
* @param s3Client The S3 client used to interact with S3
* @param bucketName The name of the directory bucket
* @return The bucket policy text
*/
public static String getDirectoryBucketPolicy(S3Client s3Client, String bucketName) {
logger.info("Getting policy for bucket: {}", bucketName);
try {
// Create a GetBucketPolicyRequest
GetBucketPolicyRequest policyReq = GetBucketPolicyRequest.builder()
.bucket(bucketName)
.build();
// Retrieve the bucket policy
GetBucketPolicyResponse response = s3Client.getBucketPolicy(policyReq);
// Print and return the policy text
String policyText = response.policy();
logger.info("Bucket policy: {}", policyText);
return policyText;
} catch (S3Exception e) {
logger.error("Failed to get bucket policy: {} - Error code: {}", e.awsErrorDetails().errorMessage(),
e.awsErrorDetails().errorCode(), e);
throw e;
}
}
```
+ 有关 API 的详细信息，请参阅 *AWS SDK for Java 2.x API 参考[GetBucketPolicy](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/GetBucketPolicy)*中的。
------
# 与 AWS SDK `GetObject` 配合使用
以下代码示例演示了如何使用 `GetObject`。
操作示例是大型程序的代码摘录，必须在上下文中运行。您可以在以下代码示例中查看此操作的上下文：
+ [了解基本功能](s3-directory-buckets_example_s3-directory-buckets_Scenario_ExpressBasics_section.md)
+ [创建预签名 URL 以获取对象](s3-directory-buckets_example_s3-directory-buckets_GeneratePresignedGetURLForDirectoryBucket_section.md)
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket#code-examples)中查找完整示例，了解如何进行设置和运行。
获取目录存储桶中的一个对象。
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.core.ResponseBytes;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.GetObjectRequest;
import software.amazon.awssdk.services.s3.model.GetObjectResponse;
import software.amazon.awssdk.services.s3.model.S3Exception;
import java.nio.charset.StandardCharsets;
import java.nio.file.Path;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.createS3Client;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteAllObjectsInDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.getFilePath;
import static com.example.s3.util.S3DirectoryBucketUtils.putDirectoryBucketObject;
/**
* Retrieves an object from the specified S3 directory bucket.
*
* @param s3Client The S3 client used to interact with S3
* @param bucketName The name of the directory bucket
* @param objectKey The key (name) of the object to be retrieved
* @return The retrieved object as a ResponseInputStream
*/
public static boolean getDirectoryBucketObject(S3Client s3Client, String bucketName, String objectKey) {
logger.info("Retrieving object: {} from bucket: {}", objectKey, bucketName);
try {
// Create a GetObjectRequest
GetObjectRequest objectRequest = GetObjectRequest.builder()
.key(objectKey)
.bucket(bucketName)
.build();
// Retrieve the object as bytes
ResponseBytes objectBytes = s3Client.getObjectAsBytes(objectRequest);
byte[] data = objectBytes.asByteArray();
// Print object contents to console
String objectContent = new String(data, StandardCharsets.UTF_8);
logger.info("Object contents: \n{}", objectContent);
return true;
} catch (S3Exception e) {
logger.error("Failed to retrieve object: {} - Error code: {}", e.awsErrorDetails().errorMessage(),
e.awsErrorDetails().errorCode(), e);
return false;
}
}
```
+ 有关 API 的详细信息，请参阅 *AWS SDK for Java 2.x API 参考[GetObject](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/GetObject)*中的。
------
# 与 AWS SDK `GetObjectAttributes` 配合使用
以下代码示例演示了如何使用 `GetObjectAttributes`。
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket#code-examples)中查找完整示例，了解如何进行设置和运行。
获取目录存储桶中的对象属性。
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.GetObjectAttributesRequest;
import software.amazon.awssdk.services.s3.model.GetObjectAttributesResponse;
import software.amazon.awssdk.services.s3.model.ObjectAttributes;
import software.amazon.awssdk.services.s3.model.S3Exception;
import java.nio.file.Path;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.createS3Client;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteAllObjectsInDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.getFilePath;
import static com.example.s3.util.S3DirectoryBucketUtils.putDirectoryBucketObject;
/**
* Retrieves attributes for an object in the specified S3 directory bucket.
*
* @param s3Client The S3 client used to interact with S3
* @param bucketName The name of the directory bucket
* @param objectKey The key (name) of the object to retrieve attributes for
* @return True if the object attributes are successfully retrieved, false
* otherwise
*/
public static boolean getDirectoryBucketObjectAttributes(S3Client s3Client, String bucketName, String objectKey) {
logger.info("Retrieving attributes for object: {} from bucket: {}", objectKey, bucketName);
try {
// Create a GetObjectAttributesRequest
GetObjectAttributesRequest getObjectAttributesRequest = GetObjectAttributesRequest.builder()
.bucket(bucketName)
.key(objectKey)
.objectAttributes(ObjectAttributes.E_TAG, ObjectAttributes.STORAGE_CLASS,
ObjectAttributes.OBJECT_SIZE)
.build();
// Retrieve the object attributes
GetObjectAttributesResponse response = s3Client.getObjectAttributes(getObjectAttributesRequest);
logger.info("Attributes for object {}:", objectKey);
logger.info("ETag: {}", response.eTag());
logger.info("Storage Class: {}", response.storageClass());
logger.info("Object Size: {}", response.objectSize());
return true;
} catch (S3Exception e) {
logger.error("Failed to retrieve object attributes: {} - Error code: {}",
e.awsErrorDetails().errorMessage(), e.awsErrorDetails().errorCode(), e);
return false;
}
}
```
+ 有关 API 的详细信息，请参阅 *AWS SDK for Java 2.x API 参考[GetObjectAttributes](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/GetObjectAttributes)*中的。
------
# 与 AWS SDK `HeadBucket` 配合使用
以下代码示例演示了如何使用 `HeadBucket`。
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket#code-examples)中查找完整示例，了解如何进行设置和运行。
检查指定的 S3 目录存储桶是否存在并且可供访问。
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.HeadBucketRequest;
import software.amazon.awssdk.services.s3.model.S3Exception;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.createS3Client;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteDirectoryBucket;
/**
* Checks if the specified S3 directory bucket exists and is accessible.
*
* @param s3Client The S3 client used to interact with S3
* @param bucketName The name of the directory bucket to check
* @return True if the bucket exists and is accessible, false otherwise
*/
public static boolean headDirectoryBucket(S3Client s3Client, String bucketName) {
logger.info("Checking if bucket exists: {}", bucketName);
try {
// Create a HeadBucketRequest
HeadBucketRequest headBucketRequest = HeadBucketRequest.builder()
.bucket(bucketName)
.build();
// If the bucket doesn't exist, the following statement throws NoSuchBucketException,
// which is a subclass of S3Exception.
s3Client.headBucket(headBucketRequest);
logger.info("Amazon S3 directory bucket: \"{}\" found.", bucketName);
return true;
} catch (S3Exception e) {
logger.error("Failed to access bucket: {} - Error code: {}", e.awsErrorDetails().errorMessage(),
e.awsErrorDetails().errorCode(), e);
throw e;
}
}
```
+ 有关 API 的详细信息，请参阅 *AWS SDK for Java 2.x API 参考[HeadBucket](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/HeadBucket)*中的。
------
# 与 AWS SDK `HeadObject` 配合使用
以下代码示例演示了如何使用 `HeadObject`。
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket#code-examples)中查找完整示例，了解如何进行设置和运行。
获取目录存储桶中对象的元数据。
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.HeadObjectRequest;
import software.amazon.awssdk.services.s3.model.HeadObjectResponse;
import software.amazon.awssdk.services.s3.model.S3Exception;
import java.nio.file.Path;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.createS3Client;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteAllObjectsInDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.getFilePath;
import static com.example.s3.util.S3DirectoryBucketUtils.putDirectoryBucketObject;
/**
* Retrieves metadata for an object in the specified S3 directory bucket.
*
* @param s3Client The S3 client used to interact with S3
* @param bucketName The name of the directory bucket
* @param objectKey The key (name) of the object to retrieve metadata for
* @return True if the object exists, false otherwise
*/
public static boolean headDirectoryBucketObject(S3Client s3Client, String bucketName, String objectKey) {
logger.info("Retrieving metadata for object: {} from bucket: {}", objectKey, bucketName);
try {
// Create a HeadObjectRequest
HeadObjectRequest headObjectRequest = HeadObjectRequest.builder()
.bucket(bucketName)
.key(objectKey)
.build();
// Retrieve the object metadata
HeadObjectResponse response = s3Client.headObject(headObjectRequest);
logger.info("Amazon S3 object: \"{}\" found in bucket: \"{}\" with ETag: \"{}\"", objectKey, bucketName,
response.eTag());
logger.info("Content-Type: {}", response.contentType());
logger.info("Content-Length: {}", response.contentLength());
logger.info("Last Modified: {}", response.lastModified());
return true;
} catch (S3Exception e) {
logger.error("Failed to retrieve object metadata: {} - Error code: {}", e.awsErrorDetails().errorMessage(),
e.awsErrorDetails().errorCode(), e);
return false;
}
}
```
+ 有关 API 的详细信息，请参阅 *AWS SDK for Java 2.x API 参考[HeadObject](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/HeadObject)*中的。
------
# 与 AWS SDK `ListDirectoryBuckets` 配合使用
以下代码示例演示了如何使用 `ListDirectoryBuckets`。
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket#code-examples)中查找完整示例，了解如何进行设置和运行。
列出所有目录存储桶。
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.Bucket;
import software.amazon.awssdk.services.s3.model.ListDirectoryBucketsRequest;
import software.amazon.awssdk.services.s3.model.ListDirectoryBucketsResponse;
import software.amazon.awssdk.services.s3.model.S3Exception;
import java.util.List;
import java.util.UUID;
import java.util.stream.Collectors;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.createS3Client;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteDirectoryBucket;
/**
* Lists all S3 directory buckets and no general purpose buckets.
*
* @param s3Client The S3 client used to interact with S3
* @return A list of bucket names
*/
public static List listDirectoryBuckets(S3Client s3Client) {
logger.info("Listing all directory buckets");
try {
// Create a ListBucketsRequest
ListDirectoryBucketsRequest listDirectoryBucketsRequest = ListDirectoryBucketsRequest.builder().build();
// Retrieve the list of buckets
ListDirectoryBucketsResponse response = s3Client.listDirectoryBuckets(listDirectoryBucketsRequest);
// Extract bucket names
List bucketNames = response.buckets().stream()
.map(Bucket::name)
.collect(Collectors.toList());
return bucketNames;
} catch (S3Exception e) {
logger.error("Failed to list buckets: {} - Error code: {}", e.awsErrorDetails().errorMessage(),
e.awsErrorDetails().errorCode());
throw e;
}
}
```
+ 有关 API 的详细信息，请参阅 *AWS SDK for Java 2.x API 参考[ListDirectoryBuckets](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/ListDirectoryBuckets)*中的。
------
# 与 AWS SDK `ListMultipartUploads` 配合使用
以下代码示例演示了如何使用 `ListMultipartUploads`。
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket#code-examples)中查找完整示例，了解如何进行设置和运行。
列出目录存储桶中的分段上传。
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.ListMultipartUploadsRequest;
import software.amazon.awssdk.services.s3.model.ListMultipartUploadsResponse;
import software.amazon.awssdk.services.s3.model.MultipartUpload;
import software.amazon.awssdk.services.s3.model.S3Exception;
import java.io.IOException;
import java.nio.file.Path;
import java.util.List;
import static com.example.s3.util.S3DirectoryBucketUtils.abortDirectoryBucketMultipartUploads;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucketMultipartUpload;
import static com.example.s3.util.S3DirectoryBucketUtils.createS3Client;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.getFilePath;
import static com.example.s3.util.S3DirectoryBucketUtils.multipartUploadForDirectoryBucket;
/**
* Lists multipart uploads for the specified S3 directory bucket.
*
* @param s3Client The S3 client used to interact with S3
* @param bucketName The name of the directory bucket
* @return A list of MultipartUpload objects representing the multipart uploads
*/
public static List listDirectoryBucketMultipartUploads(S3Client s3Client, String bucketName) {
logger.info("Listing in-progress multipart uploads for bucket: {}", bucketName);
try {
// Create a ListMultipartUploadsRequest
ListMultipartUploadsRequest listMultipartUploadsRequest = ListMultipartUploadsRequest.builder()
.bucket(bucketName)
.build();
// List the multipart uploads
ListMultipartUploadsResponse response = s3Client.listMultipartUploads(listMultipartUploadsRequest);
List uploads = response.uploads();
for (MultipartUpload upload : uploads) {
logger.info("In-progress multipart upload: Upload ID: {}, Key: {}, Initiated: {}", upload.uploadId(),
upload.key(), upload.initiated());
}
return uploads;
} catch (S3Exception e) {
logger.error("Failed to list multipart uploads: {} - Error code: {}", e.awsErrorDetails().errorMessage(),
e.awsErrorDetails().errorCode());
return List.of(); // Return an empty list if an exception is thrown
}
}
```
+ 有关 API 的详细信息，请参阅 *AWS SDK for Java 2.x API 参考[ListMultipartUploads](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/ListMultipartUploads)*中的。
------
# 与 AWS SDK `ListObjectsV2` 配合使用
以下代码示例演示了如何使用 `ListObjectsV2`。
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket#code-examples)中查找完整示例，了解如何进行设置和运行。
列出目录存储桶中的对象。
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.ListObjectsV2Request;
import software.amazon.awssdk.services.s3.model.ListObjectsV2Response;
import software.amazon.awssdk.services.s3.model.S3Exception;
import software.amazon.awssdk.services.s3.model.S3Object;
import java.nio.file.Path;
import java.util.List;
import java.util.stream.Collectors;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.createS3Client;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteAllObjectsInDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.getFilePath;
import static com.example.s3.util.S3DirectoryBucketUtils.putDirectoryBucketObject;
/**
* Lists objects in the specified S3 directory bucket.
*
* @param s3Client The S3 client used to interact with S3
* @param bucketName The name of the directory bucket
* @return A list of object keys in the bucket
*/
public static List listDirectoryBucketObjectsV2(S3Client s3Client, String bucketName) {
logger.info("Listing objects in bucket: {}", bucketName);
try {
// Create a ListObjectsV2Request
ListObjectsV2Request listObjectsV2Request = ListObjectsV2Request.builder()
.bucket(bucketName)
.build();
// Retrieve the list of objects
ListObjectsV2Response response = s3Client.listObjectsV2(listObjectsV2Request);
// Extract and return the object keys
return response.contents().stream()
.map(S3Object::key)
.collect(Collectors.toList());
} catch (S3Exception e) {
logger.error("Failed to list objects: {} - Error code: {}", e.awsErrorDetails().errorMessage(),
e.awsErrorDetails().errorCode());
throw e;
}
}
```
+ 有关 API 的详细信息，请参阅 *AWS SDK for Java 2.x API 参考*中的 [ListObjectsV2](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/ListObjectsV2)。
------
# 与 AWS SDK `ListParts` 配合使用
以下代码示例演示了如何使用 `ListParts`。
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket#code-examples)中查找完整示例，了解如何进行设置和运行。
列出目录存储桶中分段上传的分段。
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.ListPartsRequest;
import software.amazon.awssdk.services.s3.model.ListPartsResponse;
import software.amazon.awssdk.services.s3.model.Part;
import software.amazon.awssdk.services.s3.model.S3Exception;
import java.io.IOException;
import java.nio.file.Path;
import java.util.List;
import static com.example.s3.util.S3DirectoryBucketUtils.abortDirectoryBucketMultipartUploads;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucketMultipartUpload;
import static com.example.s3.util.S3DirectoryBucketUtils.createS3Client;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.getFilePath;
import static com.example.s3.util.S3DirectoryBucketUtils.multipartUploadForDirectoryBucket;
/**
* Lists the parts of a multipart upload for the specified S3 directory bucket.
*
* @param s3Client The S3 client used to interact with S3
* @param bucketName The name of the directory bucket
* @param objectKey The key (name) of the object being uploaded
* @param uploadId The upload ID used to track the multipart upload
* @return A list of Part representing the parts of the multipart upload
*/
public static List listDirectoryBucketMultipartUploadParts(S3Client s3Client, String bucketName,
String objectKey, String uploadId) {
logger.info("Listing parts for object: {} in bucket: {}", objectKey, bucketName);
try {
// Create a ListPartsRequest
ListPartsRequest listPartsRequest = ListPartsRequest.builder()
.bucket(bucketName)
.uploadId(uploadId)
.key(objectKey)
.build();
// List the parts of the multipart upload
ListPartsResponse response = s3Client.listParts(listPartsRequest);
List parts = response.parts();
for (Part part : parts) {
logger.info("Uploaded part: Part number = \"{}\", etag = {}", part.partNumber(), part.eTag());
}
return parts;
} catch (S3Exception e) {
logger.error("Failed to list parts: {} - Error code: {}", e.awsErrorDetails().errorMessage(),
e.awsErrorDetails().errorCode());
return List.of(); // Return an empty list if an exception is thrown
}
}
```
+ 有关 API 的详细信息，请参阅 *AWS SDK for Java 2.x API 参考[ListParts](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/ListParts)*中的。
------
# 与 AWS SDK `PutBucketEncryption` 配合使用
以下代码示例演示了如何使用 `PutBucketEncryption`。
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket#code-examples)中查找完整示例，了解如何进行设置和运行。
为目录存储桶设置存储桶加密。
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.kms.KmsClient;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.PutBucketEncryptionRequest;
import software.amazon.awssdk.services.s3.model.S3Exception;
import software.amazon.awssdk.services.s3.model.ServerSideEncryption;
import software.amazon.awssdk.services.s3.model.ServerSideEncryptionByDefault;
import software.amazon.awssdk.services.s3.model.ServerSideEncryptionConfiguration;
import software.amazon.awssdk.services.s3.model.ServerSideEncryptionRule;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.createKmsClient;
import static com.example.s3.util.S3DirectoryBucketUtils.createKmsKey;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.scheduleKeyDeletion;
/**
* Sets the default encryption configuration for an S3 bucket as SSE-KMS.
*
* @param s3Client The S3 client used to interact with S3
* @param bucketName The name of the directory bucket
* @param kmsKeyId The ID of the customer-managed KMS key
*/
public static void putDirectoryBucketEncryption(S3Client s3Client, String bucketName, String kmsKeyId) {
// Define the default encryption configuration to use SSE-KMS. For directory
// buckets, AWS managed KMS keys aren't supported. Only customer-managed keys
// are supported.
ServerSideEncryptionByDefault encryptionByDefault = ServerSideEncryptionByDefault.builder()
.sseAlgorithm(ServerSideEncryption.AWS_KMS)
.kmsMasterKeyID(kmsKeyId)
.build();
// Create a server-side encryption rule to apply the default encryption
// configuration. For directory buckets, the bucketKeyEnabled field is enforced
// to be true.
ServerSideEncryptionRule rule = ServerSideEncryptionRule.builder()
.bucketKeyEnabled(true)
.applyServerSideEncryptionByDefault(encryptionByDefault)
.build();
// Create the server-side encryption configuration for the bucket
ServerSideEncryptionConfiguration encryptionConfiguration = ServerSideEncryptionConfiguration.builder()
.rules(rule)
.build();
// Create the PutBucketEncryption request
PutBucketEncryptionRequest putRequest = PutBucketEncryptionRequest.builder()
.bucket(bucketName)
.serverSideEncryptionConfiguration(encryptionConfiguration)
.build();
// Set the bucket encryption
try {
s3Client.putBucketEncryption(putRequest);
logger.info("SSE-KMS Bucket encryption configuration set for the directory bucket: {}", bucketName);
} catch (S3Exception e) {
logger.error("Failed to set bucket encryption: {} - Error code: {}", e.awsErrorDetails().errorMessage(),
e.awsErrorDetails().errorCode());
throw e;
}
}
```
+ 有关 API 的详细信息，请参阅 *AWS SDK for Java 2.x API 参考[PutBucketEncryption](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/PutBucketEncryption)*中的。
------
# 与 AWS SDK `PutBucketPolicy` 配合使用
以下代码示例演示了如何使用 `PutBucketPolicy`。
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket#code-examples)中查找完整示例，了解如何进行设置和运行。
将存储桶策略应用于目录存储桶。
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.PutBucketPolicyRequest;
import software.amazon.awssdk.services.s3.model.S3Exception;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.createS3Client;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.getAwsAccountId;
/**
* Sets the following bucket policy for the specified S3 directory bucket.
*
* {
* "Version":"2012-10-17",
* "Statement": [
* {
* "Sid": "AdminPolicy",
* "Effect": "Allow",
* "Principal": {
* "AWS": "arn:aws:iam:::root"
* },
* "Action": "s3express:*",
* "Resource": "arn:aws:s3express:us-west-2::bucket/
* }
* ]
* }
*
* This policy grants all S3 directory bucket actions to identities in the same account as the bucket.
*
* @param s3Client The S3 client used to interact with S3
* @param bucketName The name of the directory bucket
* @param policyText The policy text to be applied
*/
public static void putDirectoryBucketPolicy(S3Client s3Client, String bucketName, String policyText) {
logger.info("Setting policy on bucket: {}", bucketName);
logger.info("Policy: {}", policyText);
try {
PutBucketPolicyRequest policyReq = PutBucketPolicyRequest.builder()
.bucket(bucketName)
.policy(policyText)
.build();
s3Client.putBucketPolicy(policyReq);
logger.info("Bucket policy set successfully!");
} catch (S3Exception e) {
logger.error("Failed to set bucket policy: {} - Error code: {}", e.awsErrorDetails().errorMessage(),
e.awsErrorDetails().errorCode(), e);
throw e;
}
}
```
+ 有关 API 的详细信息，请参阅 *AWS SDK for Java 2.x API 参考[PutBucketPolicy](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/PutBucketPolicy)*中的。
------
# 与 AWS SDK `PutObject` 配合使用
以下代码示例演示了如何使用 `PutObject`。
操作示例是大型程序的代码摘录，必须在上下文中运行。在以下代码示例中，您可以查看此操作的上下文：
+ [了解基本功能](s3-directory-buckets_example_s3-directory-buckets_Scenario_ExpressBasics_section.md)
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket#code-examples)中查找完整示例，了解如何进行设置和运行。
将对象放入目录存储桶。
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.awscore.exception.AwsErrorDetails;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.PutObjectRequest;
import software.amazon.awssdk.services.s3.model.S3Exception;
import java.io.UncheckedIOException;
import java.nio.file.Path;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.createS3Client;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteAllObjectsInDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.getFilePath;
/**
* Puts an object into the specified S3 directory bucket.
*
* @param s3Client The S3 client used to interact with S3
* @param bucketName The name of the directory bucket
* @param objectKey The key (name) of the object to be placed in the bucket
* @param filePath The path of the file to be uploaded
*/
public static void putDirectoryBucketObject(S3Client s3Client, String bucketName, String objectKey, Path filePath) {
logger.info("Putting object: {} into bucket: {}", objectKey, bucketName);
try {
// Create a PutObjectRequest
PutObjectRequest putObj = PutObjectRequest.builder()
.bucket(bucketName)
.key(objectKey)
.build();
// Upload the object
s3Client.putObject(putObj, filePath);
logger.info("Successfully placed {} into bucket {}", objectKey, bucketName);
} catch (UncheckedIOException e) {
throw S3Exception.builder().message("Failed to read the file: " + e.getMessage()).cause(e)
.awsErrorDetails(AwsErrorDetails.builder()
.errorCode("ClientSideException:FailedToReadFile")
.errorMessage(e.getMessage())
.build())
.build();
} catch (S3Exception e) {
logger.error("Failed to put object: {}", e.getMessage(), e);
throw e;
}
}
```
+ 有关 API 的详细信息，请参阅 *AWS SDK for Java 2.x API 参考[PutObject](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/PutObject)*中的。
------
# 与 AWS SDK `UploadPart` 配合使用
以下代码示例演示了如何使用 `UploadPart`。
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket#code-examples)中查找完整示例，了解如何进行设置和运行。
上传目录存储桶的分段上传的分段。
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.core.sync.RequestBody;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.CompletedPart;
import software.amazon.awssdk.services.s3.model.S3Exception;
import software.amazon.awssdk.services.s3.model.UploadPartRequest;
import software.amazon.awssdk.services.s3.model.UploadPartResponse;
import java.io.IOException;
import java.io.RandomAccessFile;
import java.nio.ByteBuffer;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.List;
import static com.example.s3.util.S3DirectoryBucketUtils.abortDirectoryBucketMultipartUploads;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucketMultipartUpload;
import static com.example.s3.util.S3DirectoryBucketUtils.createS3Client;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteAllObjectsInDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.getFilePath;
/**
* This method creates part requests and uploads individual parts to S3.
* While it uses the UploadPart API to upload a single part, it does so
* sequentially to handle multiple parts of a file, returning all the completed
* parts.
*
* @param s3Client The S3 client used to interact with S3
* @param bucketName The name of the directory bucket
* @param objectKey The key (name) of the object to be uploaded
* @param uploadId The upload ID used to track the multipart upload
* @param filePath The path to the file to be uploaded
* @return A list of uploaded parts
* @throws IOException if an I/O error occurs
*/
public static List multipartUploadForDirectoryBucket(S3Client s3Client, String bucketName,
String objectKey, String uploadId, Path filePath) throws IOException {
logger.info("Uploading parts for object: {} in bucket: {}", objectKey, bucketName);
int partNumber = 1;
List uploadedParts = new ArrayList<>();
ByteBuffer bb = ByteBuffer.allocate(1024 * 1024 * 5); // 5 MB byte buffer
// Read the local file, break down into chunks and process
try (RandomAccessFile file = new RandomAccessFile(filePath.toFile(), "r")) {
long fileSize = file.length();
int position = 0;
// Sequentially upload parts of the file
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(objectKey)
.uploadId(uploadId)
.partNumber(partNumber)
.build();
UploadPartResponse partResponse = s3Client.uploadPart(
uploadPartRequest,
RequestBody.fromByteBuffer(bb));
// Build the uploaded part
CompletedPart uploadedPart = CompletedPart.builder()
.partNumber(partNumber)
.eTag(partResponse.eTag())
.build();
// Add the uploaded part to the list
uploadedParts.add(uploadedPart);
// Log to indicate the part upload is done
logger.info("Uploaded part number: {} with ETag: {}", partNumber, partResponse.eTag());
bb.clear();
position += read;
partNumber++;
}
} catch (S3Exception e) {
logger.error("Failed to list parts: {} - Error code: {}", e.awsErrorDetails().errorMessage(),
e.awsErrorDetails().errorCode());
throw e;
}
return uploadedParts;
}
```
+ 有关 API 的详细信息，请参阅 *AWS SDK for Java 2.x API 参考[UploadPart](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/UploadPart)*中的。
------
# 与 AWS SDK `UploadPartCopy` 配合使用
以下代码示例演示了如何使用 `UploadPartCopy`。
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket#code-examples)中查找完整示例，了解如何进行设置和运行。
根据源对象大小创建复制分段，然后将各个分段复制到目录存储桶。
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.CompletedPart;
import software.amazon.awssdk.services.s3.model.HeadObjectRequest;
import software.amazon.awssdk.services.s3.model.HeadObjectResponse;
import software.amazon.awssdk.services.s3.model.S3Exception;
import software.amazon.awssdk.services.s3.model.UploadPartCopyRequest;
import software.amazon.awssdk.services.s3.model.UploadPartCopyResponse;
import java.io.IOException;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.List;
import static com.example.s3.util.S3DirectoryBucketUtils.abortDirectoryBucketMultipartUploads;
import static com.example.s3.util.S3DirectoryBucketUtils.completeDirectoryBucketMultipartUpload;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucketMultipartUpload;
import static com.example.s3.util.S3DirectoryBucketUtils.createS3Client;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteAllObjectsInDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.getFilePath;
import static com.example.s3.util.S3DirectoryBucketUtils.multipartUploadForDirectoryBucket;
/**
* Creates copy parts based on source object size and copies over individual
* parts.
*
* @param s3Client The S3 client used to interact with S3
* @param sourceBucket The name of the source bucket
* @param sourceKey The key (name) of the source object
* @param destinationBucket The name of the destination bucket
* @param destinationKey The key (name) of the destination object
* @param uploadId The upload ID used to track the multipart upload
* @return A list of completed parts
*/
public static List multipartUploadCopyForDirectoryBucket(S3Client s3Client, String sourceBucket,
String sourceKey, String destinationBucket, String destinationKey, String uploadId) {
// Get the object size to track the end of the copy operation
HeadObjectRequest headObjectRequest = HeadObjectRequest.builder()
.bucket(sourceBucket)
.key(sourceKey)
.build();
HeadObjectResponse headObjectResponse = s3Client.headObject(headObjectRequest);
long objectSize = headObjectResponse.contentLength();
logger.info("Source Object size: {}", objectSize);
// Copy the object using 20 MB parts
long partSize = 20 * 1024 * 1024; // 20 MB
long bytePosition = 0;
int partNum = 1;
List uploadedParts = new ArrayList<>();
while (bytePosition < objectSize) {
long lastByte = Math.min(bytePosition + partSize - 1, objectSize - 1);
logger.info("Part Number: {}, Byte Position: {}, Last Byte: {}", partNum, bytePosition, lastByte);
try {
UploadPartCopyRequest uploadPartCopyRequest = UploadPartCopyRequest.builder()
.sourceBucket(sourceBucket)
.sourceKey(sourceKey)
.destinationBucket(destinationBucket)
.destinationKey(destinationKey)
.uploadId(uploadId)
.copySourceRange("bytes=" + bytePosition + "-" + lastByte)
.partNumber(partNum)
.build();
UploadPartCopyResponse uploadPartCopyResponse = s3Client.uploadPartCopy(uploadPartCopyRequest);
CompletedPart part = CompletedPart.builder()
.partNumber(partNum)
.eTag(uploadPartCopyResponse.copyPartResult().eTag())
.build();
uploadedParts.add(part);
bytePosition += partSize;
partNum++;
} catch (S3Exception e) {
logger.error("Failed to copy part number {}: {} - Error code: {}", partNum,
e.awsErrorDetails().errorMessage(), e.awsErrorDetails().errorCode());
throw e;
}
}
return uploadedParts;
}
```
+ 有关 API 的详细信息，请参阅 *AWS SDK for Java 2.x API 参考[UploadPartCopy](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/UploadPartCopy)*中的。
------
# 使用 S3 目录存储桶的场景 AWS SDKs
以下代码示例向您展示了如何使用在 S3 目录存储桶中实现常见场景。 AWS SDKs这些场景向您展示了如何通过调用 S3 Directory Buckets 中的多个函数或与其它 AWS 服务结合来完成特定任务。每个场景都包含完整源代码的链接，您可以在其中找到有关如何设置和运行代码的说明。
场景以中等水平的经验为目标，可帮助您结合具体环境了解服务操作。
**Topics**
+ [创建预签名 URL 以获取对象](s3-directory-buckets_example_s3-directory-buckets_GeneratePresignedGetURLForDirectoryBucket_section.md)
# 使用 SDK 为 Amazon S3 目录存储桶创建预签名 URL 以获取对象 AWS
以下代码示例演示如何为 S3 目录存储桶创建预签名 URL 以及获取对象。
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
还有更多相关信息 GitHub。在 [AWS 代码示例存储库](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket#code-examples)中查找完整示例，了解如何进行设置和运行。
生成用于访问 S3 目录存储桶中的对象的预签名 GET URL。
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.GetObjectRequest;
import software.amazon.awssdk.services.s3.model.S3Exception;
import software.amazon.awssdk.services.s3.presigner.S3Presigner;
import software.amazon.awssdk.services.s3.presigner.model.GetObjectPresignRequest;
import software.amazon.awssdk.services.s3.presigner.model.PresignedGetObjectRequest;
import java.nio.file.Path;
import java.time.Duration;
import static com.example.s3.util.S3DirectoryBucketUtils.createDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.createS3Client;
import static com.example.s3.util.S3DirectoryBucketUtils.createS3Presigner;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteAllObjectsInDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.deleteDirectoryBucket;
import static com.example.s3.util.S3DirectoryBucketUtils.getFilePath;
import static com.example.s3.util.S3DirectoryBucketUtils.putDirectoryBucketObject;
/**
* Generates a presigned URL for accessing an object in the specified S3
* directory bucket.
*
* @param s3Presigner The S3 presigner client used to generate the presigned URL
* @param bucketName The name of the directory bucket
* @param objectKey The key (name) of the object to access
* @return A presigned URL for accessing the specified object
*/
public static String generatePresignedGetURLForDirectoryBucket(S3Presigner s3Presigner, String bucketName,
String objectKey) {
logger.info("Generating presigned URL for object: {} in bucket: {}", objectKey, bucketName);
try {
// Create a GetObjectRequest
GetObjectRequest getObjectRequest = GetObjectRequest.builder()
.bucket(bucketName)
.key(objectKey)
.build();
// Create a GetObjectPresignRequest
GetObjectPresignRequest getObjectPresignRequest = GetObjectPresignRequest.builder()
.signatureDuration(Duration.ofMinutes(10)) // Presigned URL valid for 10 minutes
.getObjectRequest(getObjectRequest)
.build();
// Generate the presigned URL
PresignedGetObjectRequest presignedGetObjectRequest = s3Presigner.presignGetObject(getObjectPresignRequest);
// Get the presigned URL
String presignedURL = presignedGetObjectRequest.url().toString();
logger.info("Presigned URL: {}", presignedURL);
return presignedURL;
} catch (S3Exception e) {
logger.error("Failed to generate presigned URL: {} - Error code: {}", e.awsErrorDetails().errorMessage(),
e.awsErrorDetails().errorCode(), e);
throw e;
}
}
```
+ 有关 API 的详细信息，请参阅 *AWS SDK for Java 2.x API 参考[GetObject](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/GetObject)*中的。
------