PutObject
Adds an object to a bucket.
Description
The PutObject operation adds an object to a bucket. You can use PutObject to create a new object or replace an existing object. To use this operation, you must have s3:PutObject permissions on the bucket, or be the bucket owner.
Important
- QStorage never adds partial objects; if you receive a success response, QStorage added the entire object to the bucket.
- If you upload an object that has the same key as an existing object in the bucket, QStorage replaces the existing object.
- You cannot use
PutObjectto only update a single piece of metadata for an existing object. You must put the entire object with updated metadata if you want to update some values. - The maximum size of a single PUT operation is 5 GB.
- For objects larger than 100 MB, consider using multipart uploads for better reliability.
- User-defined metadata is limited to 2 KB in size.
- Headers with the prefix
x-amz-meta-are treated as user-defined metadata. - You can use SSE, but this means your uploaded data will be encrypted twice, once with the specified key, and again for storage.
Access Control Lists (ACLs)
- By default, all objects are private. Only the owner has full access control.
- You can use headers to grant ACL-based permissions to individual accounts or predefined groups.
- You can use either canned ACLs (x-amz-acl) or grant specific permissions (x-amz-grant-* headers).
- If the bucket uses the bucket owner enforced setting for Object Ownership, ACLs are disabled.
Data Integrity
- You can use Content-MD5 header for basic data integrity verification.
- For enhanced integrity checking, you can use one of the following checksum algorithms:
- CRC32 (x-amz-checksum-crc32)
- CRC32C (x-amz-checksum-crc32c)
- SHA1 (x-amz-checksum-sha1)
- SHA256 (x-amz-checksum-sha256)
- When using SDKs, you can specify the checksum algorithm using x-amz-sdk-checksum-algorithm.
Server-Side Encryption
- Objects are encrypted by default using server-side encryption with QStorage managed keys.
- You can specify the following encryption options:
- QStorage managed keys (SSE-S3) using AES256
- QKMS keys (SSE-KMS) using verenc
- Double encryption with QKMS keys (DSSE-KMS) using verenc:dsse
- When using KMS encryption, you can specify:
- The KMS key ID (x-amz-server-side-encryption-aws-kms-key-id)
- Additional encryption context (x-amz-server-side-encryption-context)
- Whether to use QStorage Bucket Keys (x-amz-server-side-encryption-bucket-key-enabled)
Object Lock
- You can use Object Lock to prevent an object from being deleted or overwritten for a fixed amount of time or indefinitely.
- Object Lock can be applied in one of two modes:
- GOVERNANCE mode: Users with special permissions can override these retention settings
- COMPLIANCE mode: No one, including the root user, can override or delete the object until retention expires
- Legal holds can be placed independently of retention periods
- To use Object Lock:
- Specify the lock mode using x-amz-object-lock-mode
- Set the retention period using x-amz-object-lock-retain-until-date
- Apply legal holds using x-amz-object-lock-legal-hold
- Object Lock must be enabled on the bucket before it can be used on objects
Required Permissions
- To successfully complete the
PutObjectrequest, you must have thes3:PutObjectpermission on the bucket. - To change the object's ACL with your
PutObjectrequest, you must have thes3:PutObjectAclpermission. - To set the tag-set with your
PutObjectrequest, you must have thes3:PutObjectTaggingpermission. :::
Request Syntax
PUT /ObjectKey HTTP/1.1
Host: BucketName.qstorage.quilibrium.com
Content-Length: ContentLength
Content-Type: ContentType
Content-MD5: ContentMD5
x-amz-meta-*: MetadataValue
x-amz-expected-bucket-owner: OwnerAccountId
[12345 bytes of object data]
Values in italics indicate user input and should be replaced with actual values.
Request Parameters
Headers
| Name | Description | Required | Type |
|---|---|---|---|
| Content-Length | Size of the object in bytes | Yes | number |
| Content-Type | A standard MIME type describing the format of the object data | No | text |
| Content-MD5 | The base64-encoded 128-bit MD5 digest of the message (RFC 1864) | No | text |
| Cache-Control | Can be used to specify caching behavior along the request/reply chain | No | text |
| Content-Disposition | Specifies presentational information for the object | No | text |
| Content-Encoding | Specifies what content encodings have been applied to the object | No | text |
| Expires | The date and time at which the object is no longer cacheable | No | text |
| x-amz-acl | The canned ACL to apply to the object Valid values: private | public-read | public-read-write | authenticated-read | aws-exec-read | bucket-owner-read | bucket-owner-full-control | No | text |
| x-amz-checksum-crc32 | The Base64 encoded, 32-bit CRC32 checksum of the object for data integrity verification | No | text |
| x-amz-checksum-crc32c | The Base64 encoded, 32-bit CRC32C checksum of the object for data integrity verification | No | text |
| x-amz-checksum-sha1 | The Base64 encoded, 160-bit SHA1 digest of the object for data integrity verification | No | text |
| x-amz-checksum-sha256 | The Base64 encoded, 256-bit SHA256 digest of the object for data integrity verification | No | text |
| x-amz-grant-full-control | Gives the grantee READ, READ_ACP, and WRITE_ACP permissions on the object | No | text |
| x-amz-grant-read | Allows grantee to read the object data and its metadata | No | text |
| x-amz-grant-read-acp | Allows grantee to read the object ACL | No | text |
| x-amz-grant-write-acp | Allows grantee to write the ACL for the applicable object | No | text |
| x-amz-server-side-encryption | The server-side encryption algorithm to use when storing this object Valid values: AES256 | verenc | No | text |
| x-amz-server-side-encryption-aws-kms-key-id | The ID of the QKMS key to use for object encryption. Required if x-amz-server-side-encryption is verenc | No | text |
| x-amz-server-side-encryption-context | Specifies the QKMS Encryption Context to use for object encryption (Base64-encoded string of UTF-8 encoded JSON) | No | text |
| x-amz-server-side-encryption-bucket-key-enabled | Specifies whether to use an QStorage Bucket Key for object encryption with QKMS (SSE-KMS) | No | text |
| x-amz-sdk-checksum-algorithm | Indicates the algorithm used to create the checksum when using the SDK Valid values: CRC32 | CRC32C | SHA1 | SHA256 | CRC64NVME | No | text |
| x-amz-meta-* | User-defined metadata. Each key-value pair in the metadata is stored with the object. Total size of all metadata must be less than 2KB. | No | text |
| x-amz-tagging | The tag-set for the object. The tag-set must be encoded as URL Query parameters | No | text |
| x-amz-expected-bucket-owner | The account ID of the expected bucket owner. Request fails with 403 Forbidden if the account ID doesn't match the actual bucket owner | No | text |
| x-amz-object-lock-legal-hold | Specifies whether a legal hold will be applied to this object. For more information about Object Lock, see Object Lock documentation Valid values: ON | OFF | No | text |
| x-amz-object-lock-mode | The Object Lock mode that you want to apply to this object Valid values: GOVERNANCE | COMPLIANCE | No | text |
| x-amz-object-lock-retain-until-date | The date and time when you want this object's Object Lock to expire. Must be formatted as a timestamp parameter. | No | text |
Examples
Example 1: Upload a text file
PUT /hello.txt HTTP/1.1
Host: my-bucket.qstorage.quilibrium.com
Content-Length: 11
Content-Type: text/plain
Hello World
Values in italics indicate user input and should be replaced with actual values.
HTTP/1.1 200 OK
x-amz-id-2: Example7qoYGN7uMuFuYS6m7a4l
x-amz-request-id: TX234S0F24A06C7
Date: Wed, 01 Mar 2024 12:00:00 GMT
ETag: "7778aef83f66abc1fa1e8477f296d394"
Values in italics indicate variable response values.
Example 2: Upload an object with metadata
PUT /document.txt HTTP/1.1
Host: my-bucket.qstorage.quilibrium.com
Content-Length: 11
Content-Type: text/plain
x-amz-meta-title: My Document
x-amz-meta-author: John Doe
Hello World
Values in italics indicate user input and should be replaced with actual values.
HTTP/1.1 200 OK
x-amz-id-2: Example7qoYGN7uMuFuYS6m7a4l
x-amz-request-id: TX234S0F24A06C7
Date: Wed, 01 Mar 2024 12:00:00 GMT
ETag: "7778aef83f66abc1fa1e8477f296d394"
Values in italics indicate variable response values.
Response Syntax
HTTP/1.1 200 OK
x-amz-id-2: RequestId
x-amz-request-id: AmazonRequestId
Date: ISO8601Date
ETag: EntityTag
Values in italics indicate variable response values.
Response Elements
Response Headers
| Name | Description | Required | Type |
|---|---|---|---|
| x-amz-id-2 | An identifier for the request that you can use to troubleshoot issues | No | String |
| x-amz-request-id | A unique identifier for the request that you can use to troubleshoot issues | No | String |
| x-amz-version-id | The version ID of the object. When you upload an object in a bucket with versioning enabled, QStorage automatically generates a version ID for the object | No | String |
| x-amz-expiration | If the object expiration is configured, this header contains the expiration date of the object and the rule ID that matches the object | No | String |
| ETag | Entity tag containing an MD5 hash of the object. The ETag reflects changes only to the contents of an object, not its metadata | No | String |
| x-amz-server-side-encryption | The server-side encryption algorithm used when storing this object (AES256, verenc) Valid values: AES256 | verenc | No | String |
| x-amz-server-side-encryption-aws-kms-key-id | If x-amz-server-side-encryption is verenc, this header specifies the ID of the Quilibrium Key Management Service (QKMS) symmetric encryption customer managed key that was used for the object | No | String |
| x-amz-server-side-encryption-customer-algorithm | If server-side encryption with customer-provided encryption keys was requested, this header confirms the encryption algorithm used | No | String |
| x-amz-server-side-encryption-customer-key-MD5 | If server-side encryption with customer-provided encryption keys was requested, this header provides the base64-encoded MD5 digest of the encryption key | No | String |
| x-amz-server-side-encryption-bucket-key-enabled | Indicates whether the uploaded object uses an QStorage Bucket Key for server-side encryption with QKMS (SSE-KMS) | No | String |
| x-amz-checksum-crc32 | This header is returned when using the CRC32 checksum algorithm to verify object integrity | No | String |
| x-amz-checksum-crc32c | This header is returned when using the CRC32C checksum algorithm to verify object integrity | No | String |
| x-amz-checksum-sha1 | This header is returned when using the SHA-1 checksum algorithm to verify object integrity | No | String |
| x-amz-checksum-sha256 | This header is returned when using the SHA-256 checksum algorithm to verify object integrity | No | String |
| x-amz-request-charged | If present, indicates that the requester was successfully charged for the request. Valid values: requester | No | String |
| x-amz-object-size | The size of the object in bytes. This value is only present if you append to an object | No | String |
| x-amz-checksum-type | Specifies the checksum type of the object. For PutObject uploads, the value is always FULL_OBJECT. Valid values: COMPOSITE | FULL_OBJECT | No | String |
Special Errors
| Error Code | Description |
|---|---|
| NoSuchBucket | The specified bucket does not exist |
| InvalidDigest | The Content-MD5 you specified did not match what we received |
| BadDigest | The Content-MD5 you specified was invalid |
| EntityTooLarge | Your proposed upload exceeds the maximum allowed object size |
| InvalidTag | The tag provided was not a valid tag. All tags must follow the tag format requirements |
| MissingContentLength | You must provide the Content-Length HTTP header |
| MissingRequestBodyError | Request body is empty |
| RequestTimeout | Your socket connection to the server was not read from or written to within the timeout period |
| 403 | Forbidden. Authentication failed or you do not have permission to add an object to the bucket |
Permissions
You must have the s3:PutObject permission on the bucket. Additional permissions may be required:
s3:PutObjectAcl- To set the object ACLs3:PutObjectTagging- To set object tagss3:PutObjectVersionAcl- To set ACL on a specific object version
Try It Out
Test PutObject
Add an object to a bucket.
Coming Soon
This feature is currently under development and will be available soon.