Copy an object
To copy an object, you make aPUT request that is scoped to the new bucket andobject name and you specify the source object with thex-goog-copy-sourcerequest header. To copy an object to itself you must use thex-goog-metadata-directive header with a value ofREPLACE and you mustspecify any object metadata for the copied object in your request.
If any of the conditional copy headers fail to match the condition you specifyyou will get a412 PreconditionFailed status code and the body of the error response will havePreconditionFailed in theCode element.
Query string parameters
This request does not typically include query string parameters.
Seesigned URL query string parameters for information on the parametersyou include when creating and usingsigned URLs.
Request headers
In addition tocommon request headers, thefollowing can be used.
| Header | Description | Required |
|---|---|---|
Content-Encoding | The compression algorithm that was used to compress the object you are uploading. | No |
Content-Disposition | A header you can set on an object that specifies presentational information about how the object data is to be transmitted. | No |
x-goog-acl | The predefined ACL that you want to apply to the object. Do not use if you are using theacl query string parameter to apply ACLs. | No |
x-goog-custom-time | A user-specified date and time. | No |
x-goog-encryption-kms-key-name | Thecustomer-managed encryption key to use to encrypt the copied object. | No |
x-goog-metadata-directive | The instructions for handling metadata during a copy operation. Can beCOPY orREPLACE. The default value isCOPY. | No |
x-goog-meta- | An extension header that can be used to store additional metadata that is not provided by the other fields. | No |
x-goog-object-lock-mode | Mode of the object'sretention configuration. If this header is specified, | No |
| A date and time represented inRFC 3339 UTC format that determines the time until which the object is retained as immutable. If this header is specified, | No |
x-goog-copy-source | The bucket/object path to the object you want to copy. For example,/travel-maps/paris.jpg. | Yes |
x-goog-copy-source-generation | Thegeneration number of the object you want to copy. | No |
x-goog-copy-source-if-generation-match | A generation number. If the generation number you specify matches the generation number of the source object, then the source object is copied. | No |
x-goog-copy-source-if-metageneration-match | A metageneration number. If the metageneration number you specify matches the metageneration number of the source object, then the object is copied. | No |
x-goog-copy-source-if-match | An ETag. If the ETag you specify matches the ETag of the source object, then the source object is copied. | No |
x-goog-copy-source-if-none-match | An ETag. If the ETag you specify does not match the Etag of the source object, then the object is copied. | No |
x-goog-copy-source-if-modified-since | A date and time. If the date and time you specify is earlier than theLast-Modified date of the source object, then the object is copied. | No |
x-goog-copy-source-if-unmodified-since | A date and time. If the date and time you specify is later than theLast-Modified date of the source object, then the object is copied. | No |
To copy an object encrypted by acustomer-supplied encryption key, use theheaders listed on the Encryption page in your request.
Request body elements
This request does not include an XML document in the request body.
Request syntax
The following syntax applies to PUT Object requests that use thex-goog-copy-source request header and the related conditional copyrequest headers.
PUT /OBJECT_NAME HTTP/1.1Host:BUCKET_NAME.storage.googleapis.comDate:DATEContent-Length:REQUEST_BODY_LENGTHContent-Type:MIME_TYPEAuthorization:AUTHENTICATION_STRINGx-goog-copy-source: /BUCKET_NAME/OBJECT_NAMEx-goog-copy-source-if-match:ETAGx-goog-copy-source-if-none-match:ETAGx-goog-copy-source-if-unmodified-since:DATEx-goog-copy-source-if-modified-since:DATEx-goog-metadata-directive: COPY | REPLACE
Response headers
The request can return a variety of response headers depending on the request headers you use.
Response body elements
The following response elements are returned when you use thex-goog-copy-source request header or any of the related conditionalcopy request headers.
| Element | Description |
|---|---|
| CopyObjectResult | Container for copy information. |
| ETag | The ETag of the newly-copied object. |
| LastModified | The date and time that the source object was last modified prior to the current copy operation. |
Example
The following sample uses thex-goog-copy-source request header tocopy an object named paris.jpg from a bucket named travel-maps to a bucketnamed city-maps.
Request
PUT /paris.jpg HTTP/1.1Host: city-maps.storage.googleapis.comDate: Fri, 23 Jul 2010 21:27:36 GMTContent-Length: 0x-goog-copy-source: travel-maps/paris.jpgAuthorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
Response
HTTP/1.1 200 OKETag: "9930c6204b2f14e1a4496569dc200186"Date: Fri, 23 Jul 2010 21:27:37 GMTExpires: Mon, 01 Jan 1990 00:00:00 GMTCache-Control: no-cache, no-store, must-revalidateContent-Length: 175Content-Type: text/html<?xml version='1.0' encoding='UTF-8'?><CopyObjectResult> <LastModified>2010-06-17T16:18:08.291Z</LastModified> <ETag>"9930c6204b2f14e1a4496569dc200186"</ETag></CopyObjectResult>
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-02-19 UTC.