---
title: 'S3'
description: 'Как осуществляется доступ к S3 API, как проходить аутентификацию, с какими возможностями Amazon S3 API совместим S3 API и как работать с AWS SDK'
---

import { CustomTable } from '@selectel/docux/components';

:::warning

Если вы используете настройки S3, установленные до обновления хранилища 29.09.2023, обновите их до 15.09.2026, подробнее в инструкции [Настроить S3 после обновления](/s3/manage/configure-storage-update/).

После 15.09.2026 старые настройки (пользователи, URL и другие) перестанут работать.

:::

## Начало работы \{#getting-started}

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

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

### Доступ к API \{#access-to-api}

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

Для доступа к бакету через S3 API у пользователя должна быть роль с доступом к S3, подробнее в инструкции [Управлять доступом к S3](/s3/about/manage-access/).

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

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

### Аутентификация \{#authentication}

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

Для формирования подписи потребуются ключи доступа, которые можно получить при [выдаче S3-ключа пользователю](/access-control/manage/edit-user-data-or-role/#issue-s3-key):

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

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

* через HTTP-заголовок Authorization, подробнее в инструкции [Authenticating Requests: Using the Authorization Header (AWS Signature Version 4)](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-auth-using-authorization-header.html) документации Amazon;
* используя query-параметры или подписанный URL (Presigned URL). При таком методе можно указать все параметры запроса в URL, подробнее в инструкции [Authenticating Requests: Using Query Parameters (AWS Signature Version 4)](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-query-string-auth.html) документации Amazon.

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

## Совместимость \{#compatibility}

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

<CustomTable>
  <table>
    <thead>
      <tr>
        <th>Метод</th>
        <th>Совместимость</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>Bucket CRUD</td>
        <td>✓</td>
      </tr>

      <tr>
        <td>Bucket Acl</td>
        <td>✗</td>
      </tr>

      <tr>
        <td>Bucket CORS</td>
        <td>✓</td>
      </tr>

      <tr>
        <td>Bucket Encryption</td>
        <td>✗<br />Поддерживается Client-side encryption (AWS SDK)</td>
      </tr>

      <tr>
        <td>Bucket Lifecycle</td>
        <td>✗</td>
      </tr>

      <tr>
        <td>Bucket Location</td>
        <td>✓</td>
      </tr>

      <tr>
        <td>Bucket Logging</td>
        <td>✗</td>
      </tr>

      <tr>
        <td>Bucket Metrics Configuration</td>
        <td>✗</td>
      </tr>

      <tr>
        <td>Bucket Notification</td>
        <td>✗</td>
      </tr>

      <tr>
        <td>Bucket Ownership Controls</td>
        <td>✗</td>
      </tr>

      <tr>
        <td>Bucket Policy</td>
        <td>✓</td>
      </tr>

      <tr>
        <td>Bucket Replication</td>
        <td>✗</td>
      </tr>

      <tr>
        <td>Bucket Request Payment</td>
        <td>✗</td>
      </tr>

      <tr>
        <td>Bucket Tagging</td>
        <td>✗</td>
      </tr>

      <tr>
        <td>Bucket Versioning</td>
        <td>✓</td>
      </tr>

      <tr>
        <td>Bucket Website</td>
        <td>✗</td>
      </tr>

      <tr>
        <td>Conditional Writes</td>
        <td>✓</td>
      </tr>

      <tr>
        <td>Object CRUD</td>
        <td>✓</td>
      </tr>

      <tr>
        <td>Object Copy</td>
        <td>✓</td>
      </tr>

      <tr>
        <td>Object Acl</td>
        <td>✗<br />Работает Get ACL</td>
      </tr>

      <tr>
        <td>Object Content</td>
        <td>✗</td>
      </tr>

      <tr>
        <td>Object Lock Configuration</td>
        <td>✓</td>
      </tr>

      <tr>
        <td>Object Response</td>
        <td>✗</td>
      </tr>

      <tr>
        <td>Object Retention</td>
        <td>✗</td>
      </tr>

      <tr>
        <td>Object Tagging</td>
        <td>✗</td>
      </tr>

      <tr>
        <td>Object Torrent</td>
        <td>✗</td>
      </tr>

      <tr>
        <td>Object Versions</td>
        <td>✓</td>
      </tr>

      <tr>
        <td>Multipart Upload</td>
        <td>✓</td>
      </tr>

      <tr>
        <td>Public Access Block</td>
        <td>✗<br />Все запросы по умолчанию являются Private</td>
      </tr>
    </tbody>
  </table>
</CustomTable>

## AWS SDK \{#aws-sdk}

### Python \{#python}

#### Boto \{#boto}

[boto3](https://github.com/boto/boto3) — это комплекты средств разработки (SDK) для языков программирования Python 3.x. SDK предназначены для работы с сервисами AWS.

1. Установите boto, подробнее в документации [boto3](https://github.com/boto/boto3/blob/develop/README.rst#quick-start).
2. В домашнем каталоге создайте конфигурационный файл `~/.aws/credentials`:

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

Укажите:

* `<access_key>` — значение поля **Access key** из [S3-ключа](/access-control/manage/edit-user-data-or-role/#issue-s3-key);
* `<secret_key` — значение поля **Secret key** из S3-ключа.

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

```
[default]
    region=<pool>
```

#### Примеры операций \{#boto-operations-examples}

```
#!/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 \{#boto-example}

Создайте s3-клиент, предоставив endpoint\_url, пул и S3-ключ (EC2-ключ), [выданный пользователю](/access-control/manage/edit-user-data-or-role/#issue-s3-key):

```
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](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-HTTPPOSTConstructPolicy.html), нужно описать каждое дополнительное поле в массиве `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 \{#php}

[AWS SDK для PHP](https://aws.amazon.com/ru/sdk-for-php/) — это комплект средств разработки для работы с сервисами AWS.

SDK представляет собой современную библиотеку PHP с открытым исходным кодом, которая упрощает интеграцию приложения на PHP с S3 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-ключа](/access-control/manage/edit-user-data-or-role/#issue-s3-key).

#### Примеры операций \{#php-operations-examples}

```
<?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-ключа](/access-control/manage/edit-user-data-or-role/#issue-s3-key);
* `<secret_key` — значение поля **Secret key** из S3-ключа.

### JavaScript \{#javascript}

[AWS SDK для Node.js](https://aws.amazon.com/ru/sdk-for-node-js/) — это комплект средств разработки для работы JavaScript с сервисами AWS в среде Node.js.

#### Пример работы для Node.js \{#javascript-node-js-example}

```
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-ключа](/access-control/manage/edit-user-data-or-role/#issue-s3-key);
* `<secret_key>` — значение поля **Secret key** из S3-ключа;
* `<url>` — [домен S3 API](/s3/manage/domains/#s3-api-domains), зависит от [пула](/infrastructure/locations/#pool), в котором находится S3;
* `<pool>` — [пул](/infrastructure/locations/#pool), в котором находится S3.

### Java \{#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-ключа](/access-control/manage/edit-user-data-or-role/#issue-s3-key);
* `<secret_key` — значение поля **Secret key** из S3-ключа.