Алексей Клюев

Хранение файлов в S3 выглядит просто: добавляете объект в бакет по ключу и потом при необходимости удаляете или обновляете его. Но в реальной работе можно загрузить файл с помощью операции PutObject, не проверив, что в бакете уже лежит файл с этим ключом. В результате новое содержимое незаметно заменит старое. Или можно случайно удалить только что добавленный свежий бэкап вместо старого, что нарушает рабочий процесс. Чтобы избежать подобных ситуаций, в S3 есть условные операции записи (conditional write) — это когда действия вроде PutObject, CopyObject, DeleteObject или CompleteMultipartUpload выполняются только при соблюдении заданных условий. Часть работы в панели управления Selectel В целом, здесь нам нужно просто создать и настроить бакет S3. Очень подробный пошаговый гайд вы найдете в статье моего коллеги. Я же перечислю только основные шаги. 1. Перейдите в панель управления → S3 и нажмите Создать бакет. 2. Выберите тип адресации vHosted. Что касается типа контейнера, то для работы с чувствительными данными подойдет приватный, а если планируете реализовать доступ к контенту без авторизации, выберите публичный. 3. Создайте сервисного пользователя с ролью «object_storage:admin» и доступом в нужный проект. 4. Создайте S3-ключ в панели управления. 5. Сохраните Access Key и Secret Key. Будьте внимательны: ключи не хранятся в наших системах и показываются только один раз. Etag Каждый объект, загруженный в S3, получает ETag — строку, которая в большинстве случаев является хэшем (MD5) содержимого объекта. Она служит своеобразным «отпечатком» данных и позволяет проверять, не изменился ли объект с момента последнего обращения. Рассмотрим простой пример: загрузим объект и посмотрим его ETag: Инициализация S3-клиента Чтобы работать с S3 из Go, сначала нужно инициализировать клиента. Для этого мы будем использовать SDK от Amazon aws-sdk-go-v2. Ниже приведен пример вспомогательной функции NewS3Client, которую мы будем использовать в последующих примерах. Для инициализации SDK загружает настройки из стандартных файлов конфигурации (~/.aws/config и ~/.aws/credentials), проверяет регион и валидность учетных данных: PutObject Первая операция, с которой чаще всего сталкиваются при работе с S3, — PutObject. Важно понимать, что в S3 невозможно изменить содержимое существующего объекта. Любая запись — это фактически загрузка новой версии объекта под тем же ключом. И здесь легко столкнуться с неожиданной перезаписью данных. Чтобы этого избежать, S3 поддерживает использование условных заголовков. Для PutObject это прежде всего два параметра: If-None-Match — разрешает загрузку объекта, только если по указанному ключу объекта еще нет. В противном случае операция завершится ошибкой 412 Precondition Failed. If-Match — разрешает загрузку объекта, только если ETag существующего объекта совпадает с переданным значением. Если объект изменился (ETag другой), загрузка не произойдет, и вы снова получите 412 Precondition Failed. Пример с If-None-Match Попробуем загрузить объект в бакет, разрешив это только в случае, если по ключу test.txt его еще нет: Результат при двух последовательных запусках: # Первый запуск Объект успешно загружен: "5d41402abc4b2a76b9719d911017c592" Process finished with the exit code 0 # Второй запуск 2025/09/29 22:04:50 operation error S3: PutObject, https response error StatusCode: 412, RequestID: 1bfd1ad9-d0cb-4211-8e23-a90f59f1cf93, HostID: , api error PreconditionFailed: At least one of the preconditions you specified did not hold. Process finished with the exit code 1 Пример с If-Match Теперь используем If-Match, чтобы обновить объект, только если он не изменился с момента последнего чтения. Для этого мы передаем известный ETag: Успешный результат при совпадении ETag: Объект успешно загружен: "df0649bc4f1be901c85b6183091c1d83" (body"hello 1") Process finished with the exit code 0 Если же указать неверный Etag, мы получим ошибку 412 Precondition Failed: 2025/09/29 22:15:28 operation error S3: PutObject, https response error StatusCode: 412, RequestID: fd08857c-9c61-4aa1-bebe-52e32a71e97e, HostID: , api error PreconditionFailed: At least one of the preconditions you specified did not hold. Process finished with the exit code 1 CopyObject Операция CopyObject используется, когда нужно скопировать файл внутри одного бакета или между разными бакетами. При этом, как и с PutObject, можно столкнуться с ситуацией, когда данные были изменены другими процессами, и копирование приведет к неожиданному результату. Условные заголовки позволяют выполнять копирование только при соблюдении определенных условий: CopySourceIfMatch — скопировать объект, только если его ETag совпадает с указанным. CopySourceIfNoneMatch — наоборот, скопировать, только если ETag не совпадает. CopySourceIfModifiedSince — копировать объект, только если он был изменен после указанной даты. CopySourceIfUnmodifiedSince — копировать, только если объект не изменялся с определенной даты. Пример с CopySourceIfMatch Допустим, в бакете уже есть объект test.txt. Мы хотим создать его копию под именем test-copy.txt, но только если содержимое исходного файла не менялось. Для этого используем CopySourceIfMatch с актуальным ETag: Успешное выполнение: Объект успешно скопирован: "df0649bc4f1be901c85b6183091c1d83" (body"hello 1") Process finished with the exit code 0 Если же указать неверный ETag, операция завершится ошибкой: 2025/09/29 22:25:07 operation error S3: CopyObject, https response error StatusCode: 412, RequestID: 73b833f3-e1c3-4e27-b873-a0bbdc854970, HostID: , api error PreconditionFailed: Precondition Failed DeleteObject Удаление объекта в S3 — одна из самых чувствительных операций, ведь потерянные данные восстановить уже не получится (если, конечно, не включены версии или другие механизмы защиты). Чтобы снизить риск случайного удаления актуального файла, в DeleteObject доступен условный заголовок: If-Match - операция выполнится только в том случае, если текущий ETag объекта совпадает с указанным. Таким образом можно гарантировать, что вы удаляете именно ту версию объекта, которую ожидали, а не уже обновленную кем-то другим. Пример с If-Match Удалим объект test-copy.tx, сначала указав неверный ETag, а затем корректный: Если ETag неверный, получим уже знакомую ошибку: 2025/09/29 22:25:07 operation error S3: CopyObject, https response error StatusCode: 412, RequestID: 73b833f3-e1c3-4e27-b873-a0bbdc854970, HostID: , api error PreconditionFailed: Precondition Failed При использовании правильного ETag объект удаляется успешно: Объект успешно удален: test-copy.txt Process finished with the exit code 0 CompleteMultipart Последняя операция, которую рассмотрим, — CompleteMultipartUpload. Она завершает процесс загрузки больших файлов, которые разбиваются на части и отправляются в несколько запросов. После вызова этой операции части объединяются в один объект. Как и в случае с PutObject и DeleteObject, здесь есть риск перезаписать существующий объект, если по ключу уже что-то лежит. Как вы, наверное, догадались, этот риск устраняется с помощью условных заголовков: If-Match — завершить загрузку, только если текущий объект совпадает по ETag с указанным. If-None-Match — завершить загрузку, только если по этому ключу еще нет объекта. Таким образом, даже при работе с многокомпонентной загрузкой мы можем контролировать целостность и избежать неожиданных коллизий. Пример с If-Match В примере ниже создадим объект test-multipart.txt из трех частей и завершим загрузку с условием If-None-Match. Это позволит успешно загрузить объект в первый раз, но не даст перезаписать его во второй: Результаты запуска: # Первый запуск Объект успешно загружен: test-multipart.txt (etag"78a31f6c0a4aef8ab2b9713cb9bd6c64-3") Process finished with the exit code 0 # Второй запуск operation error S3: CompleteMultipartUpload, https response error StatusCode: 412, ... api error PreconditionFailed: At least one of the preconditions you specified did not hold. Таким образом, даже при работе с MultipartUpload можно защитить данные от нежелательной перезаписи. Условные заголовки делают процесс более предсказуемым и позволяют писать надежный код, особенно в системах, где одновременно работают несколько клиентов. Заключение В статье я показал базовые примеры на Go с использованием aws-sdk-go-v2. На практике же условные заголовки поддерживаются всеми основными инструментами и клиентами для S3 — будь то aws cli, s3cmd, Rclone или файловые драйверы вроде s3fs. Это значит, что вы можете применять подходы conditional write не только в коде, но и в ежедневной работе с хранилищем. Если у вас есть опыт использования условных операций или идеи по улучшению автоматизации работы с S3, делитесь ими в комментариях.Кстати, уже в этом месяце мы откроем шестой пул S3-хранилища — ru-3 в регионе Санкт-Петербург (группа ЦОД «Цветочная»). Новый пул расширит географию размещения данных и позволит повысить отказоустойчивость и гибкость инфраструктуры. Следите за обновлениями — скоро мы расскажем подробнее.

Алексей Клюев

Материалы автора

Как избежать перезаписи в S3 с помощью условных заголовков