AWS S3 with Java – 使用Java的AWS S3

最后修改: 2017年 7月 24日

中文/混合/英文(键盘快捷键：t)

1. Introduction

1.介绍

In this tutorial, we’ll learn how to interact with the Amazon S3 (Simple Storage Service) storage system programmatically from Java.

在本教程中，我们将学习如何从Java中以编程方式与Amazon S3（简单存储服务）存储系统互动。

Remember that S3 has a very simple structure; each bucket can store any number of objects, which can be accessed using either a SOAP interface or a REST-style API.

请记住，S3有一个非常简单的结构；每个桶可以存储任何数量的对象，可以使用SOAP接口或REST风格的API访问。

Going forward, we’ll use the AWS SDK for Java to create, list, and delete S3 buckets. We’ll also upload, list, download, copy, move, rename and delete objects within these buckets.

展望未来，我们将使用AWS SDK for Java来创建、列出和删除S3桶。我们还将上传、列出、下载、复制、移动、重命名和删除这些桶中的对象。

2. Maven Dependencies

2.Maven的依赖性

Before we get started, we need to declare the AWS SDK dependency in our project:

在我们开始之前，我们需要在我们的项目中声明AWS SDK的依赖性。

<dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-java-sdk</artifactId>
    <version>1.11.163</version>
</dependency>

To view the latest version, we can check Maven Central.

要查看最新版本，我们可以查看Maven Central。

3. Prerequisites

3.先决条件

To use AWS SDK, we’ll need a few things:

为了使用AWS SDK，我们需要一些东西。

  1. AWS Account: we need an Amazon Web Services account. If we don’t have one, we can go ahead and create an account.
  2. AWS Security Credentials: These are our access keys that allow us to make programmatic calls to AWS API actions. We can get these credentials in two ways, either by using AWS root account credentials from the access keys section of the Security Credentials page, or by using IAM user credentials from the IAM console.
  3. Choosing AWS Region: We also have to select the AWS region(s) where we want to store our Amazon S3 data. Keep in mind that S3 storage prices vary by region. For more details, head over to the official documentation. In this tutorial, we’ll use US East (Ohio, region us-east-2).

4. Creating Client Connection

4.创建客户连接

First, we need to create a client connection to access the Amazon S3 web service. We’ll use the AmazonS3 interface for this purpose:

首先，我们需要创建一个客户端连接来访问Amazon S3网络服务。我们将使用AmazonS3接口来实现这一目的。

AWSCredentials credentials = new BasicAWSCredentials(
  "<AWS accesskey>", 
  "<AWS secretkey>"
);

Then we’ll configure the client:

然后我们将配置客户端。

AmazonS3 s3client = AmazonS3ClientBuilder
  .standard()
  .withCredentials(new AWSStaticCredentialsProvider(credentials))
  .withRegion(Regions.US_EAST_2)
  .build();

5. Amazon S3 Bucket Operations

5.亚马逊S3桶操作

5.1. Creating a Bucket

5.1.创建一个水桶

It’s important to note that the bucket namespace is shared by all users of the system. So our bucket name must be unique across all existing bucket names in Amazon S3 (we’ll find out how to check that in just a moment).

值得注意的是，桶的名字空间是由系统的所有用户共享的。所以我们的桶的名字必须在Amazon S3的所有现有桶的名字中是唯一的（我们将在稍后发现如何检查）。

In addition, as specified in the official documentation, the Bucket names must comply with the following requirements:

此外，正如官方文件中所规定的，水桶名称必须符合以下要求。

  • names shouldn’t contain underscores
  • names should be between 3 and 63 characters long
  • names shouldn’t end with a dash
  • names can’t contain adjacent periods
  • names can’t contain dashes next to periods (e.g., “my-.bucket.com” and “my.-bucket” are invalid)
  • names can’t contain uppercase characters

Now let’s create a bucket:

现在我们来创建一个水桶。

String bucketName = "baeldung-bucket";

if(s3client.doesBucketExist(bucketName)) {
    LOG.info("Bucket name is not available."
      + " Try again with a different Bucket name.");
    return;
}

s3client.createBucket(bucketName);

Here we’re using the s3client that we created in the previous step. Before we create a bucket, we have to check whether our bucket name is available or not by using the doesBucketExist() method. If the name is available, then we’ll use the createBucket() method.

在这里，我们正在使用我们在上一步创建的s3client。在我们创建一个桶之前，我们必须通过使用doesBucketExist() 方法来检查我们的桶名是否可用。如果这个名字是可用的，那么我们将使用createBucket() 方法。

5.2. Listing Buckets

5.2.列表桶

Now that we’ve created a few buckets, let’s print a list of all the buckets available in our S3 environment using the listBuckets() method. This method will return a list of all the Buckets:

现在我们已经创建了几个桶，让我们使用listBuckets()方法打印S3环境中所有可用的桶的列表。这个方法将返回一个所有Buckets的列表。

List<Bucket> buckets = s3client.listBuckets();
for(Bucket bucket : buckets) {
    System.out.println(bucket.getName());
}

This will list all the buckets that are present in our S3 environment:

这将列出所有存在于我们S3环境中的桶。

baeldung-bucket
baeldung-bucket-test2
elasticbeanstalk-us-east-2

5.3. Deleting a Bucket

5.3.删除一个水桶

It’s important to ensure that our bucket is empty before we delete it. Otherwise, an exception will be thrown. Also, note that only the owner of a bucket can delete it, regardless of its permissions (Access Control Policies):

在我们删除它之前，必须确保我们的水桶是空的。否则，将抛出一个异常。另外，请注意，只有水桶的所有者可以删除它，而不考虑它的权限（访问控制策略）。

try {
    s3client.deleteBucket("baeldung-bucket-test2");
} catch (AmazonServiceException e) {
    System.err.println("e.getErrorMessage());
    return;
}

6. Amazon S3 Object Operations

6.亚马逊S3的对象操作

A file or collection of data inside an Amazon S3 bucket is known as an object. We can perform several operations on objects like uploading, listing, downloading, copying, moving, renaming and deleting.

亚马逊S3桶内的文件或数据集合被称为对象。我们可以对对象进行若干操作，如上传、列出、下载、复制、移动、重命名和删除。

6.1. Uploading Objects

6.1.上传对象

Uploading an object is a pretty straightforward process. We’ll use the putObject() method, which accepts three parameters:

上传一个对象是一个相当直接的过程。我们将使用putObject() 方法，它接受三个参数。

  1. bucketName: The bucket name where we want to upload the object
  2. key: This is the full path to the file
  3. file: The actual file containing the data to be uploaded
s3client.putObject(
  bucketName, 
  "Document/hello.txt", 
  new File("/Users/user/Document/hello.txt")
);

6.2. Listing Objects

6.2.列出对象

We’ll use the listObjects() method to list all the available objects in our S3 bucket:

我们将使用listObjects() 方法来列出我们的S3桶中的所有可用对象。

ObjectListing objectListing = s3client.listObjects(bucketName);
for(S3ObjectSummary os : objectListing.getObjectSummaries()) {
    LOG.info(os.getKey());
}

Calling the listObjects() method of the s3client object will yield the ObjectListing object, which can be used to get a list of all the object summaries in the specified bucket. We’re just printing the key here, but there are also a couple of other options available, like size, owner, last modified, storage class, etc.

调用s3client对象的listObjects()方法将产生ObjectListing对象，它可以被用来获得指定桶中所有对象摘要的列表。我们在这里只是打印钥匙，但也有一些其他选项可用，如大小、所有者、最后修改、存储类别等。

This will now print a list of all the objects inside our bucket:

现在，这将打印出我们的桶内所有对象的列表。

Document/hello.txt

6.3. Downloading an Object

6.3.下载一个对象

To download an object, we’ll first use the getObject() method on the s3client, which will return an S3Object object. Once we get this, we’ll call getObjectContent() on it to get an S3ObjectInputStream object, which behaves like a conventional Java InputStream:

为了下载一个对象，我们将首先使用s3client上的getObject() 方法，它将返回一个S3Object对象。一旦我们得到这个对象，我们将调用getObjectContent()来得到一个S3ObjectInputStream对象，它的行为就像一个传统的JavaInputStream：。

S3Object s3object = s3client.getObject(bucketName, "picture/pic.png");
S3ObjectInputStream inputStream = s3object.getObjectContent();
FileUtils.copyInputStreamToFile(inputStream, new File("/Users/user/Desktop/hello.txt"));

Here we’re using the FileUtils.copyInputStreamToFile() method by Apache Commons. We can also visit this Baeldung article to explore other ways to convert an InputStream to a File.

这里我们使用的是Apache Commons的FileUtils.copyInputStreamToFile()方法。我们也可以访问这篇Baeldung文章来探索将InputStream转换为文件的其他方法。

6.4. Copying, Renaming, and Moving an Object

6.4.复制、重命名和移动一个物体

We can copy an object by calling the copyObject() method on our s3client, which accepts four parameters:

我们可以通过在我们的s3client上调用copyObject()方法来复制一个对象，该方法接受四个参数。

  1. source bucket name
  2. object key in source bucket
  3. destination bucket name (it can be same as source)
  4. object key in destination bucket
s3client.copyObject(
  "baeldung-bucket", 
  "picture/pic.png", 
  "baeldung-bucket2", 
  "document/picture.png"
);

Note: We can use a combination of the copyObject() method and deleteObject() for performing moving and renaming tasks. This will involve copying the object first and then deleting it from its old location.

注意：我们可以使用copyObject()方法和deleteObject()组合来执行移动和重命名任务。这将涉及到先复制对象，然后从旧的位置删除它。

6.5. Deleting an Object

6.5.删除一个对象

To delete an Object, we’ll call the deleteObject() method on the s3client and pass the bucket name and object key:

要删除一个对象，我们将调用deleteObject()方法，在s3client上传递桶名和对象键。

s3client.deleteObject("baeldung-bucket","picture/pic.png");

6.6. Deleting Multiple Objects

6.6.删除多个对象

To delete multiple objects at once, we’ll first create the DeleteObjectsRequest object and pass the bucket name to its constructor. Then we’ll pass an array of all the object keys that we want to delete.

要一次删除多个对象，我们首先要创建DeleteObjectsRequest对象，并将桶的名称传递给它的构造函数。然后，我们将传递一个我们想要删除的所有对象键的数组。

Once we have this DeleteObjectsRequest object, we can pass it to the deleteObjects() method of our s3client as an argument. If successful, it’ll delete all the objects that we supplied:

一旦我们有了这个DeleteObjectsRequest对象，我们就可以把它作为一个参数传递给我们的s3client的deleteObjects()方法。如果成功，它将删除我们提供的所有对象。

String objkeyArr[] = {
  "document/hello.txt", 
  "document/pic.png"
};

DeleteObjectsRequest delObjReq = new DeleteObjectsRequest("baeldung-bucket")
  .withKeys(objkeyArr);
s3client.deleteObjects(delObjReq);

7. Conclusion

7.结论

In this article, we focused on the basics of interacting with the Amazon S3 web service, both at the bucket and object level.

在这篇文章中，我们着重介绍了与亚马逊S3网络服务互动的基础知识，包括在桶和对象层面。

As always, the full implementation of this article can be found over on Github.

一如既往，本文的完整实现可以在Github上找到over。