[#473] Add PATCH to extensions doc

Signed-off-by: Marina Biryukova <m.biryukova@yadro.com>
This commit is contained in:
Marina Biryukova 2024-08-21 17:06:32 +03:00 committed by Alexey Vanin
parent b08f476ea7
commit a2e0b92575

View file

@ -50,3 +50,172 @@ HTTP/1.1 204 No Content
Connection: close
Server: AmazonS3
```
## Object operations management
### Action to patch object (PatchObject)
Allows to partially change and add data to an existing object.
> **Note**: patch is not supported for objects that were uploaded using SSE.
#### Path parameters
- **Bucket**
Bucket name.
_Required: Yes_
- **Key**
Object name.
_Required: Yes_
#### Query parameters
- **versionId**
Version of the original object to patch.
_Required: No_
#### Request headers
- **Content-Range**
The byte range of the object (or its version) to patch.
The value is formed as follows: `bytes {start byte}-{end byte}/*`.
Range boundaries are included.
The maximum range length is 5GB.
To write additional data to the object, the end byte must be greater than the object size.
The start byte cannot be greater than the object size.
The range length must be equal to the value of the **_Content-Length_** header.
The format corresponds to the [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110#name-content-range) specification with the following
exceptions:
- **_complete-length_** parameter is ignored.
- **_last-pos_** parameter is optional (if not specified, the value is assumed to be equal to the end byte of the object).
_Required: Yes_
- **Content-Length**
Number of bytes sent in the request body.
_Required: Yes_
- **If-Match**
Patch is performed if ETag of the object (or its version) is equal to specified in the header.
_Required: No_
- **If-Unmodified-Since**
Patch is performed if the object (or its version) has not changed since the time specified in the header.
_Required: No_
- **x-amz-expected-bucket-owner**
ID of the intended owner of the bucket.
_Required: No_
#### Request body
Contains new data for the passed byte range of the object.
#### Response
The request returns the following data in XML format.
- **PatchObjectResult**
Root level tag for parameters.
- **Object**
Parent tag for patch results.
- **LastModified**
Time when the object was last modified. Applying patch does not change this value.
- **ETag**
Patched object tag. Always in SHA-256 format.
If the bucket is versioned, the **_x-amz-version-id_** header is returned with the version of the created object.
#### Errors
- **MissingContentRange**
The required **_Content-Range_** header was not sent.
HTTP Status Code: 400
- **NoSuchBucket**
The specified bucket does not exist.
HTTP Status Code: 404
- **NoSuchKey**
The specified object does not exist.
HTTP Status Code: 404
- **MissingContentLength**
The required **_Content-Length_** header was not sent.
HTTP Status Code: 411
- **PreconditionFailed**
At least one of the preconditions is not satisfied.
HTTP Status Code: 412
- **InvalidRange**
Incorrect value in **_Content-Range_** header.
HTTP Status Code: 416
#### Example
Sample Request
```text
PATCH /example-bucket/example-key HTTP/1.1
Host: data.s3.<Region>.frostfs-s3-gw.com
Content-Range: bytes 0-3/*
Content-Length: 4
&AUTHPARAMS
Body
```
Sample Response
```xml
<PatchObjectResult>
<Object>
<LastModified>2024-07-24T14:54:54Z</LastModified>
<ETag>"e8b53b75afaf3ce898f048c663b11cf4c71f5f13456673dd5b422a247c9e627f"</ETag>
</Object>
</PatchObjectResult>
```