CopyObject
Creates a copy of an object that is already stored in Petabox
All copy requests must be authenticated. Additionally, you must have read access to the source object and write access to the destination bucket. Both the Region that you want to copy the object from and the Region that you want to copy the object to must be enabled for your account.
A copy request might return an error when Petabox receives the copy request or while Petabox is copying the files. If the error occurs before the copy action starts, you receive a standard Petabox error. If the error occurs during the copy operation, the error response is embedded in the 200 OK response. This means that a 200 OK response can contain either a success or an error. If you call the S3 API directly, make sure to design your application to parse the contents of the response and handle it appropriately. If you use AWS SDKs, SDKs handle this condition. The SDKs detect the embedded error and apply error handling per your configuration settings (including automatically retrying the request as appropriate). If the condition persists, the SDKs throws an exception (or, for the SDKs that don't use exceptions, they return the error).
If the copy is successful, you receive a response with information about the copied object.
The copy request charge is based on the storage class and Region that you specify for the destination object.
Important
Petabox transfer acceleration does not support cross-Region copies. If you request a cross-Region copy using a transfer acceleration endpoint, you get a 400 Bad Request error.
Metadata
When copying an object, you can preserve all metadata (the default) or specify new metadata. However, the access control list (ACL) is not preserved and is set to private for the user making the request. To override the default ACL setting, specify a new ACL when generating a copy request.
To specify whether you want the object metadata copied from the source object or replaced with metadata provided in the request, you can optionally add the x-amz-metadata-directive header. When you grant permissions, you can use the s3:x-amz-metadata-directive condition key to enforce certain metadata behavior when objects are uploaded.
x-amz-copy-source-if Headers
To only copy an object under certain conditions, such as whether the Etag matches or whether the object was modified before or after a specified date, use the following request parameters:
x-amz-copy-source-if-matchx-amz-copy-source-if-none-matchx-amz-copy-source-if-unmodified-sincex-amz-copy-source-if-modified-since
If both the x-amz-copy-source-if-match and x-amz-copy-source-if-unmodified-since headers are present in the request and evaluate as follows, Petabox returns 200 OK and copies the data:
x-amz-copy-source-if-matchcondition evaluates to truex-amz-copy-source-if-unmodified-sincecondition evaluates to false
If both the x-amz-copy-source-if-none-match and x-amz-copy-source-if-modified-since headers are present in the request and evaluate as follows, Petabox returns the 412 Precondition Failed response code:
x-amz-copy-source-if-none-matchcondition evaluates to falsex-amz-copy-source-if-modified-sincecondition evaluates to true
Server-side encryption
Petabox automatically encrypts all new objects that are copied to an S3 bucket. Petabox for now supports only Server-side encryption with Petabox S3 managed keys. Other methods of SSE are not supported yet.
Access Control List (ACL)-Specific Request Headers
When copying an object, you can optionally use headers to grant ACL-based permissions. By default, all objects are private. Only the owner has full access control. When adding a new object, you can grant permissions to individual Petabox accounts or to predefined groups that are defined by Petabox. These permissions are then added to the ACL on the object.
If the bucket that you're copying objects to uses the bucket owner enforced setting for S3 Object Ownership, ACLs are disabled and no longer affect permissions. Buckets that use this setting only accept PUT requests that don't specify an ACL or PUT requests that specify bucket owner full control ACLs, such as the bucket-owner-full-control canned ACL or an equivalent form of this ACL expressed in the XML format.
Storage Class Options
You can use the CopyObject action to change the storage class of an object that is already stored in Petabox by using the StorageClass parameter.
Versioning
By default, x-amz-copy-source header identifies the current version of an object to copy. If the current version is a delete marker, Petabox behaves as if the object was deleted. To copy a different version, use the versionId subresource.
If you enable versioning on the target bucket, Petabox generates a unique version ID for the object being copied. This version ID is different from the version ID of the source object. Petabox returns the version ID of the copied object in the x-amz-version-id response header in the response.
If you do not enable versioning or suspend it on the target bucket, the version ID that Petabox generates is always null.
If the source object's storage class is GLACIER, you must restore a copy of this object before you can use it as a source object for the copy operation.
Request Syntax
URI Request Parameters
The request uses the following URI parameters.
Bucket
The name of the destination bucket.
Required: Yes
Cache-Control
Specifies caching behavior along the request/reply chain.
Content-Disposition
Specifies presentational information for the object.
Content-Encoding
Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
Content-Language
The language the content is in.
Content-Type
A standard MIME type describing the format of the object data.
Expires
The date and time at which the object is no longer cacheable.
Key
The key of the destination object.
Length Constraints: Minimum length of 1.
Required: Yes
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
x-amz-copy-source
Specifies the source object for the copy operation. You specify the value in one of two formats, depending on whether you want to access the source object through an access point:
For objects not accessed through an access point, specify the name of the source bucket and the key of the source object, separated by a slash (/). For example, to copy the object
reports/january.pdffrom the bucketexamplebucket, useexamplebucket/reports/january.pdf. The value must be URL-encoded.\
To copy a specific version of an object, append ?versionId=<version-id> to the value (for example, examplebucket/reports/january.pdf?versionId=QUpfdndhfd8438MNFDN93jdnJFkdmqnh893). If you don't specify a version ID, Petabox copies the latest version of the source object.
Pattern: \/.+\/.+
Required: Yes
x-amz-copy-source-if-match
Copies the object if its entity tag (ETag) matches the specified tag.
x-amz-copy-source-if-modified-since
Copies the object if it has been modified since the specified time.
x-amz-copy-source-if-none-match
Copies the object if its entity tag (ETag) is different than the specified ETag.
x-amz-copy-source-if-unmodified-since
Copies the object if it hasn't been modified since the specified time.
x-amz-copy-source-server-side-encryption-customer-algorithm
Specifies the algorithm to use when decrypting the source object (for example, AES256).
x-amz-copy-source-server-side-encryption-customer-key
Not supported for the moment.
x-amz-copy-source-server-side-encryption-customer-key-MD5
Not supported for the moment.
x-amz-expected-bucket-owner
The account ID of the expected destination bucket owner. If the destination bucket is owned by a different account, the request fails with the HTTP status code 403 Forbidden (access denied).
x-amz-grant-full-control
Gives the grantee READ, READ_ACP, and WRITE_ACP permissions on the object.
x-amz-grant-read
Allows grantee to read the object data and its metadata.
x-amz-grant-read-acp
Allows grantee to read the object ACL.
x-amz-grant-write-acp
Allows grantee to write the ACL for the applicable object.
x-amz-metadata-directive
Specifies whether the metadata is copied from the source object or replaced with metadata provided in the request.
Valid Values: COPY | REPLACE
x-amz-object-lock-legal-hold
Specifies whether you want to apply a legal hold to the copied object.
Valid Values: ON | OFF
x-amz-object-lock-mode
The Object Lock mode that you want to apply to the copied object.
Valid Values: GOVERNANCE | COMPLIANCE
x-amz-object-lock-retain-until-date
The date and time when you want the copied object's Object Lock to expire.
x-amz-request-payer
Confirms that the requester knows that they will be charged for the request. Bucket owners need not specify this parameter in their requests.
Valid Values: requester
x-amz-server-side-encryption
The server-side encryption algorithm used when storing this object in Petabox (for example, AES256, aws:kms).
Valid Values: AES256 | aws:kms
x-amz-server-side-encryption-aws-kms-key-id
Not supported for the moment.
x-amz-server-side-encryption-bucket-key-enabled
Not supported for the moment.
x-amz-server-side-encryption-context
Not supported for the moment.
x-amz-server-side-encryption-customer-algorithm
Specifies the algorithm to use to when encrypting the object (for example, AES256).
x-amz-server-side-encryption-customer-key
Not supported for the moment.
x-amz-server-side-encryption-customer-key-MD5
Not supported for the moment.
x-amz-source-expected-bucket-owner
The account ID of the expected source bucket owner. If the source bucket is owned by a different account, the request fails with the HTTP status code 403 Forbidden (access denied).
x-amz-storage-class
By default, Petabox uses the STANDARD Storage Class to store newly created objects. The STANDARD storage class provides high durability and high availability. Depending on performance needs, you can specify a different Storage Class.
Valid Values: STANDARD | REDUCED_REDUNDANCY | STANDARD_IA | ONEZONE_IA | INTELLIGENT_TIERING | GLACIER | DEEP_ARCHIVE | OUTPOSTS | GLACIER_IR
x-amz-tagging
The tag-set for the object destination object this value must be used in conjunction with the TaggingDirective. The tag-set must be encoded as URL Query parameters.
x-amz-tagging-directive
Specifies whether the object tag-set are copied from the source object or replaced with tag-set provided in the request.
Valid Values: COPY | REPLACE
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. Petabox stores the value of this header in the object metadata. This value is unique to each object and is not copied when using the x-amz-metadata-directive header. Instead, you may opt to provide this header in combination with the directive.
Request Body
The request does not have a request body.
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The response returns the following HTTP headers.
x-amz-copy-source-version-id
Version of the copied object in the destination bucket.
x-amz-expiration
If the object expiration is configured, the response includes this header.
x-amz-request-charged
If present, indicates that the requester was successfully charged for the request.
Valid Values: requester
x-amz-server-side-encryption
The server-side encryption algorithm used when storing this object in Petabox (for example, AES256, aws:kms).
Valid Values: AES256 | aws:kms
x-amz-server-side-encryption-aws-kms-key-id
Not supported for the moment.
x-amz-server-side-encryption-bucket-key-enabled
Not supported for the moment.
x-amz-server-side-encryption-context
Not supported for the moment.
x-amz-server-side-encryption-customer-algorithm
Not supported for the moment.
x-amz-server-side-encryption-customer-key-MD5
Not supported for the moment.
x-amz-version-id
Version ID of the newly created copy.
The following data is returned in XML format by the service.
CopyObjectResult
Root level tag for the CopyObjectResult parameters.
Required: Yes
ETag
Returns the ETag of the new object. The ETag reflects only changes to the contents of an object, not its metadata.
Type: String
LastModified
Creation date of the object.
Type: Timestamp
Examples
Sample Request
This example copies my-image.jpg into the bucket bucket, with the key name my-second-image.jpg.
Sample Response
This example illustrates one usage of CopyObject.
Sample Request: Copying a Specified Version of an Object
The following request copies the my-image.jpg key with the specified version ID, copies it into the bucket bucket, and gives it the my-second-image.jpg key.
Success Response: Copying a versioned object into a version-enabled bucket
The following response shows that an object was copied into a target bucket where versioning is enabled.
Success Response: Copying a versioned object into a version-suspended bucket
The following response shows that an object was copied into a target bucket where versioning is suspended. The parameter VersionId does not appear.
Last updated