Object Operations

Put Object

Adds an object to a bucket. You must have write permissions on the bucket to perform this operation.

Syntax

PUT /{bucket}/{object} HTTP/1.1

Request Headers

Name

Description

Valid Values

Required

content-md5

A base64 encoded MD-5 hash of the message.

A string. No defaults or constraints.

No

content-type

A standard MIME type.

Any MIME type. Default: binary/octet-stream

No

x-amz-meta-<…>

User metadata. Stored with the object.

A string up to 8kb. No defaults.

No

x-amz-acl

A canned ACL.

private, public-read, public-read-write, authenticated-read

No

Copy Object

To copy an object, use PUT and specify a destination bucket and the object name.

Syntax

PUT /{dest-bucket}/{dest-object} HTTP/1.1
x-amz-copy-source: {source-bucket}/{source-object}

Request Headers

Name

Description

Valid Values

Required

x-amz-copy-source

The source bucket name + object name.

{bucket}/{obj}

Yes

x-amz-acl

A canned ACL.

private, public-read, public-read-write, authenticated-read

No

x-amz-copy-if-modified-since

Copies only if modified since the timestamp.

Timestamp

No

x-amz-copy-if-unmodified-since

Copies only if unmodified since the timestamp.

Timestamp

No

x-amz-copy-if-match

Copies only if object ETag matches ETag.

Entity Tag

No

x-amz-copy-if-none-match

Copies only if object ETag doesn’t match.

Entity Tag

No

Response Entities

Name

Type

Description

CopyObjectResult

Container

A container for the response elements.

LastModified

Date

The last modified date of the source object.

Etag

String

The ETag of the new object.

Remove Object

Removes an object. Requires WRITE permission set on the containing bucket.

Syntax

DELETE /{bucket}/{object} HTTP/1.1

Get Object

Retrieves an object from a bucket within RADOS.

Syntax

GET /{bucket}/{object} HTTP/1.1

Request Headers

Name

Description

Valid Values

Required

range

The range of the object to retrieve.

Range: bytes=beginbyte-endbyte

No

if-modified-since

Gets only if modified since the timestamp.

Timestamp

No

if-unmodified-since

Gets only if not modified since the timestamp.

Timestamp

No

if-match

Gets only if object ETag matches ETag.

Entity Tag

No

if-none-match

Gets only if object ETag matches ETag.

Entity Tag

No

Response Headers

Name

Description

Content-Range

Data range, will only be returned if the range header field was specified in the request

Get Object Info

Returns information about object. This request will return the same header information as with the Get Object request, but will include the metadata only, not the object data payload.

Syntax

HEAD /{bucket}/{object} HTTP/1.1

Request Headers

Name

Description

Valid Values

Required

range

The range of the object to retrieve.

Range: bytes=beginbyte-endbyte

No

if-modified-since

Gets only if modified since the timestamp.

Timestamp

No

if-unmodified-since

Gets only if not modified since the timestamp.

Timestamp

No

if-match

Gets only if object ETag matches ETag.

Entity Tag

No

if-none-match

Gets only if object ETag matches ETag.

Entity Tag

No

Get Object ACL

Syntax

GET /{bucket}/{object}?acl HTTP/1.1

Response Entities

Name

Type

Description

AccessControlPolicy

Container

A container for the response.

AccessControlList

Container

A container for the ACL information.

Owner

Container

A container for the object owner’s ID and DisplayName.

ID

String

The object owner’s ID.

DisplayName

String

The object owner’s display name.

Grant

Container

A container for Grantee and Permission.

Grantee

Container

A container for the DisplayName and ID of the user receiving a grant of permission.

Permission

String

The permission given to the Grantee object.

Set Object ACL

Syntax

PUT /{bucket}/{object}?acl

Request Entities

Name

Type

Description

AccessControlPolicy

Container

A container for the response.

AccessControlList

Container

A container for the ACL information.

Owner

Container

A container for the object owner’s ID and DisplayName.

ID

String

The object owner’s ID.

DisplayName

String

The object owner’s display name.

Grant

Container

A container for Grantee and Permission.

Grantee

Container

A container for the DisplayName and ID of the user receiving a grant of permission.

Permission

String

The permission given to the Grantee object.

Initiate Multi-part Upload

Initiate a multi-part upload process.

Syntax

POST /{bucket}/{object}?uploads

Request Headers

Name

Description

Valid Values

Required

content-md5

A base64 encoded MD-5 hash of the message.

A string. No defaults or constraints.

No

content-type

A standard MIME type.

Any MIME type. Default: binary/octet-stream

No

x-amz-meta-<…>

User metadata. Stored with the object.

A string up to 8kb. No defaults.

No

x-amz-acl

A canned ACL.

private, public-read, public-read-write, authenticated-read

No

Response Entities

Name

Type

Description

InitiatedMultipartUploadsResult

Container

A container for the results.

Bucket

String

The bucket that will receive the object contents.

Key

String

The key specified by the key request parameter (if any).

UploadId

String

The ID specified by the upload-id request parameter identifying the multipart upload (if any).

Multipart Upload Part

Syntax

PUT /{bucket}/{object}?partNumber=&uploadId= HTTP/1.1

HTTP Response

The following HTTP response may be returned:

HTTP Status

Status Code

Description

404

NoSuchUpload

Specified upload-id does not match any initiated upload on this object

List Multipart Upload Parts

Syntax

GET /{bucket}/{object}?uploadId=123 HTTP/1.1

Response Entities

Name

Type

Description

ListPartsResult

Container

A container for the results.

Bucket

String

The bucket that will receive the object contents.

Key

String

The key specified by the key request parameter (if any).

UploadId

String

The ID specified by the upload-id request parameter identifying the multipart upload (if any).

Initiator

Container

Contains the ID and DisplayName of the user who initiated the upload.

ID

String

The initiator’s ID.

DisplayName

String

The initiator’s display name.

Owner

Container

A container for the ID and DisplayName of the user who owns the uploaded object.

StorageClass

String

The method used to store the resulting object. STANDARD or REDUCED_REDUNDANCY

PartNumberMarker

String

The part marker to use in a subsequent request if IsTruncated is true. Precedes the list.

NextPartNumberMarker

String

The next part marker to use in a subsequent request if IsTruncated is true. The end of the list.

MaxParts

Integer

The max parts allowed in the response as specified by the max-parts request parameter.

IsTruncated

Boolean

If true, only a subset of the object’s upload contents were returned.

Part

Container

A container for LastModified, PartNumber, ETag and Size elements.

LastModified

Date

Date and time at which the part was uploaded.

PartNumber

Integer

The identification number of the part.

ETag

String

The part’s entity tag.

Size

Integer

The size of the uploaded part.

Complete Multipart Upload

Assembles uploaded parts and creates a new object, thereby completing a multipart upload.

Syntax

POST /{bucket}/{object}?uploadId= HTTP/1.1

Request Entities

Name

Type

Description

Required

CompleteMultipartUpload

Container

A container consisting of one or more parts.

Yes

Part

Container

A container for the PartNumber and ETag.

Yes

PartNumber

Integer

The identifier of the part.

Yes

ETag

String

The part’s entity tag.

Yes

Response Entities

Name

Type

Description

CompleteMultipartUploadResult

Container

A container for the response.

Location

URI

The resource identifier (path) of the new object.

Bucket

String

The name of the bucket that contains the new object.

Key

String

The object’s key.

ETag

String

The entity tag of the new object.

Abort Multipart Upload

Syntax

DELETE /{bucket}/{object}?uploadId= HTTP/1.1

Append Object

Append data to an object. You must have write permissions on the bucket to perform this operation. It is used to upload files in appending mode. The type of the objects created by the Append Object operation is Appendable Object, and the type of the objects uploaded with the Put Object operation is Normal Object. Append Object can’t be used if bucket versioning is enabled or suspended. Synced object will become normal in multisite, but you can still append to the original object.

Syntax

PUT /{bucket}/{object}?append&position= HTTP/1.1

Request Headers

Name

Description

Valid Values

Required

content-md5

A base64 encoded MD-5 hash of the message.

A string. No defaults or constraints.

No

content-type

A standard MIME type.

Any MIME type. Default: binary/octet-stream

No

x-amz-meta-<…>

User metadata. Stored with the object.

A string up to 8kb. No defaults.

No

x-amz-acl

A canned ACL.

private, public-read, public-read-write, authenticated-read

No

Response Headers

Name

Description

x-rgw-next-append-position

Next position to append object

HTTP Response

The following HTTP response may be returned:

HTTP Status

Status Code

Description

409

PositionNotEqualToLength

Specified position does not match object length

409

ObjectNotAppendable

Specified object can not be appended

409

InvalidBucketstate

Bucket versioning is enabled or suspended

Put Object Retention

Places an Object Retention configuration on an object.

Syntax

PUT /{bucket}/{object}?retention&versionId= HTTP/1.1

Request Entities

Name

Type

Description

Required

Retention

Container

A container for the request.

Yes

Mode

String

Retention mode for the specified object. Valid Values: GOVERNANCE/COMPLIANCE | Yes

RetainUntilDate

Timestamp

Retention date. Format: 2020-01-05T00:00:00.000Z | Yes

Get Object Retention

Gets an Object Retention configuration on an object.

Syntax

GET /{bucket}/{object}?retention&versionId= HTTP/1.1

Response Entities

Name

Type

Description

Required

Retention

Container

A container for the request.

Yes

Mode

String

Retention mode for the specified object. Valid Values: GOVERNANCE/COMPLIANCE | Yes

RetainUntilDate

Timestamp

Retention date. Format: 2020-01-05T00:00:00.000Z | Yes