Copy Blob

Copy Blob

Collapse All

Copy Blob

The Copy Blob operation copies a blob to a destination within the storage account. The Copy Blob operation copies the entire committed blob.

Request

The Copy Blob request may be constructed as follows. Replace myaccount with the name of your storage account, mycontainer with the name of your container, and myblob with the name of your destination blob.

Method	Request URI	HTTP Version
PUT	http://myaccount.blob.core.windows.net/mycontainer/myblob	HTTP/1.1

Development Storage URI

When making a request against development storage, specify the local hostname and Blob service port as 127.0.0.1:10000, followed by the development storage account name:

Method	Request URI	HTTP Version
PUT	`http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob`	HTTP/1.1

For more information, see About Development Storage and Differences Between Development Storage and Windows Azure Storage Services.

URI Parameters

None.

Request Headers

The following table describes required and optional request headers.

Request Header	Description
Authorization	Required. Specifies the authentication scheme, account name, and signature. For more information, see Authentication Schemes.
Date or x-ms-date	Required. Specifies the Coordinated Universal Time (UTC) for the request. For more information, see Authentication Schemes.
x-ms-version	Required for all authenticated requests. For more information, see Storage Service Versioning.
x-ms-copy-source:name	Required. Specifies the name of the source blob, in one of the following formats: Blob in named container: `/accountName/containerName/blobName` Snapshot in named container: `/accountName/containerName/blobName?snapshot=<DateTime>` Blob in root container: `/accountName/blobName` Snapshot in root container: `/accountName/blobName?snapshot=<DateTime>`
x-ms-meta-name:value	Optional. Specifies a user-defined name-value pair associated with the blob. If no name-value pairs are specified, the operation will copy the source blob metadata to the destination blob. If one or more name-value pairs are specified, the destination blob is created with the specified metadata, and metadata is not copied from the source blob. Note that beginning with version 2009-09-19, metadata names must adhere to the naming rules for C# identifiers. See Naming Containers, Blobs, and Metadata for more information.
x-ms-source-if-modified-since	Optional. A DateTime value. Specify this conditional header to copy the blob only if the source blob has been modified since the specified date/time. If the source blob has not been modified, the Blob service returns status code 412 (Precondition Failed).
x-ms-source-if-unmodified-since	Optional. A DateTime value. Specify this conditional header to copy the blob only if the source blob has not been modified since the specified date/time. If the source blob has been modified, the Blob service returns status code 412 (Precondition Failed).
x-ms-source-if-match	Optional. An ETag value. Specify this conditional header to copy the source blob only if its ETag matches the value specified. If the ETag values do not match, the Blob service returns status code 412 (Precondition Failed).
x-ms-source-if-none-match	Optional. An ETag value. Specify this conditional header to copy the blob only if its ETag does not match the value specified. If the values are identical, the Blob service returns status code 412 (Precondition Failed).
If-Modified-Since	Optional. A DateTime value. Specify this conditional header to copy the blob only if the destination blob has been modified since the specified date/time. If the destination blob has not been modified, the Blob service returns status code 412 (Precondition Failed).
If-Unmodified-Since	Optional. A DateTime value. Specify this conditional header to copy the blob only if the destination blob has not been modified since the specified date/time. If the destination blob has not been modified, the Blob service returns status code 412 (Precondition Failed).
If-Match	Optional. An ETag value. Specify an ETag value for this conditional header to copy the blob only if the specified ETag value matches the ETag value for an existing destination blob. If the ETag for the destination blob does not match the ETag specified for If-Match, the Blob service returns status code 412 (Precondition Failed).
If-None-Match	Optional. An ETag value, or the wildcard character (). Specify an ETag value for this conditional header to copy the blob only if the specified ETag value does not match the ETag value for the destination blob. Specify the wildcard character () to perform the operation only if the destination blob does not exist. If the specified condition isn't met, the Blob service returns status code 412 (Precondition Failed).
x-ms-lease-id:<ID>	Required if the destination blob has an active lease. The lease ID specified for this header must match the lease ID stored for the destination blob. If the request does not include the lease ID or it is not valid, the operation fails with status code 412 (Precondition Failed). If this header is specified and the destination blob does not currently have an active lease, the operation will also fail with status code 412 (Precondition Failed).
x-ms-source-lease-id: <ID>	Optional. Specify this header to perform the Copy Blob operation only if the lease ID given matches the lease ID stored for the source blob. If this header is specified and the source blob does not currently have an active lease, the operation will also fail with status code 412 (Precondition Failed).

Request Body

None.

Response

The response includes an HTTP status code and a set of response headers.

Status Code

A successful operation returns status code 201 (Created).

For information about status codes, see Status and Error Codes.

Response Headers

The response for this operation includes the following headers. The response may also include additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.

Response header	Description
ETag	Returns the ETag for the destination blob.
Last-Modified	Returns the date/time that the copy operation to the destination blob completed.
x-ms-request-id	This header uniquely identifies the request that was made and can be used for troubleshooting the request. For more information, see Troubleshooting API Operations.
x-ms-version	Indicates the version of the Blob service used to execute the request. This header is returned for requests made against version 2009-09-19 and later.
Date	A UTC date/time value generated by the service that indicates the time at which the response was initiated.

Authorization

Only the account owner may call this operation.

Remarks

The source blob for a copy operation may be a block blob or a page blob, or a snapshot of either. If the destination blob already exists, it must be of the same blob type as the source blob.

Copying a source blob always copies the entire blob; copying a range of bytes or a set of blocks is not supported.

A Copy Blob operation can take any of the following forms:

You can copy a source blob to a destination blob with a different name from that of the source blob. The destination blob can be an existing blob, or a new blob created by the copy operation.
You can copy a source blob to a destination blob with the same name, effectively replacing the source blob. Such a copy operation removes any uncommitted blocks and overwrites the blob's metadata.
You can copy a snapshot over its base blob. By promoting a snapshot to the position of the base blob, you can restore an earlier version of a blob.
You can copy a snapshot to a destination blob with a different name. The resulting destination blob is a writeable blob and not a snapshot.

Note
When you a copy a source blob to a destination blob with a different blob name, you use additional storage resources for the new blob, so the copy operation results in a charge against the storage account’s capacity usage for those additional resources. However, if the source and destination blob are the same, no additional charge is incurred. When you promote a snapshot to replace its base blob, the snapshot and base blob are subsequently identical. They share blocks or pages, so the copy operation does not result in an additional charge against the storage account's capacity usage. However, if you copy a snapshot to a destination blob with a different name, an additional charge is incurred for the storage resources used by the new blob that results. Two blobs with different names cannot share blocks or pages even if they are identical.

Note

When you a copy a source blob to a destination blob with a different blob name, you use additional storage resources for the new blob, so the copy operation results in a charge against the storage account’s capacity usage for those additional resources. However, if the source and destination blob are the same, no additional charge is incurred.

When you promote a snapshot to replace its base blob, the snapshot and base blob are subsequently identical. They share blocks or pages, so the copy operation does not result in an additional charge against the storage account's capacity usage. However, if you copy a snapshot to a destination blob with a different name, an additional charge is incurred for the storage resources used by the new blob that results. Two blobs with different names cannot share blocks or pages even if they are identical.

Copying Blob Properties and Metadata

When a blob is copied, the following system properties are copied to the destination blob with the same values:

Content-Type
Content-Encoding
Content-Language
Content-Length
Cache-Control
Content-MD5
x-ms-blob-sequence-number (for page blobs only)

The source blob's committed block list is also copied to the destination blob, if the blob is a block blob. Any uncommitted blocks are not copied.

The destination blob is always the same size as the source blob, so the value of the Content-Length header for the destination blob will be the same as that for the source blob.

You can specify one or more new metadata values for the destination blob by specifying the x-ms-meta-name:value header on the request. If this header is not specified, the metadata associated with the source blob is copied to the destination blob.

When the source blob and destination blob are the same, Copy Blob removes any uncommitted blocks. If metadata is specified in this case, the existing metadata is overwritten with the new metadata.

Specifying Conditional Headers

You can specify conditional headers on the request to copy the blob only if a condition is met. If the specified condition is not met, the blob is not copied, and the Blob service returns status code 412 (Precondition Failed), along with additional error information that indicates whether the unmet condition was specified for the source blob or for the destination blob.

Copying a Leased Blob

If the destination blob has an active lease, you must specify a valid lease ID for the active lease in order to copy the blob.

If the source blob has an active lease, you can optionally specify the lease ID for the source blob to copy the source blob conditionally. In this case, the source blob will be copied only if the lease ID for the source blob matches that specified on the request.

Copying a blob does not affect an existing lease on the destination blob. The destination blob's lease is maintained, whether you are copying a blob to a destination blob with a different name from the source, copying the blob to a destination blob with the same name as the source, or copying a snapshot over its base blob.

Copying Snapshots

When a source blob is copied, any snapshots of the source blob are not copied to the destination. When a destination blob is overwritten with a copy, any snapshots associated with the destination blob stay intact under its name.

You can perform a copy operation to promote a snapshot blob over its base blob. In this way you can restore an earlier version of a blob. The snapshot remains, but its source is overwritten with a copy that can be both read and written.

Concepts

Authentication Schemes
Status and Error Codes
Blob Service Error Codes