База знаний

Список статей
Наверх

Работа с S3 API Облачного хранилища

Создание пользователя и настройка доступа

Для работы с S3 в Облачном хранилище в панели управления:

  1. Создайте отдельного пользователя. 

  2. Назначьте созданному пользователю права на работу с нужными контейнерами согласно инструкции. Для того чтобы дать пользователю полный доступ к необходимому контейнеру выберите значение Чтение и запись.

  3. Сохраните пароль, проставив галочку Хранить пароль на серверах Selectel.

Примечание: если пользователь не сохранил свой пароль в панели управления – аутентификация работать не будет, так как для проверки подписи запроса сервис должен знать пароль.

Для работы в конфигурационном файле используйте логин и пароль созданного пользователя:

  • в качестве Access Key используется формат <Номер аккаунта>_<Имя пользователя> ;

  • в качестве Secret Key используется пароль пользователя;

  • в качестве Region используется ru-1a .

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

Бакет (bucket) - это логическая сущность, которая помогает организовать хранение объектов. В терминологии Swift это контейнеры. 

Имя бакета является частью URL - https://s3.selcdn.ru/bucket/.

Работа с объектами хранилища

Для работы с объектами в Облачном хранилище используйте s3-совместимые клиенты.

Rclone

Конфигурация

Примечание: пример конфигурации может отличаться от версии к версии, в данном примере использовалась версия 2.0.1.

Для настройки rclone для работы с облачным хранилищем Selectel введите:

rclone config

На консоли появится диалог:

No remotes found - make a new one
n) New remote
[...]
n/r/c/s/q>

Выберите n и нажмите клавишу Enter

Укажите имя подключения к удаленному хранилищу (подходит любое имя, например, selectel-s3): 

name> selectel-s3

Выберите тип хранилища:

Type of storage to configure.

Choose a number from below, or type in your own value

[...]

4 / Amazon S3 Compliant Storage Provider (AWS, Alibaba, Ceph, Digital Ocean, Dreamhost, IBM COS, Minio, etc)

  \ "s3"

[...]

Укажите s3:

Storage> s3

Выберите поставщика услуг:

Choose your S3 provider.

Enter a string value. Press Enter for the default ("").

Choose a number from below, or type in your own value

[...]

10 / Any other S3 compatible provider

   \ "Other"

Укажите Other:

provider> Other

Выберите тип ввода учетных данных (вручную или из переменных окружения):

Get AWS credentials from runtime (environment variables or EC2/ECS meta data if no env vars).

Only applies if access_key_id and secret_access_key is blank.

Enter a boolean value (true or false). Press Enter for the default ("false").

Choose a number from below, or type in your own value

 1 / Enter AWS credentials in the next step
   \ "false"

 2 / Get AWS credentials from the environment (env vars or IAM)

   \ "true"

Для ввода данных вручную укажите false:

env_auth> false

Система запросит access key (логин).

AWS Access Key ID.

Leave blank for anonymous access or runtime credentials.

Enter a string value. Press Enter for the default ("").

Введите логин в формате НомерАккаунта_ИмяПользователя:

access_key_id> НомерАккаунта_ИмяПользователя

Система запросит secret key (пароль). Пароль можно посмотреть в панели управления. 

AWS Secret Access Key (password)

Leave blank for anonymous access or runtime credentials.

Enter a string value. Press Enter for the default ("").

Введите пароль пользователя:

secret_access_key> пароль

Система запросит ввести регион:

Region to connect to.

Leave blank if you are using an S3 clone and you don't have a region.

Enter a string value. Press Enter for the default ("").

Choose a number from below, or type in your own value

[...]

Введите регион ru-1a :

region> ru-1a

Выберите эндпоинт:

Endpoint for S3 API.

Required when using an S3 clone.

Enter a string value. Press Enter for the default ("").

Choose a number from below, or type in your own value

Введите https://s3.selcdn.ru:

endpoint> https://s3.selcdn.ru

Укажите регион создания бакета:

Location constraint - must be set to match the Region.

Leave blank if not sure. Used when creating buckets only.

Enter a string value. Press Enter for the default ("").


location_constraint>

Оставьте поле пустым и нажмите Enter.

Установите права доступа ACL:

Canned ACL used when creating buckets and/or storing objects in S3.

For more info visit https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl

Choose a number from below, or type in your own value

 1 / Owner gets FULL_CONTROL. No one else has access rights (default).

   \ "private"
[...]

Выберите private:

acl> private

После этого можно отказаться от расширенной конфигурации:

Edit advanced config? (y/n)

y) Yes

n) No

Введите n:

y/n> n

Сверьте данные:

--------------------
[selectel-s3]
type = s3
provider = Other
env_auth = false
access_key_id = НомерАккаунта_ИмяПользователя
secret_access_key = Пароль
region = ru-1a
endpoint = https://s3.selcdn.ru
acl = private
--------------------
y) Yes this is OK

e) Edit this remote

d) Delete this remote

Сохраните созданный профиль, введите y:

y/e/d> y

Синтаксис команд для работы с хранилищем

Подробнее обо всех командах можно прочитать в официальной документации.

Краткую справку можно получить с помощью команды:

rclone --help
Просмотр списка бакетов
rclone lsd selectel-s3:
Создание нового бакета
rclone mkdir selectel-s3:ИмяБакета
Просмотр списка файлов 
rclone ls selectel-s3:ИмяБакета
Копирование файлов с локальной машины в хранилище
rclone copy /home/local/directory selectel-s3:ИмяБакета
Синхронизация файлов на локальной машине и в хранилище
rclone sync /home/local/directory selectel-s3:ИмяБакета
Синхронизация файлов в хранилище с файлами на локальной машине
rclone sync selectel-s3:ИмяБакета /home/local/directory

При выполнении операций копирования и синхронизации rclone проверяет все файлы по дате и времени изменения, а также по md5-сумме. Из исходного контейнера в назначенный контейнер передаются те файлы, которые были изменены.

AWS CLI

AWS CLI (AWS Command Line Interface) — это интерфейс командной строки для работы с сервисами AWS. Общий порядок вызова команд смотрите в официальной документации Amazon. Для установки AWS CLI воспользуйтесь инструкцией.

Для работы с Облачным хранилищем с помощью AWS CLI можно использовать следующие наборы команд:

  • s3api — команды, соответствующие операциям в REST API;

  • s3 — дополнительные команды, упрощающие работу с большим количеством объектов.

Для настройки AWS CLI используйте команду aws configure. Команда запросит значения для следующих параметров:

  • AWS Access Key ID — введите логин в формате НомерАккаунта_ИмяПользователя

  • AWS Secret Access Key — введите пароль 

  • Default region name — введите значение ru-1a 

Команда aws configure в результате работы сохраняет настройки в конфигурационных файлах:

  • Учетные данные в .aws/credentials:

[default]
   aws_access_key_id = НомерАккаунта_ИмяПользователя
   aws_secret_access_key = Пароль
  • Регион по умолчанию в .aws/config:

[default]
   region = ru-1a

При запуске команды aws для работы с Облачным хранилищем обязателен параметр --endpoint-url=https://s3.selcdn.ru, поскольку по умолчанию клиент настроен на работу с AWS.

Синтаксис команд для работы с хранилищем

Создание бакета
aws --endpoint-url=https://s3.selcdn.ru s3 mb s3://ИмяБакета
Загрузка объекта
aws --endpoint-url=https://s3.selcdn.ru s3 cp ПутьКОбъекту s3://ИмяБакета/
Скачивание объекта
aws --endpoint-url=https://s3.selcdn.ru s3 cp s3://ИмяБакета/ПутьКФайлу Файл
Получение списка объектов
aws --endpoint-url=https://s3.selcdn.ru s3 ls --recursive s3://ИмяБакета
Удаление объекта
aws --endpoint-url=https://s3.selcdn.ru s3 rm s3://ИмяБакета/ПутьКФайлу/Файл

S3cmd

S3cmd — это интерфейс командной строки для работы с сервисами, поддерживающими HTTP API Amazon S3. Общий порядок вызова команд смотрите в официальной документации S3cmd.

Для установки S3cmd воспользуйтесь инструкцией в репозитории проекта.

Для настройки S3cmd используйте команду s3cmd --configure. Команда запросит значения для следующих параметров:

  • Access KeyНомерАккаунта_ИмяПользователя

  • Secret KeyПароль

  • Default Regionru-1a

  • S3 Endpoints3.selcdn.ru

  • DNS-style bucket+hostname:port template for accessing a bucket — s3.selcdn.ru

  • Значения остальных параметров оставьте без изменений

Программа попытается установить соединение с Облачным хранилищем и получить список бакетов. В случае успеха на экран будет выведено Success

Команда s3cmd --configure сохранит настройки в файле ~/.s3cfg в формате:

[default]
   access_key = НомерАккаунта_ИмяПользователя
   secret_key = Пароль
   bucket_location = ru-1a
   host_base = s3.selcdn.ru
   host_bucket = s3.selcdn.ru

При необходимости эти настройки можно изменить напрямую в файле. Также можно указать настройки при запуске программы с помощью соответствующих параметров.

Синтаксис команд для работы с хранилищем

Создание бакета
s3cmd mb s3://ИмяБакета
Загрузка объекта
s3cmd put local_file s3://ИмяБакета/ПутьКФайлу
Получение списка объектов
s3cmd ls s3://ИмяБакета
Скачивание объекта
s3cmd get s3://ИмяБакета/ПутьКФайлу Файл
Удаление объекта
s3cmd rm s3://ИмяБакета/ПутьКФайлу

Boto 

boto3 — это комплекты средств разработки (SDK) для языков программирования Python 3.x. SDK предназначены для работы с сервисами AWS. 

Для установки boto воспользуйтесь инструкциями в соответствующих репозиториях boto3.

Для настройки создайте в домашнем каталоге конфигурационные файлы и задайте параметры:

  • Статический ключ в файле ~/.aws/credentials:

    [default]
       aws_access_key_id = НомерАккаунта_ИмяПользователя
       aws_secret_access_key = Пароль
  • Регион по умолчанию в файле ~/.aws/config:

     [default]
        region=ru-1a

Примеры операций

#!/usr/bin/env python
#-*- coding: utf-8 -*-
import boto3

# Авторизация
s3 = boto3.client(
   service_name='s3',
   endpoint_url='https://s3.selcdn.ru'
)

# Загрузка объекта из строки
s3.put_object(Bucket='BucketName', Key='ObjectName1', Body='Test')

# Загрузка объекта из файла
s3.upload_file('data.docx', 'BucketName', 'ObjectName2')

# Получение списка объектов в бакете
for key in s3.list_objects(Bucket='BucketName')['Contents']:
   print(key['Key'])

# Скачивание объекта
get_object_response = s3.get_object(Bucket='BucketName', Key='ObjectName2')
print(get_object_response['Body'].read())

# Удаление нескольких объектов
objects_to_delete = [{'Key': 'ObjectName1'}, {'Key': 'ObjectName2'}]
s3.delete_objects(Bucket='BucketName', Delete={'Objects': objects_to_delete})

AWS SDK PHP

AWS SDK для PHP — это комплект средств разработки для работы с сервисами AWS.

SDK представляет собой современную библиотеку PHP с открытым исходным кодом, которая упрощает интеграцию приложения на PHP с объектным хранилищем S3.

Для подключения библиотеки с помощью инструмента управления зависимостями Composer выполните следующие шаги:

  1. Установите Composer:

    curl -sS https://getcomposer.org/installer | php
  2. Запустите команду Composer для установки последней стабильной версии SDK:

    php composer.phar require aws/aws-sdk-php
  3. Включите aws-sdk-php в свой скрипт.

    <?php require '/path/to/vendor/autoload.php';

Для авторизации необходимы ключи доступа Access key ID (НомерАккаунта_ИмяПользователя) и Secret access key (Пароль). 

Примеры операций

<?php
require 'vendor/autoload.php';
 
use Aws\S3\S3Client;
// Создание клиента
$s3Client = new S3Client([
   'version' 	=> 'latest',
   'region'  	=> 'ru-1a',
   'credentials' => [
   	'key'	=> 'НомерАккаунта_ИмяПользователя',
   	'secret' => 'Пароль',
   ],
   'endpoint' => 'https://s3.selcdn.ru'
]);
 
// Загрузка объекта из строки
$s3Client->putObject([
   'Bucket' => 'BucketName',
   'Key'	=> 'ObjectName',
   'Body'   => 'Test'
]);
 
// Скачивание объекта
$result = $s3Client->getObject([
   'Bucket' => 'BucketName',
   'Key'	=> 'ObjectName'
]);
 
echo $result['Body'];

Составная загрузка (Multipart Upload)

Особенность при загрузке объектов.

Составная загрузка позволяет загружать отдельный объект как набор частей.

Примечание: при работе с S3 при Multipart-загрузке больших объектов все загруженные сегменты не собираются в финале в единый объект, а складируются в соседний контейнер с таким же именем и суффиксом _s3multipartuploads.

Для загрузки больших (размер варьируется) объектов по частям используют этот API.

Загрузка выполняется в три этапа: 

Инициализация

  1. Если объект уже существует, то он удаляется.

  2. Создается контейнер с именем текущего, к нему добавляется суффикс _s3multipartuploads. Далее там будут храниться сегменты загруженного объекта.

  3. Генерируется uploadId.

  4. В контейнере с сегментами создаётся мета-объект /uploads/<bucketName>_s3multipartuploads/<objectName>_<uploadId>/, который будет хранить Content-Type и все пользовательские метаданные до финализации.

Загрузка частей (сегментов)

Происходит загрузка сегментов.

Финализация

  1. Делается листинг всех объектов по префиксу <bucketName>_s3multipartuploads/<objectName>/<uploadId>/ и сравнивается с листингом, который пришел от клиента.

  2. Считается суммарный размер объекта и суммируются хэши.

  3. Создаётся манифест, который будет находиться по пути загружаемого multipart-объекта.

  4. Из созданного ранее мета-объекта считывается Content-Type и пользовательские метаданные и записываются в манифест, а сам мета-объект затем удаляется.

Реализован данный метод с небольшим ограничением – в качестве разделителя можно использовать только "/".

Примечание: в бакетах видны контейнеры с сегментами.

Поддерживаемые методы

Облачное хранилище поддерживает базовые методы для работы с HTTP API Amazon S3. 

Метод

Команда

Действие

Доступ

GET Service

GET /

Получение списка бакетов

Пользователь получает листинг только тех бакетов, к которым у него есть доступ на чтение и запись

DELETE Bucket

DELETE /<bucketName>

Удаление бакета

Пользователь может удалить бакет, если он имеет доступ на чтение и запись

GET Bucket (List Objects) Version 1

GET /<bucketName>

Получение списка объектов в бакете

Пользователь может получить листинг объектов только того бакета, к которому он имеет доступ на чтение и запись

HEAD Bucket

HEAD /<bucketName>

Получение статуса бакета

Пользователь может получить статус бакета, если у него есть доступ на чтение и запись

List Multipart Uploads

GET /<bucketName>?uploads

Получение списка загружаемых multipart-объектов

Пользователь может получить листинг загружаемых multipart-объектов только того бакета, к которому он имеет доступ на чтение и запись

PUT Bucket

PUT /<bucketName>

Создание бакета

Пользователь может создать бакет, если он имеет доступ на чтение и запись

Delete Multiple Objects

POST /<bucketName>?delete

Множественное удаление объектов в бакете

Пользователь может удалить несколько объектов, если он имеет доступ на чтение и запись в бакет

DELETE Object

DELETE /<bucketName>/<objectName>

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

Пользователь может удалить объект, если он имеет доступ на чтение и запись в бакет

GET Object

GET /<bucketName>/<objectName>

Получение объекта

Пользователь может получить объект, если он имеет доступ на чтение и запись

HEAD Object

HEAD /<bucketName>/<objectName>

Получение метаданных объекта

Пользователь может получить метаданные объекта, если он имеет доступ на чтение и запись

PUT Object

PUT /<bucketName>/<objectName>

Создание объекта

Пользователь может создать объект, если он имеет доступ на чтение и запись

PUT Object - Copy

PUT /<bucketName>/<objectName> (x-amz-copy-source)

Копирование объекта. При копировании объекта самого в себя выполняется модификация метаданных объекта

Пользователь может скопировать объект, если он имеет доступ на чтение и запись в бакет-источник

Initiate Multipart Upload

POST /<bucketName>/<objectName>?uploads

Инициирование загрузки multipart-объекта

Пользователь может инициировать multipart upload, если он имеет доступ на чтение и запись

Complete Multipart Upload

POST /<bucketName>/<objectName>?uploadId=<uploadId>

Финализация загрузки multipart-объекта

Пользователь может финализировать multipart upload, если он имеет доступ на чтение и запись

Abort Multipart Upload

DELETE /<bucketName>/<objectName>?uploadId=<uploadId>

Отмена загрузки multipart-объекта

Примечание: удаляется каждый загруженный сегмент, затем и мета-объект

Пользователь может отменить загрузку multipart-объекта, если он имеет доступ на чтение и запись

List Parts

GET /<bucketName>/<objectName>?uploadId=<uploadId>

Получение списка сегментов multipart-объекта

Пользователь может получить список сегментов, если он имеет доступ на чтение и запись

Upload Part

PUT /<bucketName>/<objectName>?partNumber=<partNumber>&uploadId=<uploadId>

Загрузка части multipart-объекта

Примечание: в этом методе к имени бакета добавляется суффикс _s3multipartuploads, а путь к объекту заменяется на <objectName>/<uploadId>/<partNumber>

Пользователь может создать часть multipart-объекта, если он имеет доступ на чтение и запись

Upload Part - Copy

PUT /<bucketName>/<objectName>?partNumber=<part_number>&uploadId=<uploadId> (x-amz-copy-source)

Копирование части multipart-объекта

Пользователь может скопировать часть multipart-объекта, если он имеет доступ на чтение и запись в бакет-источник