Перейти к основному содержимому

S3 API

Начало работы

S3 API — API на базе Amazon S3 API, предназначенный для работы с ресурсами объектного хранилища. С помощью S3 API можно:

  • просматривать информацию о количестве и объеме контейнеров и объектов в рамках аккаунта;
  • создавать и удалять контейнеры;
  • загружать, просматривать, копировать, перемещать, скачивать и удалять объекты в контейнерах;
  • управлять сегментированной загрузкой объектов;
  • управлять CORS и т.д.

Доступ к API

К S3 API возможен только авторизованный доступ.

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

Адрес (URL) при использовании Path-Style адресации (по умолчанию) можно посмотреть в списке URL.

Если включена Virtual Hosted адресация, вы можете обращаться к контейнеру по адресу <container_name>.<url>.

Аутентификация

Аутентификация в S3 API происходит с помощью подписи запросов. Мы поддерживаем подписи версий AWS Signature Version 4 и AWS Signature Version 2.

Для формирования подписи потребуются ключи доступа, которые можно получить при выдаче S3-ключа пользователю:

  • Access Key ID — значение поля Access key из S3-ключа;
  • Secret Access Key — значение поля Secret key из S3-ключа.

Подписать запрос можно одним из методов:

Срок жизни подписи запроса — 15 минут.

Совместимость

S3 API совместим со следующими возможностями Amazon S3 API:

Метод Совместимость
Bucket CRUD
Bucket Acl
Bucket CORS
Bucket Encryption
Поддерживается Client-side encryption (AWS SDK)
Bucket Lifecycle
Bucket Location
Bucket Logging
Bucket Metrics Configuration
Bucket Notification
Bucket Ownership Controls
Bucket Policy
Bucket Replication
Bucket Request Payment
Bucket Tagging
Bucket Versioning
Bucket Website
Object CRUD
Object Copy
Object Acl
Работает Get ACL
Object Content
Object Lock Configuration
Object Response
Object Retention
Object Tagging
Object Torrent
Object Versions
Multipart Upload
Public Access Block
Все запросы по умолчанию являются Private

AWS SDK

Python

Boto

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

  1. Установите boto, подробнее в документации boto3.

  2. В домашнем каталоге создайте конфигурационный файл ~/.aws/credentials:

    [default]
       aws_access_key_id = <access_key>
       aws_secret_access_key = <secret_key>
    

    Укажите:

    • <access_key> — значение поля Access key из S3-ключа;
    • <secret_key — значение поля Secret key из S3-ключа.
  3. В домашнем каталоге создайте конфигурационный файл ~/.aws/config:

    [default]
        region=ru-1
    

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

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

# Авторизация
s3 = boto3.client(
   service_name='s3',
   endpoint_url='https://s3.ru-1.storage.selcloud.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})

Пример для boto3

Создайте s3-клиент, предоставив endpoint_url, пул и S3-ключ (EC2-ключ), выданный пользователю:

s3 = boto3.client("s3", endpoint_url="https://s3.storage.selcloud.ru", region_name="ru-1", aws_access_key_id="access_key", aws_secret_access_key="secret_key")

Вызовите метод generate_presigned_post(), передав имя бакета, в который будет производиться загрузка, и имя ключа, которое может содержать шаблон ${filename} для имени файла, предоставленного пользователем в момент загрузки. Данный вызов вернёт словарь с URL, на которую должна отправляться форма, и словарём fields со всеми необходимыми заполненными полями для этой формы (X-Amz-Algorithm, X-Amz-Credential, X-Amz-Date, X-Amz-Signature, Policy).

post = s3.generate_presigned_post(bucket, key)

Если к объекту (и форме) необходимо добавить дополнительные поля, например, заголовок Content-Type, то передайте словарь с этими полями аргументом Fields. Также, согласно спецификации Policy, нужно описать каждое дополнительное поле в массиве conditions (аргумент Conditions в boto).

post = s3.generate_presigned_post(bucket, key,
                                  Fields={"Content-Type": "image/webp"},
                                  Conditions=[["eq", "$content-type", "image/webp"]])

Из полученных данных можно составить HTML-форму или воспроизвести запрос через requests:

requests.post(post["url"], data=post["fields"], files=[("file", ("filename", b"body_data"))])

При генерации HTML-формы стоит учитывать, что поле file с данными загружаемого файла должно находиться в конце формы.

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 в свой скрипт. Для авторизации необходимы значения Access Key и Secret Key из S3-ключа.

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

<?php
require "vendor/autoload.php";

use Aws\S3\S3Client;
// Создание клиента
$s3Client = new S3Client([
   "version" 	=> "latest",
   "region"  	=> "ru-1",
   "use_path_style_endpoint" => true,
   "credentials" => [
       "key"	=> "<access_key>",
       "secret" => "<secret_key>",
   ],
   "endpoint" => "https://s3.storage.selcloud.ru"
]);

// Загрузка объекта из строки
$s3Client->putObject([
   "Bucket" => "BucketName",
   "Key"	=> "ObjectName",
   "Body"   => "Test"
]);

// Скачивание объекта
$result = $s3Client->getObject([
   "Bucket" => "BucketName",
   "Key"	=> "ObjectName"
]);

echo $result["Body"];

Укажите:

  • <access_key> — значение поля Access key из S3-ключа;
  • <secret_key — значение поля Secret key из S3-ключа.

JavaScript

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

Пример работы для Node.js

var S3 = require("aws-sdk/clients/s3");

var s3 = new S3({
    credentials: {
      accessKeyId: "<access_key>",
      secretAccessKey: "<secret_key>"
    },
    endpoint: "https://s3.storage.selcloud.ru",
    s3ForcePathStyle: true,
    region: "ru-1",
    apiVersion: "latest"
});

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

var params = {
    Bucket: "BucketName",
    Key: "ObjectName",
    Body: "Test"
};

s3.upload(params, (err, data) => {
    if (err) {
        console.log(err, err.stack);
    } else {
        console.log(data);
    }
    /*
    data = {
        ETag: "0cbc6611f5540bd0809a388dc95a615b",
        Location: "https://s3.storage.selcloud.ru/BucketName/ObjectName",
        key: "ObjectName",
        Key: "ObjectName",
        Bucket: "BucketName"
    }
    */

});

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

var params = {
    Bucket: "BucketName",
    Key: "ObjectName"
};

s3.headObject(params, (err, data) => {
    if (err) {
        console.log(err, err.stack);
    } else {
        console.log(data);
    }
    /*
    data = {
        AcceptRanges: "bytes",
        LastModified: 2019-12-03T17:29:15.000Z,
        ContentLength: 4,
        ETag: "0cbc6611f5540bd0809a388dc95a615b",
        ContentType: "application/octet-stream",
        Metadata: {}
    }
    */
});

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

var params = {
    Bucket: "BucketName",
    Key: "ObjectName"
};

s3.getObject(params, (err, data) => {
    if (err) {
        console.log(err, err.stack);
    } else {
        console.log(data);
    }
    /*
    data = {
        AcceptRanges: "bytes",
        LastModified: 2019-12-03T17:29:15.000Z,
        ContentLength: 4,
        ETag: "0cbc6611f5540bd0809a388dc95a615b",
        ContentType: "application/octet-stream",
        Metadata: {},
        Body: <Buffer 54 65 73 74>
    }
    */
});


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

var params = {
    Bucket: "BucketName",
    Key: "ObjectName"
};

s3.deleteObject(params, (err, data) => {
    if (err) {
        console.log(err, err.stack);
    } else {
        console.log(data);
    }
    /*
    data = {
    }
    */
});

Укажите:

  • <access_key> — значение поля Access key из S3-ключа;
  • <secret_key — значение поля Secret key из S3-ключа.

Java

// Configure S3 client connection
AWSCredentials credentials = new BasicAWSCredentials(
        "<access_key>",
        "<secret_key>"
);

EndpointConfiguration endpoint =
        new EndpointConfiguration("https://s3.storage.selcloud.ru", "ru-1");

AmazonS3 s3client = AmazonS3ClientBuilder
        .standard()
        .withCredentials(new AWSStaticCredentialsProvider(credentials))
        .withPathStyleAccessEnabled(true)
        .withEndpointConfiguration(endpoint)
        .build();

// Create bucket
String bucketName = "s3bucket";
String objectName = "s3object";

if(!s3client.doesBucketExistV2(bucketName)) {
        s3client.createBucket(bucketName);
}

// Upload object
s3client.putObject(
        bucketName,
        objectName,
        "sample-data"
);

// Download object
S3Object s3object = s3client.getObject(bucketName, objectName);
S3ObjectInputStream inputStream = s3object.getObjectContent();

inputStream.transferTo(new FileOutputStream("downloaded-object"));

// Delete object
s3client.deleteObject(bucketName, objectName);

// Delete bucket
s3client.deleteBucket(bucketName);

Укажите:

  • <access_key> — значение поля Access key из S3-ключа;
  • <secret_key — значение поля Secret key из S3-ключа.