Перейти к основному содержимому
API docs by Redocly

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-ключа.