forked from TrueCloudLab/frostfs-s3-gw
221 lines
4.2 KiB
Markdown
221 lines
4.2 KiB
Markdown
# S3 API Extension
|
|
|
|
## Bucket operations management
|
|
|
|
### Action to delete bucket (DeleteBucket)
|
|
|
|
Deletes bucket with all objects in it.
|
|
|
|
#### Request Parameters
|
|
|
|
- **Bucket**
|
|
|
|
Specifies the bucket being deleted.
|
|
|
|
|
|
#### Errors
|
|
|
|
- **NoSuchEntity**
|
|
|
|
The request was rejected because it referenced a resource entity that does not exist.
|
|
|
|
HTTP Status Code: 404
|
|
|
|
- **ServiceFailure**
|
|
|
|
The request processing has failed because of an unknown error, exception or failure.
|
|
|
|
HTTP Status Code: 500
|
|
|
|
|
|
#### Example
|
|
|
|
Sample Request
|
|
|
|
```text
|
|
DELETE / HTTP/1.1
|
|
X-Amz-Force-Delete-Bucket: true
|
|
Host: data.s3.<Region>.frostfs-s3-gw.com
|
|
Date: Wed, 01 Mar 2024 12:00:00 GMT
|
|
Authorization: authorization string
|
|
```
|
|
|
|
Sample Response
|
|
|
|
```text
|
|
HTTP/1.1 204 No Content
|
|
x-amz-id-2: JuKZqmXuiwFeDQxhD7M8KtsKobSzWA1QEjLbTMTagkKdBX2z7Il/jGhDeJ3j6s80
|
|
x-amz-request-id: 32FE2CEB32F5EE25
|
|
Date: Wed, 01 Mar 2006 12:00:00 GMT
|
|
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. For regular objects 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>
|
|
```
|