S3
Если вы используете настройки S3, установленные до обновления хранилища 29.09.2023, обновите их до 15.09.2026, подробнее в инструкции Настроить S3 после обновления.
После 15.09.2026 старые настройки (пользователи, URL и другие) перестанут работать.
Начало работы
S3 API — API на базе Amazon S3 API, предназначенный для работы с ресурсами S3. С помощью S3 API можно:
- просматривать информацию о количестве и объеме бакетов и объектов в рамках аккаунта;
- создавать и удалять бакеты;
- загружать, просматривать, копировать, перемещать, скачивать и удалять объекты в бакетах;
- управлять сегментированной загрузкой объектов;
- управлять CORS и т.д.
Доступ к API
К S3 API возможен только авторизованный доступ.
Для доступа к бакету через S3 API у пользователя должна быть роль с доступом к S3, подробнее в инструкции Управлять доступом в S3.
Адрес (URL) при использовании Path-Style адресации (по умолчанию) можно посмотреть в списке URL.
Если включена Virtual Hosted адресация, вы можете обращаться к бакету по адресу <bucket_name>.<s3_domain>.
Аутентификация
Аутентификация в S3 API происходит с помощью подписи запросов. Мы поддерживаем подписи версий AWS Signature Version 4 и AWS Signature Version 2.
Для формирования подписи потребуются ключи доступа, которые можно получить при выдаче S3-ключа пользователю:
- Access Key ID — значение поля Access key из S3-ключа;
- Secret Access Key — значение поля Secret key из S3-ключа.
Подписать запрос можно одним из методов:
- через HTTP-заголовок Authorization, подробнее в инструкции Authenticating Requests: Using the Authorization Header (AWS Signature Version 4) документации Amazon;
- используя query-параметры или подписанный URL (Presigned URL). При таком методе можно указать все параметры запроса в URL, подробнее в инструкции Authenticating Requests: Using Query Parameters (AWS Signature Version 4) документации Amazon.
Срок жизни подписи запроса — 15 минут.
Совместимость
S3 API совместим со следующими возможностями Amazon S3 API:
AWS SDK
Python
Boto
boto3 — это комплекты средств разработки (SDK) для языков программирования Python 3.x. SDK предназначены для работы с сервисами AWS.
- Установите boto, подробнее в документации boto3.
- В домашнем каталоге создайте конфигурационный файл
~/.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-ключа.
- В домашнем каталоге создайте конфигурационный файл
~/.aws/config:
[default]
region=<pool>
Примеры операций
#!/usr/bin/env python
#-*- coding: utf-8 -*-
import boto3
# Authorization
s3 = boto3.client(
service_name='s3',
endpoint_url='<url>'
)
# Upload object from string
s3.put_object(Bucket="BucketName", Key="ObjectName1", Body="Test")
# Upload object from file
s3.upload_file("data.docx", "BucketName", "ObjectName2")
# Get list of objects in the bucket
for key in s3.list_objects(Bucket="BucketName")["Contents"]:
print(key["Key"])
# Download object
get_object_response = s3.get_object(Bucket="BucketName", Key="ObjectName2")
print(get_object_response["Body"].read())
# Delete multiple objects
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="<url>", region_name="<pool>", 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 S3.
Для подключения библиотеки с помощью инструмента управления зависимостями Composer выполните следующие шаги:
- Установите Composer:
curl -sS 'https://getcomposer.org/installer' | php
- Запустите команду Composer для установки последней стабильной версии SDK:
php composer.phar require aws/aws-sdk-php
- Включите aws-sdk-php в свой скрипт. Для авторизации необходимы значения Access Key и Secret Key из S3-ключа.
Примеры операций
<?php
require "vendor/autoload.php";
use Aws\S3\S3Client;
// Create client
$s3Client = new S3Client([
"version" => "latest",
"region" => "<pool>",
"use_path_style_endpoint" => true,
"credentials" => [
"key" => "<access_key>",
"secret" => "<secret_key>",
],
"endpoint" => "<url>"
]);
// Upload object
$s3Client->putObject([
"Bucket" => "BucketName",
"Key" => "ObjectName",
"Body" => "Test"
]);
// Download object
$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
import {
S3Client,
PutObjectCommand,
CreateBucketCommand,
DeleteObjectCommand,
DeleteBucketCommand,
paginateListObjectsV2,
GetObjectCommand,
} from "@aws-sdk/client-s3";
import { createInterface } from "node:readline/promises";
export async function main() {
const s3 = new S3Client({
region: "<region>",
endpoint: "<endpoint>",
apiVersion: "latest",
credentials: {
accessKeyId: "<access-key>",
secretAccessKey: "<secret-key>",
},
});
const bucketName = `test-bucket-${Date.now()}`;
const fileName = "test-file.txt";
//Create S3 bucket
await s3.send(
new CreateBucketCommand({
Bucket: bucketName,
})
);
//Put an object into an S3 bucket.
await s3.send(
new PutObjectCommand({
Bucket: bucketName,
Key: fileName,
Body: "Hello JavaScript SDK!",
})
);
//Get object
const { Body } = await s3.send(
new GetObjectCommand({
Bucket: bucketName,
Key: fileName,
})
);
console.log(await Body.transformToString());
}
// Confirm resource deletion.
const prompt = createInterface({
input: process.stdin,
output: process.stdout,
});
const result = await prompt.question("Empty and delete bucket? (y/n) ");
prompt.close();
if (result === "y") {
// Create an async iterator over lists of objects in a bucket.
const paginator = paginateListObjectsV2(
{ client: s3 },
{ Bucket: bucketName }
);
for await (const page of paginator) {
const objects = page.Contents;
if (objects) {
// For every object in each page, delete it.
for (const object of objects) {
await s3.send(
new DeleteObjectCommand({ Bucket: bucketName, Key: object.Key })
);
}
}
}
// Once all the objects are gone, the bucket can be deleted.
await s3.send(new DeleteBucketCommand({ Bucket: bucketName }));
}
main();
Укажите:
<access_key>— значение поля Access key из S3-ключа;<secret_key>— значение поля Secret key из S3-ключа;<url>домен S3 API, зависит от пула, в котором находится S3;<pool>— пул, в котором находится S3.
Java
// Configure S3 client connection
AWSCredentials credentials = new BasicAWSCredentials(
"<access_key>",
"<secret_key>"
);
EndpointConfiguration endpoint =
new EndpointConfiguration("<url>", "<pool>");
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-ключа.