Copy method
Creates a copy of an object stored in Object Storage. Objects up to 5 GB can be copied with a single copy operation. For objects larger than 5 GB, use the copyPart operation.
To specify the copy source, use the X-Amz-Copy-Source header. The copy request must not provide any data other than headers.
Note
Object Storage does not lock an object for writing and can simultaneously accept multiple requests that copy objects to the same resulting object. After all the requests are completed, the resulting object is the one whose copy operation was run last.
The object metadata is copied along with the object. If required, you can change the metadata by explicitly setting the appropriate headers.
You can also use headers to:
- Change an object's storage class.
- Add conditions for copying an object.
- Put a lock on an object (if the bucket is versioned and object lock is enabled).
The user must have permission to read the source object and write data to the resulting bucket.
For more information on getting started with the API and the general request format, see How to use the S3 API.
Request
PUT /{bucket}/{key} HTTP/2
Path parameters
| Parameter | Description |
|---|---|
bucket |
Name of the resulting bucket. |
key |
Key of the resulting object. ID that the object is saved with in Object Storage. |
Headers
Required headers are listed in the table below.
| Header | Description |
|---|---|
X-Amz-Copy-Source |
The name of the bucket and the key of the object to copy, separated by the / character.Example: rc1b-cfazv1db********.mdb.yandexcloud.net port=6432.If the bucket has versioning enabled, you can copy a specific version of the object. To do this, specify the object version ID in the header by adding ?versionId=<version-id> to the header value, e.g., /mybucket/image.png?versionId=0005E4A66AD990A4. If you do not specify a version ID, the most recent version of the object will be copied. |
Make sure to also use the required common request headers.
Use the headers from the table below if you need to change the way the copy method works by default.
| Header | Description |
|---|---|
X-Amz-Metadata-Directive |
Metadata copying mode. If the header value is COPY, the object metadata is copied and all X-Amz-Meta-* headers are ignored. This is how the copy method works by default.If the header value is REPLACE, the object metadata is replaced with that provided in the request.The X-Amz-Storage-Class header is not copied; you have to add it to the request manually, if required. |
X-Amz-Copy-Source-If-Match |
Object copying condition. If ETag of an object is the same as in the header, the object is copied.If the condition is not met, Object Storage returns the 412 error. You can use it with the X-Amz-Copy-Source-If-Unmodified-Since header. |
X-Amz-Copy-Source-If-None-Match |
Object copying condition. If ETag of an object is not the same as in the header, the object is copied.If the condition is not met, Object Storage returns the 412 error. You can use it with the X-Amz-Copy-Source-If-Modified-Since header. |
X-Amz-Copy-Source-If-Unmodified-Since |
Object copying condition. The object is copied if it has not been modified since the specified time. If the condition is not met, Object Storage returns the 412 error. You can use it with the X-Amz-Copy-Source-If-Match header. |
X-Amz-Copy-Source-If-Modified-Since |
Object copying condition. The object is copied if it has been modified since the specified time. If the condition is not met, Object Storage returns the 412 error. You can use it with the X-Amz-Copy-Source-If-None-Match header. |
X-Amz-Server-Side-Encryption |
Default encryption algorithm used for new objects. |
X-Amz-Server-Side-Encryption-Aws-Kms-Key-Id |
ID of the KMS key used by default to encrypt new objects. |
X-Amz-Storage-Class |
Object storage class. It may have any of the following values:
|
X-Amz-Object-Lock-Mode |
Type of retention put on the object (if the bucket is versioned and object lock is enabled in it):
For an object version, you can use only retention ( |
X-Amz-Object-Lock-Retain-Until-Date |
Date and time of end of retention in any format described in the HTTP standard, e.g., Mon, 12 Dec 2022 09:00:00 GMT. Specify it only with the X-Amz-Object-Lock-Mode header. |
X-Amz-Object-Lock-Legal-Hold |
Type of legal hold put on the object (if the bucket is versioned and object lock is enabled in it):
For an object version, you can use only retention ( |
X-Amz-Meta-* |
User-defined object metadata. Object Storage сonverts all headers starting with X-Amz-Meta- according to the following rule: X-Amz-Meta-foo-bar_baz → X-Amz-Meta-Foo-Bar_baz.The total size of user-defined headers must not exceed 2 KB. The size of user-defined data is determined as the length of the UTF-8 encoded string. The header names and their values are included when calculating the size. With X-Amz-Metadata-Directive: COPY, these headers are ignored. |
Response
Headers
A response may contain common response headers and the headers listed in the table below.
| Header | Description |
|---|---|
X-Amz-Storage-Class |
Object storage class. It may have the following values:
|
Response codes
For a list of possible responses, see Responses.
Data schema
<CopyObjectResult>
<LastModified>2019-02-15T14:32:00</LastModified>
<ETag>"9bgh7535f2734ec974343yuc93985328"</ETag>
</CopyObjectResult>
| Element | Description |
|---|---|
CopyObjectResult |
It contains response elements. Path: /CopyObjectResult. |
ETag |
ETag of the resulting object. Since metadata does not count when calculating ETag, the source and resulting object ETags must match.>Path: /CopyObjectResult/ETag. |
LastModified |
Date and time of the object’s last update. Path: /CopyObjectResult/LastModified. |