[#473] Add PATCH to extensions doc
Signed-off-by: Marina Biryukova <m.biryukova@yadro.com>
This commit is contained in:
parent
b08f476ea7
commit
a2e0b92575
1 changed files with 169 additions and 0 deletions
|
@ -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>
|
||||
```
|
||||
|
|
Loading…
Reference in a new issue