PageBlobClient.StartCopyIncremental Method

Definition

Namespace:

Azure.Storage.Blobs.Specialized

Assembly:

Azure.Storage.Blobs.dll

Package:

Azure.Storage.Blobs v12.19.1

Source:

PageBlobClient.cs

The StartCopyIncremental(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 GetProperties(BlobRequestConditions, CancellationToken) to determine if the copy has completed.

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

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

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

Public Overridable Function StartCopyIncremental (sourceUri As Uri, snapshot As String, Optional conditions As PageBlobRequestConditions = Nothing, Optional cancellationToken As CancellationToken = Nothing) As 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

CopyFromUriOperation

A CopyFromUriOperation referencing 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 GetProperties(BlobRequestConditions, CancellationToken), GetBlobs(BlobTraits, BlobStates, String, CancellationToken), and GetBlobsByHierarchy(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 GetProperties(BlobRequestConditions, CancellationToken), StartCopyIncremental(Uri, String, PageBlobRequestConditions, CancellationToken), and Delete(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 GetProperties(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 GetProperties(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 StartCopyIncremental(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 GetAllPageRanges(GetPageRangesOptions, CancellationToken) call on the source blob snapshot with prevSnapshot set to the most recently copied snapshot. Therefore, the same restrictions on GetAllPageRanges(GetPageRangesOptions, CancellationToken) apply to StartCopyIncremental(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.UploadPages(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.StartCopyFromUri(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 StartCopyIncremental(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 GetAllPageRangesDiff(GetPageRangesDiffOptions, CancellationToken) call on the snapshot to compare it to the previous snapshot.