Метод copy
Создает копию объекта, хранящегося в Object Storage. Объекты, размером до 5 ГБ можно скопировать одной операцией copy, если объект больше, чем 5 ГБ, то необходимо применять операцию copyPart.
Чтобы указать источник для копирования, используйте заголовок X-Amz-Copy-Source. Запрос на копирование не должен передавать каких-либо данных, кроме заголовков.
Примечание
Object Storage не блокирует объект на запись и может одновременно принять несколько запросов, копирующих объекты в один и тот же результирующий объект. После завершения всех запросов результирующим объектом окажется тот, чья операция копирования запустилась последней.
Метаданные объекта копируются вместе с объектом. При необходимости их можно изменить, задав в явном виде соответствующие заголовки.
Также с помощью заголовков можно:
- Изменить класс хранилища объекта.
- Добавить условия для копирования объекта.
- Установить блокировку на объект (если бакет версионируемый и механизм блокировок включен).
Пользователь должен иметь разрешение на чтение исходного объекта и разрешение на запись в результирующий бакет.
Подробнее о подготовке к работе с API и общем виде запроса см. в разделе Как пользоваться S3 API.
Запрос
PUT /{bucket}/{key} HTTP/2
Path параметры
| Параметр | Описание |
|---|---|
bucket |
Имя результирующего бакета. |
key |
Ключ результирующего объекта. Идентификатор, под которым объект сохраняется в Object Storage. |
Заголовки
Обязательные заголовки перечислены в таблице ниже.
| Заголовок | Описание |
|---|---|
X-Amz-Copy-Source |
Имя бакета и ключ объекта, который будет копироваться, разделенные символом /.Например, X-Amz-Copy-Source: /source_bucket/sourceObject.Если в бакете включено версионирование, то вы можете скопировать определенную версию объекта. Для этого укажите в заголовке идентификатор версии объекта — добавьте ?versionId=<version-id> к значению заголовка, например: /mybucket/image.png?versionId=0005E4A66AD990A4. Если не указывать идентификатор версии, то будет скопирована последняя версия объекта. |
Также используйте необходимые общие заголовки.
Заголовки, описанные в таблице ниже используйте, если вам необходимо изменить поведение метода copy по умолчанию.
| Заголовок | Описание |
|---|---|
X-Amz-Metadata-Directive |
Режим копирования метаданных. Если значение заголовка COPY, то метаданные объекта копируются, а все заголовки X-Amz-Meta-* игнорируются. Это поведение метода copy по умолчанию.Если значение заголовка REPLACE, то метаданные объекта подменяются указанными в запросе.Заголовок X-Amz-Storage-Class не копируется, добавьте его в запрос, если это необходимо. |
X-Amz-Copy-Source-If-Match |
Условие для копирования объекта. Если ETag объекта равен заданному в заголовке, то объект копируется.Если условие не выполнено, то Object Storage вернет ошибку 412. Можно использовать вместе с заголовком X-Amz-Copy-Source-If-Unmodified-Since. |
X-Amz-Copy-Source-If-None-Match |
Условие для копирования объекта. Если ETag объекта не равен заданному в заголовке, то объект копируется.Если условие не выполнено, то Object Storage вернет ошибку 412. Можно использовать вместе с заголовком X-Amz-Copy-Source-If-Modified-Since. |
X-Amz-Copy-Source-If-Unmodified-Since |
Условие для копирования объекта. Объект копируется, если он не изменялся с указанного времени. Если условие не выполнено, то Object Storage вернет ошибку 412. Можно использовать вместе с заголовком X-Amz-Copy-Source-If-Match. |
X-Amz-Copy-Source-If-Modified-Since |
Условие для копирования объекта. Объект копируется, если он изменился с указанного времени. Если условие не выполнено, то Object Storage вернет ошибку 412. Можно использовать вместе с заголовком X-Amz-Copy-Source-If-None-Match. |
X-Amz-Server-Side-Encryption |
Алгоритм шифрования, используемый по умолчанию для шифрования новых объектов. |
X-Amz-Server-Side-Encryption-Aws-Kms-Key-Id |
Идентификатор ключа KMS, используемый по умолчанию для шифрования новых объектов. |
X-Amz-Storage-Class |
Класс хранилища объекта. Может иметь любое из значений:
|
X-Amz-Object-Lock-Mode |
Тип временной блокировки, устанавливаемой на объект (если бакет версионируемый и в нем включен механизм блокировок):
Вы можете установить на версию объекта только временную блокировку (заголовки |
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 |
Статус бессрочной блокировки, устанавливаемой на объект (если бакет версионируемый и в нем включен механизм блокировок):
Вы можете установить на версию объекта только временную блокировку (заголовки |
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-Metadata-Directive: COPY, то эти заголовки игнорируются. |
Ответ
Заголовки
Ответ может содержать общие заголовки, а также заголовки, перечисленные в таблице ниже.
| Заголовок | Описание |
|---|---|
X-Amz-Storage-Class |
Класс хранилища объекта. Может иметь значения:
|
Коды ответов
Перечень возможных ответов смотрите в разделе Ответы.
Схема данных
<CopyObjectResult>
<LastModified>2019-02-15T14:32:00</LastModified>
<ETag>"9bgh7535f2734ec974343yuc93985328"</ETag>
</CopyObjectResult>
| Элемент | Описание |
|---|---|
CopyObjectResult |
Содержит элементы ответа. Путь: /CopyObjectResult. |
ETag |
ETag результирующего объекта. Поскольку при вычислении ETag не учитываются метаданные, то ETag исходного и результирующего объекта должны быть равны.Путь: /CopyObjectResult/ETag. |
LastModified |
Дата последнего изменения объекта. Путь: /CopyObjectResult/LastModified. |