Связаться с намиПодключиться

Загрузка объекта

Статья создана
Улучшена
Обновлена 26 ноября 2025 г.

Пользователь может создавать внутри бакета папки и загружать туда объекты. При этом необходимо помнить, что в SDK и HTTP API ключом объекта будет весь путь к объекту от корня бакета. Читайте подробнее в разделе Объект.

Примечание

Через консоль управления нельзя загрузить объекты размером более 5 ГБ (см. Квоты и лимиты в Object Storage). Также при загрузке через консоль нельзя указать content-type и другие заголовки. Для загрузки больших объектов или указания заголовков объекта используйте другие инструменты.

Для загрузки объектов в бакет вы можете использовать инструменты, поддерживающие работу с Object Storage, а также подписанные URL-ссылки.

Простая загрузка

Чтобы работать с объектами в зашифрованном бакете, у пользователя или сервисного аккаунта вместе с ролью storage.configurer должны быть следующие роли на ключ шифрования:

  • kms.keys.encrypter — для чтения ключа, шифрования и загрузки объектов;
  • kms.keys.decrypter — для чтения ключа, расшифровки и скачивания объектов;
  • kms.keys.encrypterDecrypter — включает разрешения, предоставляемые ролями kms.keys.encrypter и kms.keys.decrypter.

Подробнее см. Сервисные роли Key Management Service.

  1. В консоли управления выберите каталог.
  2. Перейдите в сервис Object Storage.
  3. Выберите бакет, в который нужно загрузить объект.
  4. На панели слева выберите Объекты.
  5. Если вы хотите загрузить объект в бакет впервые, нажмите Загрузить объекты.
  6. Если вы хотите загрузить объект в конкретную папку, перейдите в нее, нажав на имя. Если вам нужно создать новую папку, нажмите Создать папку.
  7. Оказавшись в нужной папке, на верхней панели нажмите Загрузить.
  8. В появившемся окне выберите необходимые файлы и нажмите Открыть.
  9. Консоль управления отобразит все объекты, выбранные для загрузки и предложит для каждого из них выбрать класс хранилища. Класс хранилища по умолчанию определяется настройкой бакета.
  10. Нажмите Загрузить.
  11. Обновите страницу.

В консоли управления информация о количестве объектов в бакете и занятом месте обновляется с задержкой в несколько минут.

Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

По умолчанию используется каталог, указанный при создании профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду yc config set folder-id <идентификатор_каталога>. Также для любой команды вы можете указать другой каталог с помощью параметров --folder-name или --folder-id.

  1. Посмотрите описание команды CLI для загрузки файла в бакет:

    yc storage s3api put-object --help

  2. Получите список бакетов в каталоге по умолчанию:

    yc storage bucket list

    Результат:

    +------------------+----------------------+-------------+-----------------------+---------------------+
|       NAME       |      FOLDER ID       |  MAX SIZE   | DEFAULT STORAGE CLASS |     CREATED AT      |
+------------------+----------------------+-------------+-----------------------+---------------------+
| first-bucket     | b1gmit33ngp6******** | 53687091200 | STANDARD              | 2022-12-16 13:58:18 |
+------------------+----------------------+-------------+-----------------------+---------------------+

  3. Выполните команду:

    yc storage s3api put-object \
  --body <путь_к_локальному_файлу> \
  --bucket <имя_бакета> \
  --key <путь_к_объекту>

    Где:

    • --body — путь к файлу, который нужно загрузить в бакет.
    • --bucket — имя вашего бакета.
    • --key — ключ, по которому объект будет храниться в бакете.

    Результат:

    etag: '"d41d8cd98f00b204e980099********"'
request_id: 3f2705f********

    Альтернативная команда:

    yc storage s3 cp \
  <путь_к_локальному_файлу> \
  s3://<имя_бакета>/<путь_к_объекту>

    Результат:

    upload: object.txt to s3://my-bucket/object.txt
    Настройка параметров для команды yc storage s3 cp

    Вы можете настроить следующие параметры для команды yc storage s3 cp:

    • s3.max-queue-size — максимальное количество задач в очереди. Значение по умолчанию — 1000.
    • s3.max-concurrent-requests — максимальное количество одновременных запросов. Значение по умолчанию — 10.
    • s3.multipart-threshold — пороговый размер объекта, при превышении которого будет использоваться составная (multipart) загрузка. Значение по умолчанию — 8MB.
    • s3.multipart-chunksize — размер частей, на которые будет делиться объект при составной (multipart) загрузке. Значение по умолчанию — 8MB.

    Чтобы задать эти параметры, используйте команду yc config set <параметр> <значение>.

  1. Если у вас еще нет AWS CLI, установите и сконфигурируйте его.

  2. Чтобы загрузить один объект, выполните команду:

    aws --endpoint-url=https://storage.yandexcloud.kz/ \
  s3 cp <путь_к_локальному_файлу> s3://<имя_бакета>/<ключ_объекта>

    Где:

    • --endpoint-url — эндпоинт Object Storage.
    • s3 cp — команда для загрузки объекта. Чтобы загрузить объект, в первой части команды укажите путь к локальному файлу, который нужно загрузить, а во второй — имя вашего бакета и ключ, по которому объект будет храниться в бакете.

    Чтобы загрузить все объекты из локальной директории, используйте команду:

    aws --endpoint-url=https://storage.yandexcloud.kz/ \
  s3 cp --recursive <путь_к_локальной_директории>/ s3://<имя_бакета>/<префикс>/

    Где:

    • --endpoint-url — эндпоинт Object Storage.
    • s3 cp --recursive — команда для загрузки всех объектов из локальной директории, включая вложенные. Чтобы загрузить объекты, в первой части команды укажите путь к папке, из которой нужно скопировать файлы в бакет, а во второй — имя вашего бакета и идентификатор папки в хранилище.

Команда aws s3 cp — высокоуровневая, ее функциональность ограничена. Подробнее см. в справочнике AWS CLI. Все возможности загрузки, которые поддерживаются в Object Storage, можно использовать при выполнении команды aws s3api put-object (см. ниже примеры работы с блокировками).

Примечание

Terraform взаимодействует с Object Storage от имени сервисного аккаунта. Назначьте сервисному аккаунту нужную роль, например storage.admin, на каталог, в котором будут создаваться ресурсы.

Terraform позволяет быстро создать облачную инфраструктуру в Yandex Cloud и управлять ею с помощью файлов конфигураций. В файлах конфигураций хранится описание инфраструктуры на языке HCL (HashiCorp Configuration Language). При изменении файлов конфигураций Terraform автоматически определяет, какая часть вашей конфигурации уже развернута, что следует добавить или удалить.

Terraform распространяется под лицензией Business Source License, а провайдер Yandex Cloud для Terraform — под лицензией MPL-2.0.

Подробную информацию о ресурсах провайдера смотрите в документации на сайте Terraform или в зеркале.

Если у вас еще нет Terraform, установите его и настройте провайдер Yandex Cloud.

Перед началом работы получите статические ключи доступа — секретный ключ и идентификатор ключа, используемые для аутентификации в Object Storage.

Примечание

Кроме статических ключей доступа для аутентификации в Object Storage можно использовать IAM-токен. Подробнее смотрите в разделе Создание бакета и в документации провайдера.

Чтобы создать объект в существующем бакете:

  1. Опишите в конфигурационном файле параметры ресурсов, которые необходимо создать.

    # Создание сервисного аккаунта

resource "yandex_iam_service_account" "sa" {
  name = "<имя_сервисного_аккаунта>"
}

# Назначение роли сервисному аккаунту

resource "yandex_resourcemanager_folder_iam_member" "sa-admin" {
  folder_id = "<идентификатор_каталога>"
  role      = "storage.admin"
  member    = "serviceAccount:${yandex_iam_service_account.sa.id}"
}

# Создание статического ключа доступа

resource "yandex_iam_service_account_static_access_key" "sa-static-key" {
  service_account_id = yandex_iam_service_account.sa.id
  description        = "static access key for object storage"
}

# Создание объекта

resource "yandex_storage_object" "test-object" {
  access_key = yandex_iam_service_account_static_access_key.sa-static-key.access_key
  secret_key = yandex_iam_service_account_static_access_key.sa-static-key.secret_key
  bucket     = "<имя_бакета>"
  key        = "<имя_объекта>"
  source     = "<путь_к_файлу>"
}

    Где:

    • access_key — идентификатор статического ключа доступа.

    • secret_key — значение секретного ключа доступа.

    • bucket — имя бакета для добавления объекта. Обязательный параметр.

    • key — имя объекта в бакете. Обязательный параметр. Формат имени:

      • длина — от 2 до 63 символов;
      • может содержать строчные буквы латинского алфавита, цифры и дефисы;
      • первый символ — буква, последний — не дефис.

    • source — относительный или абсолютный путь к файлу, который нужно загрузить в бакет.

    Более подробную информацию о ресурсах, которые вы можете создать с помощью Terraform, см. в документации провайдера.

Загрузка версии объекта с блокировкой (object lock)

Если в бакете включены версионирование и блокировки версий объектов, вы можете указать настройки блокировки (запрета на удаление или перезапись) при загрузке версии объекта.

  1. В консоли управления выберите каталог.
  2. Перейдите в сервис Object Storage.
  3. Выберите бакет, в который нужно загрузить объект.
  4. На панели слева выберите Объекты.
  5. Если вы хотите загрузить объект в бакет впервые, нажмите Загрузить объекты.
  6. Если вы хотите загрузить объект в конкретную папку, перейдите в нее, нажав на имя. Если хотите создать новую папку, создайте ее, нажав на панели сверху Создать папку.
  7. Оказавшись в нужной папке, нажмите на верхней панели Загрузить.
  8. В появившемся окне выберите необходимые файлы и нажмите Открыть.
  9. Консоль управления отобразит все объекты, выбранные для загрузки и предложит для каждого из них выбрать класс хранилища. Класс хранилища по умолчанию определяется настройкой бакета.
  10. Чтобы настроить блокировку загружаемых объектов, в выпадающем списке Блокировка версии объекта выберите вид блокировки:
    • Бессрочная блокировка — блокировка бессрочно запрещает удаление или перезапись версии объекта, но при этом не запрещает загружать новые версии объекта. Пользователь с ролью storage.uploader может установить и снять блокировку. Обойти блокировку нельзя. В сочетании с временной блокировкой имеет приоритет.
    • Временная блокировка — блокировка запрещает удаление или перезапись версии объекта на определенный срок, но при этом не запрещает загружать новые версии объекта. Пользователь с ролью storage.uploader может установить блокировку. В сочетании с бессрочной блокировкой не имеет приоритета.
  11. Если вы выбрали вид Временная блокировка, укажите Тип блокировки по умолчанию:
    • Временная управляемая (governance) — пользователь с ролью storage.admin может обойти блокировку, изменить ее срок или снять ее.
    • Временная строгая (compliance) — пользователь с ролью storage.admin может только продлить блокировку. Обойти, сократить или снять блокировку до ее окончания нельзя.
  12. Установите Срок блокировки по умолчанию в днях или годах. Отсчитывается от момента, когда версия объекта загружена в бакет.
  13. Нажмите Загрузить и обновите страницу.

В консоли управления информация о количестве объектов в бакете и занятом месте обновляется с задержкой в несколько минут.

Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

По умолчанию используется каталог, указанный при создании профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду yc config set folder-id <идентификатор_каталога>. Также для любой команды вы можете указать другой каталог с помощью параметров --folder-name или --folder-id.

  1. Посмотрите описание команды CLI для загрузки файла в бакет:

    yc storage s3api put-object --help

  2. Получите список бакетов в каталоге по умолчанию:

    yc storage bucket list

    Результат:

    +------------------+----------------------+-------------+-----------------------+---------------------+
|       NAME       |      FOLDER ID       |  MAX SIZE   | DEFAULT STORAGE CLASS |     CREATED AT      |
+------------------+----------------------+-------------+-----------------------+---------------------+
| first-bucket     | b1gmit33ngp6******** | 53687091200 | STANDARD              | 2022-12-16 13:58:18 |
+------------------+----------------------+-------------+-----------------------+---------------------+

  3. Выполните команду:

    yc storage s3api put-object \
 --body <путь_к_локальному_файлу> \
 --bucket <имя_бакета> \
 --key <ключ_объекта> \
 --object-lock-mode <тип_временной_блокировки> \
 --object-lock-retain-until-date <дата_и_время_окончания_временной_блокировки> \
 --object-lock-legal-hold-status <статус_бессрочной_блокировки>

    Где:

    • --body — путь к файлу, который нужно загрузить в бакет.

    • --bucket — имя вашего бакета.

    • --key — ключ, по которому объект будет храниться в бакете.

    • --object-lock-mode — тип временной блокировки:

      • GOVERNANCE — временная управляемая блокировка.
      • COMPLIANCE — временная строгая блокировка.

    • --object-lock-retain-until-date — дата и время окончания временной блокировки в любом из форматов, описанных в стандарте HTTP. Например, 2025-01-02T15:04:05Z. Указывается только вместе с параметром --object-lock-mode.

    • --object-lock-legal-hold-status — статус бессрочной блокировки:

      • ON — блокировка установлена.
      • OFF — блокировка не установлена.

    Вы можете установить на версию объекта только временную блокировку (параметры object-lock-mode и object-lock-retain-until-date), только бессрочную блокировку (object-lock-legal-hold-status) или обе сразу. Подробнее об их совместной работе см. в разделе Типы блокировок.

    Результат:

    etag: '"d41d8cd98f00b204e9800998********"'
request_id: e19afe50********
version_id: 0006241E********

  1. Если у вас еще нет AWS CLI, установите и сконфигурируйте его.

  2. Выполните команду:

    aws --endpoint-url=https://storage.yandexcloud.kz/ \
  s3api put-object \
  --body <путь_к_локальному_файлу> \
  --bucket <имя_бакета> \
  --key <ключ_объекта> \
  --object-lock-mode <тип_временной_блокировки> \
  --object-lock-retain-until-date <дата_и_время_окончания_временной_блокировки> \
  --object-lock-legal-hold-status <статус_бессрочной_блокировки>

    Где:

    • --endpoint-url — эндпоинт Object Storage.
    • s3api put-object — команда для загрузки версии объекта. Чтобы загрузить версии объекта с блокировкой, укажите следующие параметры:

      • --body — путь к файлу, который нужно загрузить в бакет.

      • --bucket — имя вашего бакета.

      • --key — ключ, по которому объект будет храниться в бакете.

      • --object-lock-mode — тип временной блокировки:

        • GOVERNANCE — временная управляемая блокировка.
        • COMPLIANCE — временная строгая блокировка.

      • --object-lock-retain-until-date — дата и время окончания временной блокировки в любом из форматов, описанных в стандарте HTTP. Например, Mon, 12 Dec 2022 09:00:00 GMT. Указывается только вместе с параметром --object-lock-mode.

      • --object-lock-legal-hold-status — статус бессрочной блокировки:

        • ON — блокировка установлена.
        • OFF — блокировка не установлена.

    Вы можете установить на версию объекта только временную блокировку (параметры object-lock-mode и object-lock-retain-until-date), только бессрочную блокировку (object-lock-legal-hold-status) или обе сразу. Подробнее об их совместной работе см. в разделе Типы блокировок.

Чтобы загрузить версию объекта с блокировкой, воспользуйтесь методом S3 API upload с заголовками X-Amz-Object-Lock-Mode и X-Amz-Object-Lock-Retain-Until-Date для временной блокировки и X-Amz-Object-Lock-Legal-Hold для бессрочной.

Если для бакета также настроены временные блокировки по умолчанию, все объекты в него нужно загружать с указанием их MD5-хешей:

Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

По умолчанию используется каталог, указанный при создании профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду yc config set folder-id <идентификатор_каталога>. Также для любой команды вы можете указать другой каталог с помощью параметров --folder-name или --folder-id.

  1. Вычислите MD5-хэш файла и закодируйте его по схеме Base64:

    md5=($(md5sum <путь_к_локальному_файлу>))
md5_base64=$(echo $md5 | base64)

  2. Посмотрите описание команды CLI для загрузки файла в бакет:

    yc storage s3api put-object --help

  3. Получите список бакетов в каталоге по умолчанию:

    yc storage bucket list

    Результат:

    +------------------+----------------------+-------------+-----------------------+---------------------+
|       NAME       |      FOLDER ID       |  MAX SIZE   | DEFAULT STORAGE CLASS |     CREATED AT      |
+------------------+----------------------+-------------+-----------------------+---------------------+
| first-bucket     | b1gmit33ngp6******** | 53687091200 | STANDARD              | 2022-12-16 13:58:18 |
+------------------+----------------------+-------------+-----------------------+---------------------+

  4. Загрузите объект в бакет:

     yc storage s3api put-object \
  --body <путь_к_локальному_файлу> \
  --bucket <имя_бакета> \
  --key <ключ_объекта> \
  --content-md5 $md5_base64

    Где:

    • --body — путь к файлу, который нужно загрузить в бакет.
    • --bucket — имя вашего бакета.
    • --key — ключ, по которому объект будет храниться в бакете.
    • --content-md5 — закодированный MD5-хеш объекта.

    Также вы можете добавить к команде параметры:

    • --object-lock-mode и --object-lock-retain-until-date, чтобы установить на версию объекта временную блокировку, отличную от настроек бакета по умолчанию;
    • --object-lock-legal-hold-status, чтобы установить на версию объекта бессрочную блокировку.

    Подробнее об этих параметрах см. в инструкции выше.

  1. Вычислите MD5-хэш файла и закодируйте его по схеме Base64:

    md5=($(md5sum <путь_к_локальному_файлу>))
md5_base64=$(echo $md5 | base64)

  2. Если у вас еще нет AWS CLI, установите и сконфигурируйте его.

  3. Загрузите объект в бакет:

    aws --endpoint-url=https://storage.yandexcloud.kz/ \
  s3api put-object \
  --body <путь_к_локальному_файлу> \
  --bucket <имя_бакета> \
  --key <ключ_объекта> \
  --content-md5 $md5_base64

    Где:

    • --endpoint-url — эндпоинт Object Storage.
    • s3api put-object — команда для загрузки версии объекта. Чтобы загрузить версии объекта, укажите следующие параметры:
      • --body — путь к файлу, который нужно загрузить в бакет.
      • --bucket — имя вашего бакета.
      • --key — ключ, по которому объект будет храниться в бакете.
      • --content-md5 — закодированный MD5-хеш объекта.

    Также вы можете добавить к команде параметры:

    • --object-lock-mode и --object-lock-retain-until-date, чтобы установить на версию объекта временную блокировку, отличную от настроек бакета по умолчанию;
    • --object-lock-legal-hold-status, чтобы установить на версию объекта бессрочную блокировку.

    Подробнее об этих параметрах см. в инструкции выше.

Чтобы загрузить версию объекта с временной блокировкой по умолчанию, воспользуйтесь методом S3 API upload с заголовком Content-MD5.

Условная загрузка объекта (conditional writes)

Вы можете использовать условия при загрузке объекта, а также при завершении составной загрузки.

Загрузка объекта с условием по ETag

  1. Если у вас еще нет AWS CLI, установите и сконфигурируйте его.

  2. Чтобы загрузить объект только при существовании объекта с определенным ETag, выполните команду:

    aws s3api put-object \
    --endpoint-url https://storage.yandexcloud.kz \
    --body <путь_к_локальному_файлу> \
    --bucket <имя_бакета> \
    --key <путь_к_объекту> \
    --if-match "<ETag_объекта>"

    Где:

    • --endpoint-url — эндпоинт Object Storage.
    • --body — путь к файлу, который нужно загрузить в бакет. Например: ./my-folder/my-file.txt.
    • --bucket — имя вашего бакета.
    • --key — ключ, по которому объект будет храниться в бакете. Например: my-folder/my-file.txt.
    • --if-match — текущий ETag объекта, например \"d41d8cd98f00b204e9800998********\". Запись выполнится, только если по указанному ключу уже существует объект и его текущий ETag совпадает.

Чтобы загрузить объект только при существовании объекта с определенным ETag, воспользуйтесь методом S3 API upload с заголовком --if-match.

Загрузка объекта с условием отсутствия

  1. Если у вас еще нет AWS CLI, установите и сконфигурируйте его.

  2. Чтобы загрузить объект только при отсутствии в бакете объекта с определенным ключом, выполните команду:

    aws s3api put-object \
    --endpoint-url https://storage.yandexcloud.kz \
    --body <путь_к_локальному_файлу> \
    --bucket <имя_бакета> \
    --key <путь_к_объекту> \
    --if-none-match "*"

    Где:

    • --endpoint-url — эндпоинт Object Storage.
    • --body — путь к файлу, который нужно загрузить в бакет. Например: ./my-folder/my-file.txt.
    • --bucket — имя вашего бакета.
    • --key — ключ, по которому объект будет храниться в бакете. Например: my-folder/my-file.txt.
    • --if-none-match — укажите "*", чтобы запись выполнилась, только если по указанному ключу еще нет объекта.

Чтобы загрузить объект только при отсутствии в бакете объекта с определенным ключом, воспользуйтесь методом S3 API upload с заголовком --if-none-match.

См. также

Предыдущая
Просмотр метрик бакета
Следующая
Составная загрузка объекта