Initiate Multipart Upload

Описание

Операция инициализирует многокомпонентную загрузку и возвращает идентификатор загрузки. Идентификатор загрузки используется для объединения всех частей одной многокомпонентной загрузки. Необходимо указывать этот идентификатор загрузки в каждом из ваших последующих запросов на загрузку части. Также можно включать данный идентификатор загрузки в последний запрос для завершения или прерывания запроса на многокомпонентную загрузку.

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

По отношению к подписи запроса многокомпонентная загрузка — это последовательность обычных запросов, т. е. вы инициализируете многокомпонентную загрузку, отправляете один или несколько запросов на загрузку частей, а затем завершаете многокомпонентную загрузку. Подпись каждого запроса осуществляется по отдельности. Подпись запросов на многокомпонентную загрузку является стандартной процедурой. 

Примечание

После инициализации многокомпонентной загрузки и собственно загрузки одной или нескольких частей вы должны завершить или прервать многокомпонентную загрузку, чтобы приостановить списание оплаты за хранение загруженных частей. Только после завершения или прерывания многокомпонентной загрузки сервис освобождает место, предоставляемое частям в хранилище, и прекращает производить списание оплаты за хранение этих частей.

Вы также можете запросить шифрование на стороне сервера. В этом случае, ваши данные шифруются во время их записи на диски в центрах хранения и обработки данных сервиса и расшифровываются тогда, когда вы осуществляете доступ к ним. У вас есть возможность предоставить собственный ключ шифрования при помощи ключей шифрования сервиса или службы управления ключами. При выборе собственного ключа шифрования, заголовки запроса, предоставляемые вами в запросах по загрузке части, должны совпадать с заголовками, которые вы использовали в запросе на инициализацию загрузки.

Запросы

Синтаксис

 POST /ObjectName?uploads HTTP/1.1
 Host: BucketName.hb.bizmrg.com (BucketName.ib.bizmrg.com)
 Date: date
 Authorization: authorization string

Параметры запроса

Эта операция не использует параметры запроса.

Заголовки запроса

Имя
Описание
Обязательно
Cache-Control

Может использоваться для указания поведения кеширования по отношению к цепочке запросов/ответов. Для получения дополнительной информации перейдите по ссылке: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9.

  • Тип: String
  • По умолчанию: нет значения
Нет
Content-?Disposition

Указывает представляемую информацию для объекта. Дополнительная информация находится по ссылке: http://www.w3.org/Protocols/rfc2616/rfc2616-sec19.html#sec19.5.1.

  • Тип: String
  • По умолчанию: нет значения
Нет
Content-Encoding

Указывает на используемые кодировки содержимого на объекте и, следовательно, на то, какие механизмы декодирования должны быть использованы для получения типа содержимого media-type, на который ссылается поле заголовка Content-Type. Для получения дополнительной информации перейдите по ссылке: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.11.

  • Тип: String
  • По умолчанию: нет значения
Нет
Content-Type

Стандартный тип MIME, описывающий формат данных объекта. Для получения дополнительной информации перейдите по ссылке: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17.


  • Тип: String
  • По умолчанию: binary/octet-stream
Ограничения: только для типов MIME


Нет
Expires

Дата и время окончания возможности кешированния объекта. Для получения дополнительной информации перейдите по ссылке: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.21.

  • Тип: String
  • По умолчанию: нет значения
Нет
x-amz-meta-

Заголовки, начинающиеся с этого префикса являются пользовательскими метаданными. Каждый из заголовков сохраняется и возвращается как набор пар ключ-значение. Сервис не осуществляет проверку и не интерпретирует пользовательские метаданные. Дополнительная информация находится по ссылке <ссылка>.

  • Тип: String
  • По умолчанию: нет значения
Нет
x-amz-storage-?class

Класс используемого хранения для объекта, создаваемого после успешной многокомпонентной загрузки. При отсутствии указанного значения устанавливается класс хранения Standard.


  • Тип: Enum
  • По умолчанию: STANDARD
  • Допустимые значения: STANDARD | STANDARD_IA |REDUCED_REDUNDANCY


Ограничения: вы не можете указать GLACIER в качестве класса хранения холодных данных. Для того, чтобы объекты перешли в класс хранения GLACIER вы можете воспользоваться конфигурацией жизненного цикла.

Нет
x-amz-website?-redirect-location

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

В следующем примере заголовок запроса устанавливает переадресацию на объект (anotherPage.html), находящийся в том же бакете.

x-amz-website-redirect-location: /anotherPage.html

В следующем примере заголовок запроса устанавливает переадресацию объекта на другой веб-сайт.

x-amz-website-redirect-location: http://www.example.com/

  • Тип: String
  • По умолчанию: нет значения

Ограничения: у значения должен присутствовать префикс «/», «http://» или «https://». Максимальная длина значения — 2 КБ.

Нет

Заголовки запроса, характерные для списка управления доступом (ACL) 

С данной операцией вы можете дополнительно использовать следующие заголовки, относящиеся к управлению доступом. По умолчанию все объекты являются частными (private) и только их владелец имеет право полного доступа к ним. При добавлении нового объекта вы можете предоставить разрешения отдельным проектам сервиса или группам, предопределяемым сервисом. Это приведет к добавлению этих разрешений в список управления доступом (ACL) на объекте. Данная операция позволяет вам устанавливать права доступа, используя один из следующих методов.

  • Указание готового ACL: сервис поддерживает набор предопределенных ACL, так называемых «готовых ACL». Каждый готовый ACL содержит предопределенный набор получателей прав и разрешений. 


Имя
Описание
Обязательно
x-amz-acl

Готовый ACL, применяемый к объекту.

  • Тип: String
  • По умолчанию: private
  • Допустимые значения: private | public-read | public-read-write | aws-exec-read | authenticated-read | bucket-owner-read | bucket-owner-full-control
Ограничения: нет
Нет
  • Указание права доступа явным образом — если вы хотите указать предоставляемые права доступа конкретным проектам сервиса или группам явным образом, то вы можете использовать нижеуказанные заголовки. Каждый из этих заголовков соответствует определенным разрешениям, поддерживаемым сервисом в ACL. Дополнительная информация находится по ссылке <ссылка>. В заголовке указывается список получателей прав, которые получают конкретное разрешение.


Имя
Описание
Обязательно
x-amz-grant-read

Позволяет получателю прав прочитать данные объекта и его метаданные.

  • Тип: String
  • По умолчанию: нет значения
Ограничения: нет
Нет
x-amz-grant-write

Неприменимо.

  • Тип: String
  • По умолчанию: нет значения
Ограничения: нет
Нет
x-amz-grant-read-acp

Позволяет получателю прав прочитать ACL объекта.

  • Тип: String
  • По умолчанию: нет значения
Ограничения: нет
Нет
x-amz-grant-write-acp

Позволяет получателю прав записывать ACL для соответствующего объекта.

  • Тип: String
  • По умолчанию: нет значения
Ограничения: нет
Нет
x-amz-grant-full-control

Дает получателю прав следующие разрешения на объект: READ, READ_ACP и WRITE_ACP.

  • Тип: String
  • По умолчанию: нет значения
Ограничения: нет
Нет

Вы указываете каждого получателя прав как «тип=пара значений», где «тип» может принимать одно из следующих значений:

  • emailAddress, если указываемое значение является адресом электронной почты проекта сервиса;
  • id, если указываемое значение является каноническим идентификатором пользователя проекта сервиса;
  • uri, если разрешение предоставляется предопределенной группе.

Например, следующий заголовок x-amz-grant-read предоставляет проектам сервиса, определяемым по адресам электронной почты, разрешение на чтение данных и метаданных объекта.

 x-amz-grant-read: emailAddress="xyz@bizmrg.com", emailAddress="abc@bizmrg.com"

Заголовки запроса, характерные для шифрования на серверной части

По желанию вы можете запросить сервис шифровать данные при хранении, используя шифрование на стороне сервера. Шифрование на стороне сервера — это шифрование данных при хранении, т. е. ваши данные шифруются во время их записи на диски в центрах хранения и обработки данных сервиса и расшифровываются тогда, когда вы осуществляете доступ к ним. В зависимости от того, хотите ли вы использовать ключи шифрования сервиса или предоставлять собственные ключи шифрования, вы используете следующие заголовки.

  • При использовании ключей шифрования, управляемых при помощи службы управления ключами или при помощи сервиса вы указываете следующие заголовки в запросе.
Имя
Описание
Обязательно
x-amz-server-side?-encryption

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

  • Тип: String
  • Допустимое значение: aws:kms, AES256
Нет
x-amz-server-side-encryption-aws-kms-key-id

Если элемент x-amz-server-side-encryption присутствует и при этом его значение равно значению aws:kmz, то данный заголовок указывает идентификатор главного ключа шифрования службы управления ключами, использованного для объекта.

  • Тип: String
Да, если значением элемента x-amz-server-side-encryption является aws:kms
x-amz-server-side-encryption-context

Если элемент x-amz-server-side-encryption присутствует и при этом его значение равно aws:kmz, то данный заголовок указывает контекст шифрования для объекта. Значением данного заголовка является зашифрованная алгоритмом Base64 строка в кодировке UTF-8, содержащая пары ключ–значение контекста шифрования в формате JSON.

  • Тип: String
Нет


При указании x-amz-server-side-encryption:aws:kms и непредоставлении x-amz-server-side- encryption-aws-kms-key-id для защиты данных будет использоваться стандартный ключ службы управления ключами сервиса.

  • При использовании пользовательских ключей шифрования, т. е. если вы сами хотите управлять собственными ключами шифрования, вы должны указывать все следующие заголовки в запросе.
Имя
Описание
Обязательно
x-amz-server-side?-encryption?-customer-algorithm

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


  • Тип: String
  • По умолчанию: нет значения
  • Допустимое значение: AES256


Ограничения: необходимо также указать допустимые заголовки x-amz-server-side-encryption-customer-key и x-amz-server-side-encryption-customer-key-MD5.
Да
x-amz-server-side?-encryption?-customer-key

Указывает зашифрованный алгоритмом Base64 пользовательский ключ шифрования для использования сервисом в шифровании данных. Данное значение используется для сохранения объекта, а затем отбрасывается — сервис не хранит ключ шифрования. Этот ключ должен подходить для использования в алгоритме, указанном в заголовке x-amz-server-side-encryption-customer-algorithm.

  • Тип: String
  • По умолчанию: нет значения
Ограничения: необходимо также указать допустимые заголовки x-amz-server-side-encryption-customer-algorithm и x-amz-server-side-encryption-customer-key-MD5.
Да
x-amz-server-side-encryption-customer-key-MD5

Указывает зашифрованную алгоритмом Base64 128-битную MD5-свертку ключа шифрования согласно RFC 1321. Сервис использует данный заголовок для проверки целостности сообщения, чтобы удостовериться в том, что передача ключа шифрования была безошибочной.

  • Тип: String
  • По умолчанию: нет значения

Ограничения: необходимо также указать допустимые заголовки x-amz-server-side-encryption-customer-algorithm и x-amz-server-side-encryption-customer-key.

Да

Элементы запроса

Эта операция не использует элементы запроса.

Ответы

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

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


Имя
Описание
x-amz-abort-date

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

Ответ также включает в себя заголовок x-amz-abort-rule-id, который предоставляет идентификатор правила конфигурации жизненного цикла, определяющего данное действие.

  • Тип: String
x-amz-abort?-rule-id

Данный заголовок возвращается вместе с заголовком x-amz-abort-date и определяет применимое правило конфигурации жизненного цикла, которое определяет действие прерывания для незавершенных многокомпонентных загрузок.

  • Тип: String
x-amz-server-side?-encryption

Если вы указали в запросе на инициализацию многокомпонентной загрузки шифрование на стороне сервера при помощи ключа шифрования сервиса или службы управления ключами, то ответ содержит этот заголовок. Он подтверждает тот алгоритм шифрования, который используется сервисом для шифрования загруженной вами части.

  • Тип: String
x-amz-server-side-encryption-aws-kms-key-id

Если элемент x-amz-server-side-encryption присутствует и при этом его значение равно значению aws:kmz, то данный заголовок указывает идентификатор главного ключа шифрования службы управления ключами, использованного для объекта.

  • Тип: String
x-amz-server-side?-encryption?-customer-algorithm

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

  • Тип: String
  • Допустимые значения: AES256
x-amz-server-side?-encryption?-customer-key-MD5

Если было запрошено шифрование на стороне сервера с помощью пользовательского ключа шифрования, то ответ возвращает данный заголовок для предоставления проверки целостности кругового сообщения с пользовательским ключом шифрования.

  • Тип: String

Элементы ответов

Имя
Описание
InitiateMultipartUploadResult

Контейнер для ответа.


  • Тип: Container
  • Дочерние элементы: Bucket, Key, UploadId
  • Предки: нет значения


Bucket

Имя бакета, для которого инициализирована многокомпонентная загрузка.

  • Тип: string
  • Предки: InitiateMultipartUploadResult
Key

Ключ объекта, для которого инициализирована многокомпонентная загрузка.

  • Тип: String
  • Предки: InitiateMultipartUploadResult
UploadId

Идентификатор инициализированной многокомпонентной загрузки.

  • Тип: String
  • Предки: InitiateMultipartUploadResult

Примеры

Пример 1

Данная операция инициализирует многокомпонентную загрузку для объекта example-object.

Запрос

 POST /example-object?uploads HTTP/1.1
 Host: BucketName.hb.bizmrg.com (BucketName.ib.bizmrg.com)
 Date: Mon, 1 Nov 2010 20:34:56 GMT
 Authorization: authorization string

Ответ

 HTTP/1.1 200 OK
 x-amz-id-2: Uuag1LuByRx9e6j5Onimru9pO4ZVKnJ2Qz7/C1NPcfTWAtRPfTaOFg==
 x-amz-request-id: 656c76696e6727732072657175657374
 Date: Mon, 1 Nov 2010 20:34:56 GMT
 Content-Length: 197
 Connection: keep-alive
 Server: HbBizmrg
<?xml version="1.0" encoding="UTF-8"?>
<InitiateMultipartUploadResult xmlns="http://hb.bizmrg.com/doc/2006-03-01/">
<Bucket>example-bucket</Bucket>
<Key>example-object</Key>
<UploadId>VXBsb2FkIElEIGZvciA2aWWpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZA</UploadId>
</InitiateMultipartUploadResult>

Пример 2. Инициализация многокомпонентной загрузки с шифрованием на стороне сервера с помощью пользовательских ключей шифрования

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

 POST /example-object?uploads HTTP/1.1
 Host: example-bucket.hb.bizmrg.com (example-bucket.ib.bizmrg.com) 
 Authorization: authorization string 
 Date: Wed, 28 May 2014 19:34:57 +0000 
 x-amz-server-side-encryption-customer-key: g0lCfA3Dv40jZz5SQJ1ZukLRFqtI5WorC/8SEEXAMPLE
 x-amz-server-side-encryption-customer-key-MD5: ZjQrne1X/iTcskbY2example
 x-amz-server-side-encryption-customer-algorithm: AES256 

В ответе сервис возвращает идентификатор загрузки UploadId. Кроме того, сервис возвращает используемый алгоритм шифрования и MD5-свертку ключа шифрования, который вы предоставили в запросе.

 HTTP/1.1 200 OK
 x-amz-id-2: 36HRCaIGp57F1FvWvVRrvd3hNn9WoBGfEaCVHTCt8QWf00qxdHazQUgfoXAbhFWD
 x-amz-request-id: 50FA1D691B62CA43   
 Date: Wed, 28 May 2014 19:34:58 GMT
 x-amz-server-side-encryption-customer-algorithm: AES256
 x-amz-server-side-encryption-customer-key-MD5: ZjQrne1X/iTcskbY2m3tFg== 
 Transfer-Encoding: chunked
<?xml version="1.0" encoding="UTF-8"?>
<InitiateMultipartUploadResult xmlns="http://hb.bizmrg.com/doc/2006-03-01/">
<Bucket>example-bucket</Bucket>
<Key>example-object</Key>
<UploadId>EXAMPLEJZ6e0YupT2h66iePQCc9IEbYbDUy4RTpMeoSMLPRp8Z5o1u8feSRonpvnWsKKG35tI2
LB9VDPiCgTy.Gq2VxQLYjrue4Nq.NBdqI-</UploadId>
</InitiateMultipartUploadResult>