Manage Objects

Starting with VMware Cloud Director Object Storage Extension 1.5, you can keep multiple variants of an object within a bucket by enabling versioning.

With versioning, you can preserve, retrieve, and restore every version of every object that you store in a bucket. You enable versioning at the bucket level. You can enable versioning during the creation of a bucket, or you can edit the versioning configuration later. By default, versioning is disabled.

When the bucket versioning is enabled, modifying object contents or metadata results in a new version of the object.

Once you enable versioning, you cannot disable the feature. You can suspend versioning. The following table describes the versioning statuses.


Status	Description
Disabled	Default feature status. VMware Cloud Director Object Storage Extension does not store versions of the objects that you upload.
Enabled	VMware Cloud Director Object Storage Extension stores versions of the objects that you upload.
Suspended	You cannot upload new object versions. Earlier versions of your objects are preserved and you can retrieve and restore an earlier version of your objects.

Version IDs are generated at the storage platform level and VMware Cloud Director Object Storage Extension does not control the generation of version IDs.

Important:

If VMware Cloud Director Object Storage Extension uses the ECS storage platform, adding tags to an object is impossible. The ECS storage platform does not support object tagging.

Procedure

List all buckets owned by the authenticated user.
If you use path-style requests, use the following format for your request:
```
GET https://cloud-object-storage.example.com:8443/api/v1/s3
```
If you use virtual hosted-style requests, use the following format for your request:
```
GET https://s3.cloud-object-storage.example.com:8443
```
The response body contains a list of all buckets that the authenticated user owns.
Create a bucket.
If you use path-style requests, use the following format for your request:
```
PUT https://cloud-object-storage.example.com:8443/api/v1/s3/bucket-name
```
If you use virtual hosted-style requests, use the following format for your request:
```
PUT https://bucket-name.s3.cloud-object-storage.example.com:8443
```
For more information, see https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html.

The system returns a 200 OK message upon a successful creation of the bucket.
Verify that the bucket is available and accessible.
If you use path-style requests, use the following format for your request:
```
HEAD https://cloud-object-storage.example.com:8443/api/v1/s3/bucket-name
```
If you use virtual hosted-style requests, use the following format for your request:
```
HEAD https://bucket-name.s3.cloud-object-storage.example.com:8443
```
If the bucket is available and accessible for the authenticated user, the system returns a 200 OK message.
Upload an object.
If you use path-style requests, use the following format for your request:
```
PUT https://cloud-object-storage.example.com:8443/api/v1/s3/bucket-name/object-name
```
If you use virtual hosted-style requests, use the following format for your request:
```
PUT https://bucket-name.s3.cloud-object-storage.example.com:8443/object-name
```
For more information, see https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html.
Add tags to the object.
Object tags are key-value pairs that help you categorize objects and buckets.
If you use path-style requests, use the following format for your request:
```
PUT https://cloud-object-storage.example.com:8443/api/v1/s3/bucket-name/object-name?tagging
```
If you use virtual hosted-style requests, use the following format for your request:
```
PUT https://bucket-name.s3.cloud-object-storage.example.com:8443/object-name?tagging
```
Following is an example of a valid tagging request body in JSON and XML formats:
```
{
  "tagSets": [
    {
      "tags": [
        {
          "key": "string",
          "value": "string"
        }
      ]
    }
  ]
}
```
```
<Tagging>
  <TagSet>
     <Tag>
       <Key>string</Key>
       <Value>string</Value>
     </Tag>
  </TagSet>
</Tagging>
```
For more information, see https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObjectTagging.html.

The system returns a 200 OK message upon a successful completion of the operation.
Enable versioning for the bucket.
If you use path-style requests, use the following format for your request:
```
PUT https://cloud-object-storage.example.com:8443/api/v1/s3/bucket-name?versioning
```
If you use virtual hosted-style requests, use the following format for your request:
```
PUT https://bucket-name.s3.cloud-object-storage.example.com:8443?versioning
```
Add the following to the request body:
```
{
  "status": "Enabled"
}
```
The system returns a 200 OK message upon a successful completion of the operation.
Modify the content of the object that you uploaded.
Upload the modified object.
If you use path-style requests, use the following format for your request:
```
PUT https://cloud-object-storage.example.com:8443/api/v1/s3/bucket-name/object-name
```
If you use virtual hosted-style requests, use the following format for your request:
```
PUT https://bucket-name.s3.cloud-object-storage.example.com:8443/object-name
```

Retrieve version details of the object.

If you use path-style requests, use the following format for your request:

GET https://cloud-object-storage.example.com:8443/api/v1/s3/bucket-name?versions&prefix=object_name

If you use virtual hosted-style requests, use the following format for your request:

GET https://bucket-name.s3.cloud-object-storage.example.com:8443?versions&prefix=object_name

The system returns the following:

<ListVersionResult>
    <Name>bucket-name</Name>
    <Prefix>object-name</Prefix>
    <KeyMarker/>
    <VersionIdMarker/>
    <MaxKeys>1000</MaxKeys>
    <IsTruncated>false</IsTruncated>
    <Version>
        <Key>object-name</Key>
        <VersionId>version-id-string</VersionId>
        <IsLatest>true</IsLatest>
        <LastModified>timestamp</LastModified>
        <Owner>
            <ID>owner-id-string</ID>
            <DisplayName>object-owner</DisplayName>
        </Owner>
        <ETag>etag-string</ETag>
        <StorageClass>STANDARD</StorageClass>
        <Size>version-size</Size>
    </Version>
    <Version>
        <Key>object-name</Key>
        <VersionId>version-id-string</VersionId>
        <IsLatest>false</IsLatest>
        <LastModified>timestamp</LastModified>
        <Owner>
            <ID>owner-id-string</ID>
            <DisplayName>object-owner</DisplayName>
        </Owner>
        <ETag>etag-string</ETag>
        <StorageClass>STANDARD</StorageClass>
        <Size>version-size</Size>
    </Version>
</ListVersionResult>

Retrieve the contents of a specific version of the object.
If you use path-style requests, use the following format for your request:
```
GET https://cloud-object-storage.example.com:8443/api/v1/s3/bucket-name/object_name?versionId=version-id-string
```
If you use virtual hosted-style requests, use the following format for your request:
```
GET https://bucket-name.s3.cloud-object-storage.example.com:8443/object-name?versionId=version-id-string
```
The system returns the contents of the version of the object that you specified in the request.