Yandex Cloud
Поиск
Связаться с намиПодключиться
  • Истории успеха
  • Документация
  • Блог
  • Все сервисы
  • Статус работы сервисов
    • Доступны в регионе
    • Инфраструктура и сеть
    • Платформа данных
    • Контейнеры
    • Инструменты разработчика
    • Бессерверные вычисления
    • Безопасность
    • Мониторинг и управление ресурсами
    • ML Services
    • Бизнес-инструменты
  • Все решения
    • По отраслям
    • По типу задач
    • Экономика платформы
    • Безопасность
    • Техническая поддержка
    • Каталог партнёров
    • Обучение и сертификация
    • Облако для стартапов
    • Облако для крупного бизнеса
    • Центр технологий для общества
    • Партнёрская программа
    • Поддержка IT-бизнеса
    • Облако для фрилансеров
    • Обучение и сертификация
    • Блог
    • Документация
    • Мероприятия и вебинары
    • Контакты, чаты и сообщества
    • Идеи
    • Тарифы Yandex Cloud
    • Промоакции и free tier
    • Правила тарификации
  • Истории успеха
  • Документация
  • Блог
Проект Яндекса
© 2025 ТОО «Облачные Сервисы Казахстан»
Yandex Object Storage
  • Правила тарификации
  • Справочник Terraform
    • Аутентификация в API
      • Как пользоваться API
      • Подписывание запросов
      • Начало работы с S3 API
        • Все сервисы и методы
          • Все методы
          • upload
          • get
          • patch
          • copy
          • getObjectMeta
          • delete
          • deleteMultipleObjects
          • options
          • selectObjectContent
          • putObjectRetention
          • putObjectLegalHold
          • getObjectRetention
          • getObjectLegalHold
          • putObjectTagging
          • getObjectTagging
          • deleteObjectTagging
        • Общие заголовки запросов
        • Общие заголовки ответов
        • Ответы
  • Метрики Monitoring
  • Аудитные логи Audit Trails
  • Логи бакета
  • История изменений
  • Вопросы и ответы
  • Обучающие курсы

В этой статье:

  • Запрос
  • Path параметры
  • Заголовки
  • Ответ
  • Заголовки
  • Коды ответов
  1. Справочник API
  2. REST (совместимый с Amazon S3)
  3. REST
  4. Object
  5. upload

Метод upload

Статья создана
Yandex Cloud
Обновлена 19 сентября 2025 г.
  • Запрос
    • Path параметры
    • Заголовки
  • Ответ
    • Заголовки
    • Коды ответов

Загружает объект и его метаданные в Yandex Object Storage.

Примечание

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

Чтобы убедиться, что объект передан по сети без повреждений, используйте заголовок Content-MD5. Object Storage вычислит MD5 для сохраненного объекта и если вычисленная MD5 не совпадет с переданной в заголовке, вернет ошибку. Эту проверку можно выполнить и на стороне клиента, сравнив ETag из ответа Object Storage с предварительно вычисленной MD5.

Важно

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

Подробнее о подготовке к работе с API и общем виде запроса см. в разделе Как пользоваться S3 API.

ЗапросЗапрос

PUT /{bucket}/{key} HTTP/2

Path параметрыPath параметры

Параметр Описание
bucket Имя бакета.
key Ключ объекта. Идентификатор, под которым объект будет сохранен в Object Storage.

ЗаголовкиЗаголовки

Используйте в запросе необходимые общие заголовки.

Дополнительно можно использовать заголовки, перечисленные в таблице ниже.

Заголовок Описание
If-Match Определяет условие выполнения операции. Операция будет выполнена, только если текущая версия объекта по указанному ключу существует, и ее ETag совпадает со значением в заголовке If-Match.
If-None-Match Определяет условие выполнения операции. Операция будет выполнена, только если в бакете нет объекта с таким же ключом. В значении заголовка укажите *.
X-Amz-Meta-* Пользовательские метаданные объекта.

Все заголовки, начинающиеся с X-Amz-Meta-, Object Storage преобразует по правилу: X-Amz-Meta-foo-bar_baz → X-Amz-Meta-Foo-Bar_baz.

Общий размер пользовательских заголовков не должен превышать 2KB. Размер пользовательских данных определяется как длина строки в кодировке UTF-8. В размере учитываются и названия заголовков и их значения.
X-Amz-Storage-Class Класс хранилища объекта.

Может иметь любое из значений:
  • STANDARD — стандартное хранилище.
  • COLD, STANDARD_IA или NEARLINE — холодное хранилище.
  • ICE или GLACIER — ледяное хранилище.
Если заголовок не указан, то объект сохраняется в хранилище, установленном в настройках бакета.
X-Amz-Server-Side-Encryption Алгоритм шифрования загружаемого объекта. Доступные значения: aws:kms.
X-Amz-Server-Side-Encryption-Aws-Kms-Key-Id Идентификатор ключа KMS для шифрования загружаемого объекта.
X-Amz-Object-Lock-Mode

Тип временной блокировки, устанавливаемой на объект (если бакет версионируемый и в нем включен механизм блокировок):

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

Вы можете установить на версию объекта только временную блокировку (заголовки X-Amz-Object-Lock-Mode и X-Amz-Object-Lock-Retain-Until-Date), только бессрочную блокировку (X-Amz-Object-Lock-Legal-Hold) или обе сразу. Подробнее об их совместной работе см. в разделе Типы блокировок.

X-Amz-Object-Lock-Retain-Until-Date Дата и время окончания временной блокировки в любом из форматов, описанных в стандарте HTTP. Например, Mon, 12 Dec 2022 09:00:00 GMT. Указывается только вместе с заголовком X-Amz-Object-Lock-Mode.
X-Amz-Object-Lock-Legal-Hold

Статус бессрочной блокировки, устанавливаемой на объект (если бакет версионируемый и в нем включен механизм блокировок):

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

Вы можете установить на версию объекта только временную блокировку (заголовки X-Amz-Object-Lock-Mode и X-Amz-Object-Lock-Retain-Until-Date), только бессрочную блокировку (X-Amz-Object-Lock-Legal-Hold) или обе сразу. Подробнее об их совместной работе см. в разделе Типы блокировок.

С помощью заголовков, перечисленных ниже, можно установить ACL для загружаемого объекта.

Заголовок Описание
X-Amz-Acl Устанавливает предопределенный ACL для объекта.
X-Amz-Grant-Read Устанавливает получателю доступа разрешение на чтение объекта.
X-Amz-Grant-Read-Acp Устанавливает получателю доступа разрешение на чтение ACL объекта.
X-Amz-Grant-Write-Acp Устанавливает получателю доступа разрешение на запись ACL объекта.
X-Amz-Grant-Full-Control Устанавливает получателю доступа разрешения: READ, WRITE, READ_ACP, WRITE_ACP на объект.

Значение для заголовков X-Amz-Grant-* представляет собой разделенный запятыми список получателей доступа. Каждый получатель доступа идентифицируется структурой вида <тип_получателя_доступа>:<идентификатор_получателя_доступа>. Object Storage поддерживает следующие типы получателей:

  • id — получатель доступа — пользователь облака.
  • uri — получатель доступа — публичная группа.

Пример:

X-Amz-Grant-Read: uri="http://acs.amazonaws.com/groups/s3/AuthenticatedUsers"

ОтветОтвет

ЗаголовкиЗаголовки

Ответ может содержать только общие заголовки.

Коды ответовКоды ответов

Перечень возможных ответов смотрите в разделе Ответы.

См. такжеСм. также

  • Начало работы с AWS S3 API в Yandex Object Storage

  • Отладка запросов с помощью утилиты AWS CLI

  • Пример отправки подписанного запроса с помощью утилиты curl

  • Пример кода для генерации подписи

Была ли статья полезна?

Предыдущая
Все методы
Следующая
get
Проект Яндекса
© 2025 ТОО «Облачные Сервисы Казахстан»