Yandex Cloud
  • Services
  • Solutions
  • Why Yandex Cloud
  • Blog
  • Pricing
  • Documentation
  • Contact us
Get started
Language / Region
Yandex project
© 2023 Yandex.Cloud LLC
Yandex Object Storage
  • Getting started
  • Step-by-step instructions
    • All instructions
    • Buckets
      • Creating a bucket
      • Deleting a bucket
      • Limiting the maximum size of a bucket
      • Allowing public access to a bucket
      • Bucket encryption
      • Managing object lifecycles
      • Managing CORS configurations
      • Access policy management
      • Managing bucket versioning
      • Editing the ACL of a bucket
      • Enabling logging
      • Object lock management
    • Objects
      • Uploading an object
      • Getting information about an object
      • Downloading an object
      • Restoring an object's version
      • Getting a public link to an object
      • Configuring an object lock
      • Deleting an object
      • Deleting all objects
      • Deleting a partially uploaded object
      • Editing an object ACL
    • Static website hosting
      • Hosting setup
      • Support for your own domain
      • Support for multiple domain names
      • Configuring HTTPS
  • Tutorials
    • Getting object query statistics with S3 Select
    • Getting website traffic statistics with S3 Select
    • Generating a billing report with resource break-down using S3 Select
    • Server-side encryption
    • Integrating an L7 load balancer with the CDN and Object Storage
    • Blue-green and canary deployment of service versions
    • Analyzing logs in DataLens
    • Using initialization scripts to configure GeeseFS in Yandex Data Proc
    • Mounting a bucket as a disk on Windows
    • Migrating data from Yandex Data Streams using Yandex Data Transfer
  • Concepts
    • Overview
    • Bucket
    • Objects
    • Bucket versioning
    • Object locks
    • Encryption
    • Object lifecycles
    • CORS
    • Static website hosting
    • Pre-signed URLs
    • Multipart upload
    • Access control lists (ACLs)
    • Bucket Policy
    • Uploading files via an HTML form
    • Storage class
    • Logging actions with a bucket
    • Backups
    • TLS protocol
    • S3 Select query language
    • Quotas and limits
  • Tools
    • All tools
    • Console clients
      • AWS CLI
      • S3cmd
    • File browsers
      • CyberDuck
      • WinSCP
    • SDK
      • AWS SDK for Java
      • Python SDK (boto)
      • AWS SDK for .NET
      • AWS SDK for C++
      • AWS SDK for PHP
      • AWS SDK for Go
    • FUSE
      • GeeseFS
      • s3fs
      • goofys
    • FTP
      • Docker container for (S)FTP(S)
  • API reference
    • REST (Amazon S3-compatible)
      • How to use the API
      • Signing requests
      • REST
        • All services and methods
        • Bucket
          • All methods
          • create
          • getBucketEncryption
          • getMeta
          • listObjects
          • listBuckets
          • deleteBucket
          • deleteBucketEncryption
          • putBucketEncryption
          • putBucketVersioning
          • getBucketVersioning
          • putBucketLogging
          • getBucketLogging
          • listObjectVersions
          • putObjectLockConfiguration
          • getObjectLockConfiguration
        • Object
          • All methods
          • upload
          • get
          • copy
          • getObjectMeta
          • delete
          • deleteMultipleObjects
          • options
          • selectObjectContent
          • putObjectRetention
          • putObjectLegalHold
          • getObjectRetention
          • getObjectLegalHold
        • Multipart upload
          • General multipart upload procedure
          • startUpload
          • uploadPart
          • copyPart
          • listParts
          • abortUpload
          • completeUpload
          • listUploads
        • Static Website Hosting
          • All methods
          • upload
          • get
          • delete
          • Static website response codes
        • CORS
          • All methods
          • XML structure of CORS configuration
          • upload
          • get
          • delete
        • Lifecycles
          • All methods
          • XML structure of lifecycle configuration
          • upload
          • get
          • delete
        • ACL
          • All methods
          • XML structure of ACL configuration
          • objectGetAcl
          • objectPutAcl
          • bucketGetAcl
          • bucketPutAcl
        • Bucket Policy
          • All methods
          • GetBucketPolicy
          • PutBucketPolicy
          • DeleteBucketPolicy
          • Data schema
          • Actions
          • Conditions
        • Common request headers
        • Common response headers
        • Responses
    • gRPC and REST
      • Authentication in the API
      • gRPC
        • Overview
        • BucketService
        • OperationService
      • REST
        • Overview
        • Bucket
          • Overview
          • create
          • delete
          • deleteHTTPSConfig
          • get
          • getHTTPSConfig
          • getStats
          • list
          • setHTTPSConfig
          • update
  • Access management
  • Pricing policy
    • Current pricing policy
    • Archive
      • Before January 1, 2019
      • From January 1 to March 1, 2019
  • Questions and answers
  1. API reference
  2. REST (Amazon S3-compatible)
  3. REST
  4. Object
  5. copy

copy method

Written by
Yandex Cloud
  • Request
    • Path parameters
    • Headers
  • Response
    • Headers
    • Response codes
    • Data schema

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 pass 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 necessary, 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.

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 /.

For example, X-Amz-Copy-Source: /source_bucket/sourceObject.

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 value of the header, for example: /mybucket/image.png?versionId=0005E4A66AD990A4. If you do not specify a version ID, the most recent version of the object will be copied.

You should also use the necessary common request headers.

Use the headers from the table below if you need to change the default behavior of the copy method.

Header Description
X-Amz-Metadata-Directive Metadata copy mode.

If the header value is COPY, the object metadata is copied and all the X-Amz-Meta-* headers are ignored. Default behavior of the copy method.

If the header value is REPLACE, the object metadata is replaced with the metadata specified in the request.

The X-Amz-Storage-Class header is not copied; add it to the request if necessary.
X-Amz-Copy-Source-If-Match Condition for copying an object.

If the object's ETag matches the one specified in the header, the object is copied.

If the condition is not met, Object Storage returns error 412.

Can be used with the X-Amz-Copy-Source-If-Unmodified-Since.
X-Amz-Copy-Source-If-None-Match Condition for copying an object.

If the object's ETag does not match the one specified in the header, the object is copied.

If the condition is not met, Object Storage returns error 412.

Can be used with the X-Amz-Copy-Source-If-Unmodified-Since.
X-Amz-Copy-Source-If-Unmodified-Since Condition for copying an object.

The object is copied if it has not been modified since the specified time.

If the condition is not met, Object Storage returns error 412.

Can be used with the X-Amz-Copy-Source-If-Match.
X-Amz-Copy-Source-If-Modified-Since Condition for copying an object.

The object is copied if it has been modified since the specified time.

If the condition is not met, Object Storage returns error 412.

Can be used with the X-Amz-Copy-Source-If-None-Match.
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.

Possible values:
  • STANDARD: Standard storage.
  • COLD, STANDARD_IA, or NEARLINE: Cold storage.
  • ICE or GLACIER: Ice storage.
If the header isn't specified, the object is stored in the storage defined in the bucket settings.
X-Amz-Object-Lock-Mode

Type of retention put on the object (if the bucket is versioned and object lock is enabled in it):

  • GOVERNANCE: An object lock with a predefined retention period that can be managed.
  • COMPLIANCE: An object lock with a predefined retention period with strict compliance.

On an object version, you can put only retention (the headers X-Amz-Object-Lock-Mode and X-Amz-Object-Lock-Retain-Until-Date), only legal hold (X-Amz-Object-Lock-Legal-Hold), or both at the same time. For more information about their combined use, see Object lock types.

X-Amz-Object-Lock-Retain-Until-Date Date and time until which the object is retained, specified in any format described in the HTTP standard. For example, Mon, 12 Dec 2022 09:00:00 GMT. Specified only together 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):

  • ON: Enabled.
  • OFF: Disabled.

On an object version, you can put only retention (the headers X-Amz-Object-Lock-Mode and X-Amz-Object-Lock-Retain-Until-Date), only legal hold (X-Amz-Object-Lock-Legal-Hold), or both at the same time. For more information about their combined use, see Object lock types.

X-Amz-Meta-* User-defined metadata.

Object Storage transforms all headers starting with X-Amz-Meta- as follows: X-Amz-Meta-foo-bar_baz → X-Amz-Meta-Foo-Bar_baz.

Total user-defined header size must not exceed 2 KB. The size of user-defined data is determined as the length of the UTF-8 encoded string. Both the headers and their values are included in the size.

Headers that have X-Amz-Metadata-Directive: COPY 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.

Possible values:
  • STANDARD: Standard storage.
  • COLD: Cold storage.
  • ICE: Ice storage.

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 Contains response elements.

Path: /CopyObjectResult.
ETag ETag of the resulting object. Because metadata is not taken into account when calculating the ETag, the ETag of the source and resulting objects must match.

Path: /CopyObjectResult/ETag.
LastModified Date when the object was last modified.

Path: /CopyObjectResult/LastModified.

Was the article helpful?

Language / Region
Yandex project
© 2023 Yandex.Cloud LLC
In this article:
  • Request
  • Path parameters
  • Headers
  • Response
  • Headers
  • Response codes
  • Data schema