«1. Введение

В этом руководстве мы научимся программно взаимодействовать с системой хранения Amazon S3 (Simple Storage Service) с помощью Java.

Помните, что S3 имеет очень простую структуру — в каждой корзине может храниться любое количество объектов, доступ к которым можно получить с помощью интерфейса SOAP или API в стиле REST.

В дальнейшем мы будем использовать AWS SDK для Java для создания, перечисления и удаления сегментов S3. Мы также будем загружать, перечислять, скачивать, копировать, перемещать, переименовывать и удалять объекты в этих корзинах.

2. Зависимости Maven

Прежде чем мы начнем, нам нужно объявить зависимость AWS SDK в нашем проекте: 

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

Чтобы просмотреть последнюю версию, проверьте Maven Central.

3. Предварительные условия

Для использования AWS SDK нам потребуется несколько вещей:

  1. AWS Account: we need an Amazon Web Services account. If you still don’t have any, 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 access keys section of Security Credentials page or by using IAM user credentials from IAM console
  3. Choosing AWS Region: We have to select an 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. For this tutorial, we’ll use US East (Ohio) (region us-east-2)

4. Создание клиентского подключения

Во-первых, нам нужно создать клиентское подключение для доступа к веб-сервису Amazon S3. Для этого воспользуемся интерфейсом AmazonS3: 

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

А затем настроим клиент: 

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

5. Операции с корзиной Amazon S3

5.1. Создание корзины

Важно отметить, что пространство имен корзины совместно используется всеми пользователями системы. Поэтому имя нашей корзины должно быть уникальным среди всех существующих имен корзин в Amazon S3 (мы скоро узнаем, как это проверить).

Кроме того, как указано в официальной документации, имена Bucket должны соответствовать следующим требованиям:

    имена не должны содержать символы подчеркивания имена должны быть от 3 до 63 символов длинные имена не должны заканчиваться тире имена не могут содержать смежные имена периодов не могут содержать тире рядом с точками (например, «my-.bucket.com» и «my.-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);

Здесь мы используем s3client, созданный на предыдущем шаге. Прежде чем создавать корзину, мы проверяем, доступно ли имя нашей корзины, используя метод doBucketExist(). Если это имя доступно, мы будем использовать метод createBucket().

5.2. Список сегментов

Теперь, когда мы создали несколько сегментов, давайте распечатаем список всех сегментов, доступных в нашей среде S3, используя метод listBuckets(). Этот метод вернет список всех сегментов: 

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

Это список всех сегментов, присутствующих в нашей среде S3: 

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

5.3. Удаление ведра

Важно убедиться, что наше ведро пусто, прежде чем мы сможем его удалить. В противном случае будет выброшено исключение. Также обратите внимание, что только владелец корзины может удалить ее независимо от его разрешений (политик управления доступом): 

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

6. Операции с объектами Amazon S3

Файл или набор данных внутри корзины Amazon S3 известен как объект. Мы можем выполнять несколько операций с объектами, таких как загрузка, перечисление, загрузка, копирование, перемещение, переименование и удаление.

6.1. Загрузка объектов

Загрузка объекта — довольно простой процесс. Мы будем использовать метод putObject(), который принимает три параметра:

  1. bucketName: The bucket name where we want to upload 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. Список объектов

Мы будем использовать метод listObjects() для вывода списка всех доступных объектов в нашей корзине S3: 

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

Вызов метода listObjects() объекта s3client даст объект ObjectListing, который можно использовать для получить список всех сводок объектов в указанном сегменте. Здесь мы просто печатаем ключ, но есть также пара других доступных параметров, таких как размер, владелец, последнее изменение, класс хранения и т. д.

Теперь будет напечатан список всех объектов внутри нашего сегмента. : 

Document/hello.txt

6.3. Загрузка объекта

Чтобы загрузить объект, мы сначала воспользуемся методом getObject() на s3client, который вернет объект S3Object. Как только мы получим это, мы вызовем getObjectContent() для этого, чтобы получить объект S3ObjectInputStream, который ведет себя как обычный Java InputStream. 

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

Здесь мы используем метод FileUtils.copyInputStreamToFile() от Apache Commons. Вы также можете посетить эту статью Baeldung, чтобы изучить другие способы преобразования InputStream в файл.

6.4. Копирование, переименование и перемещение объекта

«Мы можем скопировать объект, вызвав метод copyObject() в нашем s3client, который принимает четыре параметра:

  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"
);

Примечание. Мы можем использовать комбинацию метода copyObject() и deleteObject() для выполнения задач перемещения и переименования. Это потребует сначала скопировать объект, а затем удалить его из старого местоположения.

6.5. Удаление объекта

Чтобы удалить объект, мы вызовем метод deleteObject() на s3client и передадим имя корзины и ключ объекта: 

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

6.6. Удаление нескольких объектов

Чтобы удалить сразу несколько объектов, мы сначала создадим объект DeleteObjectsRequest и передадим имя корзины в его конструктор. Затем мы передадим массив всех ключей объектов, которые мы хотим удалить.

Получив этот объект DeleteObjectsRequest, мы можем передать его методу deleteObjects() нашего s3client в качестве аргумента. В случае успеха будут удалены все предоставленные нами объекты: 

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

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

7. Заключение

В этой статье мы сосредоточились на основах взаимодействия с веб-сервисом Amazon S3 — как в корзине и уровень объекта.

Как всегда, полную реализацию этого руководства можно найти на Github.