Object Storage API, REST совместимый с Amazon S3: patch
Статья создана
Обновлена 24 июня 2026 г.
Частично изменяет и дозаписывает данные объекта в Yandex Object Storage.
Примечание
Механизм частичного изменения объекта не входит в стандартную функциональность S3 API и доступен для бакетов с выключенным версионированием.
В запросе передаются изменяемый диапазон объекта и новые данные.
Допускается одновременное изменение объекта несколькими запросами.
Подробнее о подготовке к работе с API и общем виде запроса в разделе Как пользоваться S3 API.
Запрос
PATCH /{bucket}/{key} HTTP/2
Path параметры
| Параметр | Описание |
|---|---|
bucket |
Имя бакета. |
key |
Ключ объекта. Идентификатор, под которым объект хранится в Object Storage. |
Заголовки
Используйте в запросе общие заголовки, а также заголовки, представленные ниже:
| Заголовок | Описание |
|---|---|
Content-Range |
Обязательный параметр. Значение: bytes {<начальный_байт>}-{<конечный_байт>}/*.Границы диапазона включены. Максимальная длина диапазона — 5 ГБ. Заголовок Content-Length должен быть равен длине Content-Range.Чтобы дозаписать данные в объект, укажите значение конечного байта большее, чем размер объекта. Значение начального байта не может быть больше, чем размер объекта. Формат заголовка соответствует спецификации RFC 9110 со следующими исключениями:
|
X-Yc-S3-Patch-Append-Part-Size |
Опциональный параметр. Значение: {размер_новой_составной_части}.Размер новых составных частей объекта, загруженного по частям, при дозаписи в конец объекта. В байтах. Если последняя составная часть объекта достигла указанного размера, следующая дозапись будет сохранена как новая составная часть. Значение по умолчанию — 25 МБ. |
If-Match |
Опциональный параметр. Условие для частичного изменения объекта. Если ETag объекта равен заданному в заголовке, то операция выполняется.Если условие не выполнено, то Object Storage вернет ошибку 412 Precondition Failed.Можно использовать вместе с заголовком If-Unmodified-Since. |
If-Unmodified-Since |
Опциональный параметр. Условие для частичного изменения объекта. Операция выполняется, если объект не менялся с указанного времени. Если условие не выполнено, то Object Storage вернет ошибку 412 Precondition Failed.Можно использовать вместе с заголовком If-Match. |
Ответ
Заголовки
Ответ может содержать только общие заголовки.
Коды ответов
Перечень возможных ответов смотрите в разделе Ответы.
Дополнительно Object Storage может вернуть ошибки, описанные в таблице ниже.
| Ошибка | Описание |
|---|---|
MissingContentRange |
В запросе отсутствует заголовок Content-Range. |
MalformedPatchAppendPartSize |
В запросе неверно указано значение заголовка X-Yc-S3-Patch-Append-Part-Size. |
ObjectVersionPatchConflict |
Во время частичного изменения объект был перезаписан новой версией. |
ConcurrentUpdatesPatchConflict |
Из-за большого количества одновременных запросов не удалось разрешить конфликт. |
Схема данных
<?xml version="1.0" encoding="UTF-8"?>
<PatchObjectResult>
<Object>
<LastModified>2023-07-21T11:46:16.357Z</LastModified>
<ETag>"daebcb5e72f14b690c18018c9f92af05-2"</ETag>
</Object>
</PatchObjectResult>
| Тег | Описание |
|---|---|
PatchObjectResult |
Корневой элемент. |
Object |
Родительский тег для результатов изменения. |
LastModified |
Дата и время последнего изменения объекта. При частичном изменении объекта тег не изменяется. |
ETag |
ETag обновленного объекта. Подробнее смотрите общие заголовки. |