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

Метод startUpload

Статья создана
Обновлена 15 августа 2025 г.

Возвращает идентификатор, который следует использовать во всех дальнейших операциях по загрузке объекта.

Если вместе с объектом необходимо хранить пользовательские метаданные, то передавать их следует в этом запросе.

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

Запрос

POST /{bucket}/{key}?uploads HTTP/2

Path параметры

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

Query параметры

Параметр Описание
uploads Флаг, обозначающий операцию составной загрузки.

Заголовки

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

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

Заголовок Описание
X-Amz-Meta-* Пользовательские метаданные объекта.

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

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

Может иметь любое из значений:
  • STANDARD — стандартное хранилище.
  • COLD, STANDARD_IA или NEARLINE — холодное хранилище.
  • ICE или GLACIER — ледяное хранилище.
Если заголовок не указан, то объект сохраняется в хранилище, установленном в настройках бакета.
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"

Ответ

Заголовки

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

Коды ответов

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

Успешный ответ содержит дополнительные данные в формате XML, схема которого описана ниже.

Схема данных

<ListBucketResult
          xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
          <KeyCount>1</KeyCount>
          <Name>my-sample-bucket</Name>
          <Prefix></Prefix>
          <MaxKeys>1000</MaxKeys>
          <IsTruncated>false</IsTruncated>
          <Contents>
              <Key>text.txt</Key>
              <LastModified>2025-05-15T07:23:08.030Z</LastModified>
              <Owner>
                  <ID>ajegtlf2q28a********</ID>
                  <DisplayName>ajegtlf2q28a********</DisplayName>
              </Owner>
              <ETag>&#34;f75a361db63aa4722fb8e083********&#34;</ETag>
              <Size>103</Size>
              <StorageClass>STANDARD</StorageClass>
              <TagSet></TagSet>
          </Contents>
      </ListBucketResult>
Тег Описание
InitiateMultipartUploadResult Корневой тег ответа.

Путь: /InitiateMultipartUploadResult.
Bucket Имя бакета в который загружается объект.

Путь: /InitiateMultipartUploadResult/Bucket.
Key Ключ, который ассоциируется с объектом, после окончания загрузки.

Путь: /InitiateMultipartUploadResult/Key.
UploadId Идентификатор загрузки.

Все последующие операции с загрузкой должны передавать в Object Storage этот идентификатор.

Путь: /InitiateMultipartUploadResult/UploadId.

См. также

Предыдущая
Общий порядок составной загрузки
Следующая
uploadPart