PageBlobClient.StartCopyIncrementalAsync Method

Definition

Namespace:

Azure.Storage.Blobs.Specialized

Assembly:

Azure.Storage.Blobs.dll

Package:

Azure.Storage.Blobs v12.19.1

Source:

PageBlobClient.cs

The StartCopyIncrementalAsync(Uri, String, PageBlobRequestConditions, CancellationToken) operation starts copying a snapshot of the sourceUri page blob to this page blob. The snapshot is copied such that only the differential changes between the previously copied snapshot are transferred to the destination. The copied snapshots are complete copies of the original snapshot and can be read or copied from as usual. You can check the Azure.Storage.Blobs.Models.BlobProperties.CopyStatus returned from the GetPropertiesAsync(BlobRequestConditions, CancellationToken) to determine if thecopy has completed.

For more information, see Incremental Copy Blob and Back up Azure unmanaged VM disks with incremental snapshots.

public virtual System.Threading.Tasks.Task<Azure.Storage.Blobs.Models.CopyFromUriOperation> StartCopyIncrementalAsync (Uri sourceUri, string snapshot, Azure.Storage.Blobs.Models.PageBlobRequestConditions conditions = default, System.Threading.CancellationToken cancellationToken = default);

abstract member StartCopyIncrementalAsync : Uri * string * Azure.Storage.Blobs.Models.PageBlobRequestConditions * System.Threading.CancellationToken -> System.Threading.Tasks.Task<Azure.Storage.Blobs.Models.CopyFromUriOperation>
override this.StartCopyIncrementalAsync : Uri * string * Azure.Storage.Blobs.Models.PageBlobRequestConditions * System.Threading.CancellationToken -> System.Threading.Tasks.Task<Azure.Storage.Blobs.Models.CopyFromUriOperation>

Public Overridable Function StartCopyIncrementalAsync (sourceUri As Uri, snapshot As String, Optional conditions As PageBlobRequestConditions = Nothing, Optional cancellationToken As CancellationToken = Nothing) As Task(Of CopyFromUriOperation)

Parameters

sourceUri

Uri

Specifies the to the source page blob as a Uri up to 2 KB in length. The source blob must either be public or must be authenticated via a shared access signature.

snapshot

String

The name of a snapshot to start copying from sourceUri.

conditions

PageBlobRequestConditions

Optional PageBlobRequestConditions to add conditions on the incremental copy into this page blob.

cancellationToken

CancellationToken

Optional CancellationToken to propagate notifications that the operation should be cancelled.

Returns

Task<CopyFromUriOperation>

A CopyFromUriOperation describing the state of the incremental copy operation.

Remarks

A RequestFailedException will be thrown if a failure occurs.

The destination of an incremental copy must either not exist, or must have been created with a previous incremental copy from the same source blob. Once created, the destination blob is permanently associated with the source and may only be used for incremental copies.

The GetPropertiesAsync(BlobRequestConditions, CancellationToken), GetBlobsAsync(BlobTraits, BlobStates, String, CancellationToken), and GetBlobsByHierarchyAsync(BlobTraits, BlobStates, String, String, CancellationToken) operations indicate whether the blob is an incremental copy blob created in this way. Incremental copy blobs may not be downloaded directly. The only supported operations are GetPropertiesAsync(BlobRequestConditions, CancellationToken), StartCopyIncrementalAsync(Uri, String, PageBlobRequestConditions, CancellationToken), and DeleteAsync(DeleteSnapshotsOption, BlobRequestConditions, CancellationToken). The copied snapshots may be read and deleted as usual.

An incremental copy is performed asynchronously on the service and must be polled for completion. You can poll GetPropertiesAsync(BlobRequestConditions, CancellationToken) and check Azure.Storage.Blobs.Models.BlobProperties.CopyStatus to determine when the copy has completed. When the copy completes, the destination blob will contain a new snapshot. The GetPropertiesAsync(BlobRequestConditions, CancellationToken) operation returns the snapshot time of the newly created snapshot.

The first time an incremental copy is performed on a destination blob, a new blob is created with a snapshot that is fully copied from the source. Each subsequent call to StartCopyIncrementalAsync(Uri, String, PageBlobRequestConditions, CancellationToken) will create a new snapshot by copying only the differential changes from the previously copied snapshot. The differential changes are computed on the server by issuing a GetAllPageRangesAsync(GetPageRangesOptions, CancellationToken) call on the source blob snapshot with prevSnapshot set to the most recently copied snapshot. Therefore, the same restrictions on GetAllPageRangesAsync(GetPageRangesOptions, CancellationToken) apply to StartCopyIncrementalAsync(Uri, String, PageBlobRequestConditions, CancellationToken). Specifically, snapshots must be copied in ascending order and if the source blob is recreated using Azure.Storage.Blobs.Specialized.PageBlobClient.UploadPagesAsync(System.IO.Stream,System.Int64,System.Byte[],Azure.Storage.Blobs.Models.PageBlobRequestConditions,System.IProgress{System.Int64},System.Threading.CancellationToken) or Azure.Storage.Blobs.Specialized.BlobBaseClient.StartCopyFromUriAsync(System.Uri,System.Collections.Generic.IDictionary{System.String,System.String},System.Nullable{Azure.Storage.Blobs.Models.AccessTier},Azure.Storage.Blobs.Models.BlobRequestConditions,Azure.Storage.Blobs.Models.BlobRequestConditions,System.Nullable{Azure.Storage.Blobs.Models.RehydratePriority},System.Threading.CancellationToken) then StartCopyIncrementalAsync(Uri, String, PageBlobRequestConditions, CancellationToken) on new snapshots will fail.

The additional storage space consumed by the copied snapshot is the size of the differential data transferred during the copy. This can be determined by performing a GetAllPageRangesDiffAsync(GetPageRangesDiffOptions, CancellationToken) call on the snapshot to compare it to the previous snapshot.