Exportera (0) Skriv ut
Visa allt
EN
Det här innehållet finns inte tillgängligt på ditt språk men här finns den engelska versionen,

Copy Blob

Updated: November 26, 2013

The Copy Blob operation copies a blob to a destination within the storage account. In version 2012-02-12 and newer, the source for a Copy Blob operation can be a committed blob in any Azure storage account.

noteNote
Only storage accounts created on or after June 7th, 2012 allow the Copy Blob operation to copy from another storage account.

The Copy Blob request may be constructed as follows. HTTPS is recommended. 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. Beginning with version 2013-08-15, you may specify a shared access signature for the destination blob.

 

  PUT Method Request URI HTTP Version

https://myaccount.blob.core.windows.net/mycontainer/myblob

HTTP/1.1

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

 

  PUT Method Request URI HTTP Version

http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob

HTTP/1.1

For more information, see Using the Azure Storage Emulator for Development and Testing.

The following additional parameters may be specified on the request URI.

 

Parameter Description

timeout

Optional. The timeout parameter is expressed in seconds. For more information, see Setting Timeouts for Blob Service Operations.

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 for the Azure Storage Services.

Date or x-ms-date

Required. Specifies the Coordinated Universal Time (UTC) for the request. For more information, see Authentication for the Azure Storage Services.

x-ms-version

Required for all authenticated requests. For more information, see Versioning for the Azure Storage Services.

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 and Referencing 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 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-copy-source:name

Required. Specifies the name of the source blob.

In version 2012-02-12 and newer, this value is a URL up to 2 KB in length that specifies a blob. A source blob in the same account can be private, but a blob in another account must be public or accept credentials included in this URL, such as a shared access signature. Only storage accounts created on or after June 7th, 2012 allow the Copy Blob operation to copy from another storage account. Microsoft recommends using HTTPS when possible. Examples:

  • https://myaccount.blob.core.windows.net/mycontainer/myblob

  • https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>

In versions before 2012-02-12, blobs can only be copied within the same account, and a source name can use these 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-lease-id:<ID>

Required if the destination blob has an active lease. The lease ID specified for this header must match the lease ID of 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).

In version 2012-02-12 and newer, this value must specify an active, infinite lease for a leased blob. A finite-duration lease ID fails with 412 (Precondition Failed).

x-ms-source-lease-id: <ID>

Optional, versions before 2012-02-12 (unsupported in 2012-02-12 and newer). Specify this header to perform the Copy Blob operation only if the lease ID given matches the active lease ID of 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).

x-ms-client-request-id

Optional. Provides a client-generated, opaque value with a 1 KB character limit that is recorded in the analytics logs when storage analytics logging is enabled. Using this header is highly recommended for correlating client-side activities with requests received by the server. For more information, see About Storage Analytics Logging and Azure Logging: Using Logs to Track Storage Requests.

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

In version 2012-02-12 and newer, a successful operation returns status code 202 (Accepted).

In versions before 2012-02-12, a successful operation returns status code 201 (Created).

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

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

In version 2012-02-12 and newer, if the copy is complete, contains the ETag of the destination blob. If the copy isn’t complete, contains the ETag of the empty blob created at the start of the copy.

In versions before 2012-02-12, returns the ETag for the destination blob.

In version 2011-08-18 and newer, the ETag value will be in quotes.

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.

x-ms-copy-id: <id>

Version 2012-02-12 and newer. String identifier for this copy operation. Use with Get Blob or Get Blob Properties to check the status of this copy operation, or pass to Abort Copy Blob to abort a pending copy.

x-ms-copy-status: <success | pending>

Version 2012-02-12 and newer. State of the copy operation, with these values:

  • success: the copy completed successfully.

  • pending: the copy is in progress.

The following is a sample response for a request to copy a blob:

Response Status:
HTTP/1.1 202 Accepted

Response Headers: 
Last-Modified: Thu, 09 Feb 2012 23:30:19 GMT 
ETag: "0x8CEB669D794AFE2"
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: cc6b209a-b593-4be1-a38a-dde7c106f402
x-ms-version: 2012-02-12
x-ms-copy-id: 1f812371-a41d-49e6-b123-f4b542e851c5
x-ms-copy-status: pending
Date: Thu, 09 Feb 2012 23:30:18 GMT

This operation can be called by the account owner. For requests made against version 2013-08-15 and later, a shared access signature that has permission to write to the destination blob or its container is supported for copy operations within the same account. Note that the shared access signature specified on the request applies only to the destination blob. Access to the source blob is authorized separately, as described in the details for the request header x-ms-copy-source.

In version 2012-02-12 and newer, the Copy Blob operation can complete asynchronously. This operation returns a copy ID you can use to check or abort the copy operation. The Blob service copies blobs on a best-effort basis.

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. Any existing destination blob will be overwritten. The destination blob cannot be modified while a copy operation is in progress.

Multiple pending Copy Blob operations within an account might be processed sequentially. A destination blob can only have one outstanding copy blob operation. In other words, a blob cannot be the destination for multiple pending Copy Blob operations. An attempt to Copy Blob to a destination blob that already has a copy pending fails with status code 409 (Conflict).

Only storage accounts created on or after June 7th, 2012 allow the Copy Blob operation to copy from another storage account. An attempt to copy from another storage account to an account created before June 7th, 2012 fails with status code 400 (Bad Request).

The Copy Blob operation always copies the entire source blob; copying a range of bytes or 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. The destination blob can be an existing blob of the same blob type (block or page), or can be 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.

When copying from a page blob, the Blob service creates a destination page blob of the source blob’s length, initially containing all zeroes. Then the source page ranges are enumerated, and non-empty ranges are copied. When copying from a block blob, all of the committed blocks and their block IDs will be copied. Uncommitted blocks will not be copied. For a block blob, the Blob service creates a committed blob of zero length before returning from this operation. For either blob type, you can call Get Blob or Get Blob Properties on the destination blob to check the status of the copy operation. The final blob will be committed when the copy completes.

When the source of a copy operation provides ETags, if there are any changes to the source while the copy is in progress, the copy will fail. An attempt to change the destination blob while a copy is in progress will fail with 409 Conflict. If the destination blob has an infinite lease, the lease ID must be passed to Copy Blob. Finite-duration leases are not allowed.

The ETag for a block blob changes when the Copy Blob operation is initiated and when the copy finishes. The ETag for a page blob changes when the Copy Blob operation is initiated, and continues to change frequently during the copy. The contents of a block blob are only visible using a GET after the full copy completes.

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

  • Content-Disposition

  • 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 matches that for the source 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.

Copying a Leased Blob

The Copy Blob operation only reads from the source blob so the lease state of the source blob does not matter. However, the Copy Blob operation saves the ETag of the source blob when the copy is initiated. If the ETag value changes before the copy completes, the copy fails. You can prevent changes to the source blob by leasing it during the copy operation.

If the destination blob has an active infinite lease, you must specify its lease ID in the call to the Copy Blob operation. If the lease you specify is an active finite-duration lease, this call fails with a status code 412 (Precondition Failed). While the copy is pending, any lease operation on the destination blob will fail with status code 409 (Conflict). An infinite lease on the destination blob is locked in this way during the copy operation whether you are copying to a destination blob with a different name from the source, copying to a destination blob with the same name as the source, or promoting a snapshot over its base blob. If the client specifies a lease ID on a blob that does not yet exist, the Blob service will return status code 412 (Precondition Failed) for requests made against version 2013-08-15 and later; for prior versions the Blob service will return status code 201 (Created).

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 destination is overwritten with a copy that can be both read and written.

Working with a Pending Copy (version 2012-02-12 and newer)

The Copy Blob operation completes the copy asynchronously. Use the following table to determine the next step based on the status code returned by Copy Blob:

 

Status Code Meaning

202 (Accepted), x-ms-copy-status: success

Copy completed successfully.

202 (Accepted), x-ms-copy-status: pending

500 or 503

Copy has not completed. Poll the destination blob using Get Blob Properties to examine the x-ms-copy-status until copy completes or fails.

4xx, 500, or 503

Copy failed.

During and after a Copy Blob operation, the properties of the destination blob contain the copy ID of the Copy Blob operation and URL of the source blob. When the copy completes, the Blob service writes the time and outcome value (success, failed, or aborted) to the destination blob properties. If the operation failed, the x-ms-copy-status-description header contains an error detail string.

A pending Copy Blob operation has a 2 week timeout. A copy attempt that has not completed after 2 weeks times out and leaves an empty blob with the x-ms-copy-status field set to failed and the x-ms-copy-status-description set to 500 (OperationCancelled). Intermittent, non-fatal errors that can occur during a copy might impede progress of the copy but not cause it to fail. In these cases, x-ms-copy-status-description describes the intermittent errors.

Any attempt to modify or snapshot the destination blob during the copy will fail with 409 (Conflict) Copy Blob in Progress.

If you call the Abort Copy Blob operation, you will see a x-ms-copy-status:aborted header and the destination blob will have intact metadata and a blob length of zero bytes. You can repeat the original call to Copy Blob to try the copy again.

Billing

The destination account of a Copy Blob operation is charged for one transaction to initiate the copy, and also incurs one transaction for each request to abort or request the status of the copy operation.

When the source blob is in another account, the source account incurs transaction costs. In addition, if the source and destination accounts reside in different regions (e.g., US North and US South), bandwidth used to transfer the request is charged to the source storage account as egress. Egress between accounts within the same region is free.

When you copy a source blob to a destination blob with a different name within the same account, 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 name are the same within the same account (for example, when you promote a snapshot to its base blob), no additional charge is incurred other than the extra copy metadata stored in version 2012-02-12 and newer.

When you promote a snapshot to replace its base blob, the snapshot and base blob become 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. For more information about snapshot cost scenarios, see Understanding How Snapshots Accrue Charges.

Visa:
© 2014 Microsoft