1. Главная
  2. О компании
  3. Документация
  4. Взаимодействие с S3 через API

Взаимодействие с S3 через API

В инструкции будут рассмотрены примеры по взаимодействию с S3 через API с помощью ПО Bruno и Postman.

1. Создайте Environment

Создание набора переменных в Bruno или Postman.

Переменные Environment

  • s3_endpoint: https://s3.example.local — Адрес RGW без / в конце.

  • s3_access_key: ACCESS_KEY — S3 Access Key.

  • s3_secret_key: SECRET_KEY — S3 Secret Key.

  • s3_region: default или ru-central1 — Region вашего S3/RGW стенда.

  • s3_service: s3 — Имя сервиса для AWS Signature V4.

  • bucket: api-test-bucket-001 — имя bucket.

2. Настройка Bruno

  1. Создайте Collection.

  2. Откройте Environments → Create и создайте environment.

  3. Добавьте в Environment все переменные из предыдущего раздела.

  4. Выберите ваш созданый ранее Environment как активный.

  5. Откройте настройки авторизации Collection и выберите AWS Sig V4.

    Консоль
    1.2.3.4.
    Access Key ID: {{s3_access_key}} Secret Access Key: {{s3_secret_key}} Service Name: {{s3_service}} AWS Region: {{s3_region}}
    Совет
    для запросов внутри Collection используйте наследование авторизации, чтобы не дублировать ключи в каждом запросе.

  6. Создайте запрос проверки подключения.

    Консоль
    1.
    GET {{s3_endpoint}}

  7. Нажмите Send.

При корректных endpoint и подписи RGW возвращает HTTP 200 и XML со списком bucket текущего пользователя.

3. Настройка Postman

  1. Откройте Environments → Create Environment и создайте.

  2. Добавьте в Environment все переменные из предыдущего раздела.

  3. Выберите ваш созданый ранее Environment как активный.

  4. Создайте Collection.

  5. Откройте Authorization коллекции и выберите Auth Type = AWS Signature.

    Консоль
    1.2.3.4.
    AccessKey: {{s3_access_key}} SecretKey: {{s3_secret_key}} AWS Region: {{s3_region}} Service Name: {{s3_service}}

  6. Во всех запросах внутри Collection выберите Inherit auth from parent.

  7. Создайте запрос проверки подключения.

    Консоль
    1.
    GET {{s3_endpoint}}

  8. Нажмите Send.

При корректных endpoint и подписи RGW возвращает HTTP 200 и XML со списком bucket текущего пользователя.

5. Выполните базовые S3-запросы

Важно
все запросы ниже выполняются с уже настроенной AWS Signature V4. В Bruno используйте авторизацию Collection, в Postman — Inherit auth from parent

5.1. Получить список bucket

Консоль
1.
GET {{s3_endpoint}}

Результат: HTTP 200. В ответе XML со списком bucket текущего пользователя.

5.2. Создать bucket

Консоль
1.
PUT {{s3_endpoint}}/{{bucket}}

Результат: Bucket {{bucket}} создан.

5.3. Получить список объектов

Консоль
1.
GET {{s3_endpoint}}/{{bucket}} 

Результат: HTTP 200. Для нового bucket список объектов пуст.

5.4. Загрузить объект

Консоль
1.
PUT {{s3_endpoint}}/{{bucket}}/{{object_key}}

Результат: Объект {{object_key}} появляется в bucket {{bucket}}.

5.5. Получить объект

Консоль
1.
GET {{s3_endpoint}}/{{bucket}}/{{object_key}}

Результат: HTTP 200. В body ответа содержимое загруженного объекта.

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

Консоль
1.
HEAD {{s3_endpoint}}/{{bucket}}/{{object_key}}

Результат: HTTP 200. Тело ответа отсутствует; метаданные доступны в response headers.

5.7. Скопировать объект

Консоль
1.
PUT {{s3_endpoint}}/{{bucket}}/{{copy_object_key}}

Результат: В bucket появляется {{copy_object_key}}. Body не требуется.

5.8. Удалить копию объекта

Консоль
1.
DELETE {{s3_endpoint}}/{{bucket}}/{{copy_object_key}}

Результат: Объект {{copy_object_key}} удалён.

5.9. Удалить основной объект

Консоль
1.
DELETE {{s3_endpoint}}/{{bucket}}/{{object_key}}

Результат: Объект {{object_key}} удалён.

5.10. Удалить bucket

Консоль
1.
DELETE {{s3_endpoint}}/{{bucket}}

Результат: HTTP 204 No Content. Bucket удалён.

Важно
перед DELETE bucket удалите из него все объекты. Непустой bucket удалить нельзя.

8. Если запрос не работает

403 AccessDenied

Проверьте права пользователя на bucket/object, ACL и policy.

403 SignatureDoesNotMatch

Проверьте Access Key, Secret Key, region, endpoint и системное время. После исправления повторите GET {{s3_endpoint}}.

404 NoSuchBucket

Проверьте значение {{bucket}} и активный environment.

404 NoSuchKey

Проверьте {{object_key}} и выполните List Objects.

409 BucketAlreadyExists

Измените значение {{bucket}} на уникальное имя.

409 BucketNotEmpty

Удалите объекты из bucket и повторите DELETE.