CopyObject
Creates a copy of an object that is already stored in QStorage.
Description
The CopyObject operation creates a copy of an object that is already stored in QStorage. A copy operation creates a new object with the same data and metadata as the source object, but with a different key name and/or destination bucket.
Permissions
You must have:
s3:GetObjectpermission on the source objects3:PutObjectpermission on the destination bucket
note
- The source object and destination must be in QStorage buckets.
- When copying an object, you can preserve all metadata (default) or specify new metadata.
- You cannot copy objects that are larger than 5 GB in size. For larger objects, you must use multipart upload operations.
- The source bucket and destination bucket must exist before you can copy an object.
- You can use SSE, but this means your uploaded data will be encrypted twice, once with the specified key, and again for storage.
Request Headers
| Name | Description | Required | Type |
|---|---|---|---|
| x-amz-copy-source | The name of the source bucket and key name of the source object, separated by a forward slash | Yes | text |
| x-amz-acl | The canned ACL to apply to the object. Valid Values: private | public-read | public-read-write | authenticated-read | bucket-owner-read | bucket-owner-full-control | No | text |
| x-amz-checksum-algorithm | Indicates the algorithm used to create the checksum for the object. Valid Values: CRC32 | CRC32C | SHA1 | SHA256 | No | text |
| x-amz-copy-source-if-match | Copy the object only if its entity tag (ETag) matches the specified tag | No | text |
| x-amz-copy-source-if-none-match | Copy the object only if its entity tag (ETag) is different from the specified tag | No | text |
| x-amz-copy-source-if-modified-since | Copy the object only if it has been modified since the specified time | No | text |
| x-amz-copy-source-if-unmodified-since | Copy the object only if it hasn't been modified since the specified time | No | text |
| x-amz-copy-source-server-side-encryption-customer-algorithm | Specifies the algorithm to use when decrypting the source object. Must be used with x-amz-copy-source-server-side-encryption-customer-key and x-amz-copy-source-server-side-encryption-customer-key-MD5 | No | text |
| x-amz-copy-source-server-side-encryption-customer-key | Specifies the customer-provided encryption key for decrypting the source object. Must be used with x-amz-copy-source-server-side-encryption-customer-algorithm and x-amz-copy-source-server-side-encryption-customer-key-MD5 | No | text |
| x-amz-copy-source-server-side-encryption-customer-key-MD5 | Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Must be used with x-amz-copy-source-server-side-encryption-customer-algorithm and x-amz-copy-source-server-side-encryption-customer-key | No | text |
| x-amz-metadata-directive | Specifies whether to copy the metadata from the source object or replace it with metadata provided in the request Valid values: COPY | REPLACE | No | text |
| x-amz-server-side-encryption | Specifies server-side encryption algorithm to use for the destination object Valid values: AES256 | verenc | No | text |
| x-amz-server-side-encryption-customer-algorithm | Specifies the algorithm to use to when encrypting the destination object. Must be used with x-amz-server-side-encryption-customer-key and x-amz-server-side-encryption-customer-key-MD5 | No | text |
| x-amz-server-side-encryption-customer-key | Specifies the customer-provided encryption key for encrypting the destination object. Must be used with x-amz-server-side-encryption-customer-algorithm and x-amz-server-side-encryption-customer-key-MD5 | No | text |
| x-amz-server-side-encryption-customer-key-MD5 | Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Must be used with x-amz-server-side-encryption-customer-algorithm and x-amz-server-side-encryption-customer-key | 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-expected-bucket-owner | The account ID of the expected destination bucket owner | No | text |
| x-amz-source-expected-bucket-owner | The account ID of the expected source bucket owner | No | text |
| x-amz-request-payer | Confirms that the requester knows that they will be charged for the request. Required for Requester Pays buckets. | No | text |
| x-amz-object-lock-retain-until-date | The date and time when the Object Lock retention period expires. Must be formatted as a timestamp in ISO 8601 format. | No | text |
| x-amz-object-lock-mode | The Object Lock mode that you want to apply to the copied object. Valid Values: GOVERNANCE | COMPLIANCE | No | text |
| x-amz-object-lock-legal-hold | Specifies whether you want to apply a legal hold to the copied object. Valid Values: ON | OFF | No | text |
| x-amz-server-side-encryption-aws-kms-key-id | The ID of the symmetric encryption key to use for object encryption. Must be used with x-amz-server-side-encryption=verenc. | No | text |
| x-amz-server-side-encryption-bucket-key-enabled | Specifies whether QStorage should use an S3 Bucket Key for object encryption. Valid values: true | false | No | text |
| x-amz-server-side-encryption-context | Specifies the encryption context to use for object encryption. Must be base64-encoded and must be used with x-amz-server-side-encryption=verenc. | 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-tagging-directive | Specifies whether to copy the tag-set from the source object or replace it with tags provided in the request. Valid Values: COPY | REPLACE | No | text |
| x-amz-website-redirect-location | If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. | No | text |
Request URI Parameters
This operation does not use URI parameters.
Request Body
This operation does not have a request body.
Request Syntax
PUT /{ObjectKey} HTTP/1.1
Host: {BucketName}.qstorage.quilibrium.com
x-amz-copy-source: {SourceBucket}/{SourceObjectKey}
x-amz-copy-source-if-match: {ETag}
x-amz-copy-source-if-none-match: {ETag}
x-amz-copy-source-if-modified-since: {TimeStamp}
x-amz-copy-source-if-unmodified-since: {TimeStamp}
x-amz-metadata-directive: COPY | REPLACE
x-amz-expected-bucket-owner: {OwnerAccountId}
x-amz-source-expected-bucket-owner: {SourceOwnerAccountId}
Values in italics indicate user input and should be replaced with actual values.
Response Headers
| Name | Description | Required | Type |
|---|---|---|---|
| x-amz-id-2 | An identifier for the request | No | String |
| x-amz-request-id | A unique identifier for the request | No | String |
| x-amz-version-id | Version ID of the newly created copy | No | String |
| x-amz-copy-source-version-id | Version ID of the source object | No | String |
| x-amz-server-side-encryption | The server-side encryption algorithm used when storing this object in QStorage | No | String |
| x-amz-server-side-encryption-aws-kms-key-id | If x-amz-server-side-encryption is present and has the value of verenc, this indicates the ID of the Q KMS Key Management Service (KMS) symmetric encryption customer master 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, the response will include this header confirming 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, the response will include this header to provide round-trip message integrity verification of the customer-provided encryption key | No | String |
| x-amz-server-side-encryption-bucket-key-enabled | Indicates whether the copied object uses an S3 Bucket Key for server-side encryption with QKMS (SSE-KMS) | No | String |
Response Body Elements
| Name | Description | Required | Type |
|---|---|---|---|
| CopyObjectResult | Container for all response elements. See CopyObjectResult for details. | No | String |
| ETag | The entity tag (ETag) that represents the copied object. The ETag reflects only changes to the contents of an object, not its metadata. | No | String |
| LastModified | The date and time at which the copied object was last modified. | No | String |
| ChecksumCRC32 | The base64-encoded, 32-bit CRC32 checksum of the object. This will only be present if it was uploaded with the object. | No | String |
| ChecksumCRC32C | The base64-encoded, 32-bit CRC32C checksum of the object. This will only be present if it was uploaded with the object. | No | String |
| ChecksumCRC64NVME | The base64-encoded, 64-bit CRC64 checksum of the object computed using the NVME format. This will only be present if it was uploaded with the object. | No | String |
| ChecksumSHA1 | The base64-encoded, 160-bit SHA-1 digest of the object. This will only be present if it was uploaded with the object. | No | String |
| ChecksumSHA256 | The base64-encoded, 256-bit SHA-256 digest of the object. This will only be present if it was uploaded with the object. | No | String |
| ChecksumType | The algorithm that was used to create the checksum for the object. | No | String |
Special Errors
| Error Code | Description |
|---|---|
| NoSuchBucket | The specified bucket does not exist |
| NoSuchKey | The specified source object does not exist |
| InvalidRequest | The specified copy source is not supported |
| EntityTooLarge | The source object is too large to copy using a single operation |
| 403 | Forbidden. Authentication failed or you do not have permission to copy the object |
Examples
Example 1: Copy an object
PUT /destination.txt HTTP/1.1
Host: destination-bucket.qstorage.quilibrium.com
x-amz-copy-source: source-bucket/source.txt
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}"
<?xml version="1.0" encoding="UTF-8"?>
<CopyObjectResult>
<LastModified>2024-03-01T12:00:00.000Z</LastModified>
<ETag>"7778aef83f66abc1fa1e8477f296d394"</ETag>
</CopyObjectResult>
Values in italics indicate variable response values.
Example 2: Copy an object and replace its metadata
PUT /destination.txt HTTP/1.1
Host: destination-bucket.qstorage.quilibrium.com
x-amz-copy-source: source-bucket/source.txt
x-amz-metadata-directive: REPLACE
x-amz-meta-title: New Document
x-amz-meta-author: Jane Doe
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}"
<?xml version="1.0" encoding="UTF-8"?>
<CopyObjectResult>
<LastModified>2024-03-01T12:00:00.000Z</LastModified>
<ETag>"7778aef83f66abc1fa1e8477f296d394"</ETag>
</CopyObjectResult>
Values in italics indicate variable response values.
Try It Out
Test CopyObject
Create a copy of an existing object in QStorage.
Coming Soon
This feature is currently under development and will be available soon.