Object
Operations with objects:
- GetObject — download an object from the bucket.
- HeadObject — get information about an object.
- PutObject — upload an object to the bucket.
- CopyObject — copy an object located in the bucket.
- DeleteObject — delete an object.
- DeleteMultipleObjects — delete a group of objects by a list.
The GET operation retrieves an object from the bucket. To perform the operation, you must have READ permissions on the object.
By granting READ access to an anonymous user, you can return the object without using an authorization header.
The bucket has no directory hierarchy, unlike a standard file system. However, you can create a logical hierarchy using object key names that imply a structure with directories. For example, you can name an object not sample.jpg, but photos/2020/August/01.jpg.
To retrieve an object with such a logical hierarchy, specify the full object name in the GET operation.
Request example:
...GET /example.txt HTTP/1.1Host: my-test-bucket1.hb.ru-msk.vkcloud-storage.rux-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855x-amz-date: 20200831T190539ZAuthorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20170710/ru-msk/s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-date,Signature=e912de79c88f07832558244bd867c3d834584c7f8b3d8efe4d0f0ba60b7a1dcb'''
Response example:
...HTTP/1.1 200 OKDate: Mon, 31 Aug 2020 19:05:39 GMTx-amz-request-id: tx00000000000000279f46e-005963d003-1268c-ru-mskaContent-Type: text/plainContent-Length: 14Accept-Ranges: bytesLast-Modified: Mon, 31 Aug 2020 19:05:09 GMTEtag: "b3a92f49e7ae64acbf6b3e76f2040f5e"Connection: closeExample text.'''
Header | Description |
|---|---|
Object tagging headers | |
| The number of tags attached to the object, taking into account ACL. If the object has no tags, this header is not returned in the response |
Object lock response header | |
| The status of the legal hold placed on the object:
|
| The type of retention placed on the object:
|
| The date and time the retention period ends, in ISO8601 format |
The HEAD operation retrieves metadata from an object without returning the object itself. This operation is used only when you need just the object's metadata. To use the HEAD operation, you must have READ permission on the object.
To request the HEAD operation, specify the same parameters as for the GetObject operation. The response is identical to the GET response, except that the response body is absent.
If the requested object does not exist, the error returned depends on whether the account has the additional s3:ListBucket permission.
- If the
s3:ListBucketpermission is granted on the bucket, an HTTP 404 error is returned. - If not, an HTTP 403 error is returned.
Request example:
...HEAD /example.txt HTTP/1.1Host: my-test-bucket1.hb.ru-msk.vkcloud-storage.rux-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855x-amz-date: 20200831T185156ZAuthorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20170710/ru-msk/s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-date,Signature=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'''
Response example:
...HTTP/1.1 200 OKDate: Mon, 31 Aug 2020 18:51:58 GMTx-amz-request-id: tx0000000000000002ff1c9-00596912ce-6441-ru-mskaContent-Type: text/plainContent-Length: 14Accept-Ranges: bytesLast-Modified: Mon, 31 Aug 2020 18:40:46 GMTEtag: "b3a92f49e7ae64acbf6b3e76f2040f5e"Connection: close'''
Header | Description |
|---|---|
Object tagging headers | |
| The number of tags attached to the object, taking into account ACL. If the object has no tags, this header is not returned in the response |
Object lock response header | |
| The status of the legal hold placed on the object:
|
| The type of retention placed on the object:
|
| The date and time the retention period ends, in ISO8601 format |
The PUT operation adds an object to the bucket. To perform the operation, you must have WRITE permissions on the bucket.
VK Object Storage adds objects partially if the object size exceeds 50 MB. If a success response is received, the object has been added to the bucket in full.
When concurrent PUT operations are performed and there are identical objects being uploaded, VK Object Storage overwrites all but the last written object.
To prevent data corruption while passing through the network, it is recommended to use the Content-MD5 header, which causes the object to be checked against the provided MD5 value and returns an error if there is a mismatch. In addition, you can calculate the MD5 when placing the object in the bucket and compare the returned ETag with the calculated MD5 value.
Request example:
...PUT /example.txt HTTP/1.1Content-Length: 14Content-Type: text/plainHost: my-test-bucket1.hb.ru-msk.vkcloud-storage.rux-amz-content-sha256: 003f0e5fe338b17be8be93fec537764ce199ac50f4e50f2685a753c4cc781747x-amz-date: 20200831T194605Zx-amz-meta-s3cmd-attrs:uid:1000/gname:asb/uname:asb/gid:1000/mode:33204/mtime:1499727909/atime:1499727909/md5:fb08934ef619f205f272b0adfd6c018c/ctime:1499713540x-amz-storage-class: STANDARDAuthorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20200831/ru-msk/s3/aws4_request,SignedHeaders=content-length;content-type;host;x-amz-content-sha256;x-amz-date;x-amz-meta-s3cmd-attrs;x-amz-storage-class,Signature=a9a9e16da23e0b37ae8362824de77d66bba2edd702ee5f291f6ecbb9ebac6013Example text.'''
Response example:
...HTTP/1.1 200 OKDate: Mon, 31 Aug 2020 19:46:06 GMTx-amz-request-id: tx0000000000000027bd57c-005963d97e-1268c-ru-mskaContent-Length: 0Accept-Ranges: bytesLast-Modified: Mon, 31 Aug 2020 19:05:09 GMTEtag: "fb08934ef619f205f272b0adfd6c018c"Connection: close'''
Header | Description |
|---|---|
Object lock headers | |
| The status of the legal hold being set on the object:
|
| The type of retention being set on the object:
|
| The date and time the retention period ends |
Object tagging headers | |
| Adds tags to the object. Specified as URL query parameters: |
The PUT operation can create a copy of an object that is already stored in the bucket. The copy operation is identical to performing GetObject followed by PutObject. Adding the x-amz-copy-source header to the request causes the PUT operation to copy the source object into the target bucket.
When copying an object, you can retain most of the metadata (by default) or specify new metadata. To write new metadata when copying an object, you must include the x-amz-metadata-directive: REPLACE header in the request. However, ACL and ObjectLock are not copied - for the user sending the request, the new object will be private.
All copy requests must pass authentication and cannot contain a message body. In addition, you must have READ access to the source object and WRITE access to the target bucket.
A copy request can return an error in two cases. This can happen when the copy request is received, or when the objects are being copied. If the error occurs before the copy operation begins, a standard error is returned. If the error occurs during the copy operation, the error is embedded in a 200 OK response. This means that a 200 OK response can contain either a success or an error message.
Request example:
...PUT /copied-example.txt HTTP/1.1Host: my-test-bucket1.hb.ru-msk.vkcloud-storage.rux-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855x-amz-copy-source: /static-images/example.txtx-amz-date: 20200831T202253Zx-amz-metadata-directive: COPYAuthorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20170710/ru-msk/s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-copy-source;x-amz-date;x-amz-metadata-directive;x-amz-storage-class,Signature=0cb03470dd80bdd41a4b8fb06c1800b27a5059b61b0303fe589578835531c877'''
Response example:
...HTTP/1.1 200 OKDate: Mon, 31 Aug 2020 20:22:54 GMTx-amz-request-id: tx0000000000000027d8430-005963e21d-1268c-ru-mskaContent-Length: 183Connection: close<CopyObjectResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/"><LastModified>2020-08-31T20:22:54.167Z</LastModified><ETag>7967bfe102f83fb5fc7e5a02bf05e8fc</ETag></CopyObjectResult>'''
Header | Description |
|---|---|
Object lock headers | |
| The status of the legal hold being set on the object:
|
| The type of retention being set on the object:
|
| The date and time the retention period ends |
Object tagging headers | |
| Adds tags to the object. Specified as URL query parameters: |
| Specifies whether the object's tag set is copied from the source object or replaced with the tag set specified in the request. Possible values:
|
The DELETE operation deletes the object specified in the request.
To delete an object with GOVERNANCE retention set, specify the x-amz-bypass-governance-retention header in the request.
Request example:
...DELETE /sammy.png HTTP/1.1Host: my-test-bucket1.hb.ru-msk.vkcloud-storage.rux-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855x-amz-date: 20200831T194408ZAuthorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20170710/ru-msk/s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-date,Signature=c2a46b21e2e8589dfbfa54382030bbef8108b2504a9f1d8aaba70fb0e1c46522'''
Response example:
...HTTP/1.1 204 No ContentDate: Mon, 31 Aug 2020 19:44:09 GMTx-amz-request-id: tx0000000000000027bbc48-005963d908-1268c-ru-mskaConnection: close'''
Deletes objects by the list of keys passed in the request. The deletion list can contain no more than 1000 keys. The absence of an object is not an error — if the object does not exist, it will be marked as deleted in the response.
The Content-MD5 and Content-Length headers are required, and the list of keys to delete is passed in XML format.
To bypass governance retention when performing this method, specify the x-amz-bypass-governance-retention header in the request.
Request example:
...DELETE /sammy.png HTTP/1.1Host: my-test-bucket1.hb.ru-msk.vkcloud-storage.ruContent-Length: 176Content-MD5: 44c4dcd3d2f3645544a366ae481342fax-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855x-amz-date: 20200831T194408ZAuthorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20170710/ru-msk/s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-date,Signature=c2a46b21e2e8589dfbfa54382030bbef8108b2504a9f1d8aaba70fb0e1c46522<?xml version="1.0" encoding="UTF-8"?><Delete><Object><Key>picture.png</Key></Object><Object><Key>picture2.jpg</Key></Object></Delete>'''
Response example:
...HTTP/1.1 204 No ContentDate: Mon, 31 Aug 2020 19:44:09 GMTx-amz-request-id: tx0000000000000027bbc48-005963d908-1268c-ru-mskaConnection: close<DeleteResult><Deleted><Key>picture.png</Key></Deleted><Error><Key>some/another/key.txt</Key><Code>TextErrorCode</Code><Message>Describing message</Message></Error></DeleteResult>'''