To copy an object, you make a PUT request that is scoped to the new bucket and
object name and you specify the source object with the x-goog-copy-source
request header.
If you are using the PUT Object method to copy an object, you must have READ
permission on the source object and you must have WRITE or FULL_CONTROL
permission on the bucket to which you are copying the object. To copy an object
to itself you must use the x-goog-metadata-directive header and you must
specify REPLACE, which replaces all of the source object's metadata with
whatever metadata you specify in the request. The x-goog-metadata-directive
header also lets you copy the source object's metadata to the newly-created
object as part of the copy operation. If you copy the metadata, the ACLs are not
copied and the default object ACLs are applied to the new object. You can apply
different ACLs during a copy operation by using the x-goog-acl request
header. Also, during a copy operation the request body must be empty.
If any of the conditional copy headers fail to match the condition you specify
you will get a 412 Precondition
Failed status code and the body of the error response will have
PreconditionFailed in the Code element.
Query string parameters
| Parameter | Description | Required |
|---|---|---|
Expires |
Used for Signed URLs. | No |
GoogleAccessId |
Used for Signed URLs. | No |
Signature |
Used for Signed URLs. | No |
Request headers
In addition to common request headers, the following 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 bucket. Do not use if you are using the acl query string parameter to apply ACLs. |
No |
x-goog-metadata-directive |
The instructions for handling metadata during a copy operation. Can be COPY or REPLACE. The default value is COPY. |
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-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 |
The generation number of the object you want to copy. | 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 the Last-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 the Last-Modified date of the source object, then the object is copied. |
No |
x-goog-encryption-kms-key-name |
The customer-managed encryption key to use to encrypt the copied object. | No |
To copy an object encrypted by a customer-supplied encryption key, use the headers 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 the x-goog-
copy-source request header and the related conditional copy request
headers.
PUT /<object> HTTP/1.1 Host: <bucket>.storage.googleapis.com Date: <date> Content-Length: <request body length> Content-Type: <MIME type> Authorization: <authentication string> x-goog-copy-source: </bucket/object> x-goog-copy-source-if-match: <ETag> x-goog-copy-source-if-none-match: <ETag> x-goog-copy-source-if-unmodified-since: <date> x-goog-copy-source-if-modified-since: <date> x-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 the x-goog-copy-
source request header or any of the related conditional copy 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 the x-goog-copy-source request header to
copy an object named paris.jpg from a bucket named travel-maps to a bucket
named city-maps.
Request
PUT /paris.jpg HTTP/1.1 Host: city-maps.storage.googleapis.com Date: Fri, 23 Jul 2010 21:27:36 GMT Content-Length: 0 x-goog-copy-source: travel-maps/paris.jpg Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
Response
HTTP/1.1 200 OK ETag: "9930c6204b2f14e1a4496569dc200186" Date: Fri, 23 Jul 2010 21:27:37 GMT Expires: Mon, 01 Jan 1990 00:00:00 GMT Cache-Control: no-cache, no-store, must-revalidate Content-Length: 175 Content-Type: text/html <?xml version='1.0' encoding='UTF-8'?> <CopyObjectResult> <LastModified>2010-06-17T16:18:08.291Z</LastModified> <ETag>"9930c6204b2f14e1a4496569dc200186"</ETag> </CopyObjectResult>