Aracılığıyla paylaş

Veri Taşıma kitaplığıyla veri aktarımı

Azure Depolama Veri Taşıma kitaplığı, blobların ve dosyaların yüksek performanslı karşıya yüklenmesi, indirilmesi ve kopyalanması için tasarlanmış bir platformlar arası açık kaynak kitaplığıdır. Veri Taşıma kitaplığı, .NET için Azure Depolama istemci kitaplığında bulunmayan kullanışlı yöntemler sağlar. Bu yöntemler paralel işlemlerin sayısını ayarlamanıza, aktarım ilerlemesini izlemenize, iptal edilen aktarımı sürdürmenize ve daha fazlasını yapmanızı sağlar.

Veri Taşıma kitaplığı yalnızca .NET için kullanılabilir ve yalnızca Azure Blob Depolama ve Azure Dosyalar destekler. Veri Taşıma kitaplığını kullanıp kullanmayacağınız konusunda karar verirken bu sınırlamaları ve bilinen diğer sorunları göz önünde bulundurmanız gerekir.

Kodu eski Microsoft.Azure.Storage.DataMovement kitaplığından (sürüm 2.X.X) geçerli Azure.Storage.DataMovement kitaplığına (sürüm 12.X.X) geçiriyorsanız Geçiş kılavuzuna bakın.

API başvuru belgeleri | Kaynak kodu | Paket (NuGet) | Örnekler: Bloblar / Files.Shares

Önkoşullar

Ortamınızı ayarlama

Var olan bir projeniz yoksa, bu bölümde bir projenin .NET için Azure Blob Depolama istemci kitaplığıyla çalışacak şekilde nasıl ayarlanacağı gösterilir. Adımlar arasında paket yükleme, yönergeler ekleme using ve yetkili istemci nesnesi oluşturma yer alır.

Paketleri yükleme

Proje dizininizden komutunu kullanarak Azure Depolama Veri Taşıma istemci kitaplığına ve Azure Identity istemci kitaplığına yönelik dotnet add package paketleri yükleyin. Azure hizmetlerine parolasız bağlantılar için Azure.Identity paketi gereklidir.

dotnet add package Azure.Storage.DataMovement
dotnet add package Azure.Storage.DataMovement.Blobs
dotnet add package Azure.Identity

Azure Dosyalar uzantı kitaplığıyla çalışmak için Azure.Storage.DataMovement.Files.Shares paketini yükleyin:

dotnet add package Azure.Storage.DataMovement.Files.Shares

"using Yönergeleri Ekle"

Bu makaledeki kod örneklerini çalıştırmak için aşağıdaki using yönergeleri ekleyin:

using Azure;
using Azure.Core;
using Azure.Identity;
using Azure.Storage.DataMovement;
using Azure.Storage.DataMovement.Blobs;

Azure Dosyalar için uzantı kitaplığını kullanıyorsanız aşağıdaki using yönergeyi ekleyin:

using Azure.Storage.DataMovement.Files.Shares;

Yetkilendirme

Yetkilendirme mekanizması, karşıya yükleme, indirme veya kopyalama işlemlerini gerçekleştirmek için gerekli izinlere sahip olmalıdır. Microsoft Entra Id ile yetkilendirme için (önerilir), Azure RBAC yerleşik rolü Depolama Blob Verileri Katkıda Bulunanı veya üzeri gerekir.

Veri Taşıma kitaplığı hakkında

Azure Depolama Veri Taşıma kitaplığı ortak bir istemci kitaplığı ile Azure Blob Depolama ve Azure Dosyalar için uzantı kitaplıklarından oluşur. Ortak kitaplık veri aktarımı için temel işlevselliği sağlarken, uzantı kitaplıkları Blob Depolama ve Azure Dosyalar özgü işlevler sağlar. Daha fazla bilgi edinmek için aşağıdaki kaynaklara bakın:

TransferManager Nesne oluşturma

TransferManager , karşıya yükleme, indirme ve kopyalama dahil olmak üzere tüm aktarım türlerini başlatmak ve denetlemek için ana sınıftır. Bu bölümde, yerel bir TransferManager dosya sistemi, Blob Depolama veya Azure Dosyalar ile çalışacak bir nesne oluşturmayı öğreneceksiniz.

Not

Azure SDK istemci yönetimi için en iyi yöntem, bir istemciyi tekil olarak ele almaktır; bu da bir sınıfın aynı anda yalnızca bir nesnesi olduğu anlamına gelir. Belirli bir oluşturucu parametreleri veya istemci seçenekleri kümesi için bir istemcinin birden fazla örneğini tutmanız gerekmez.

Aşağıdaki kodda bir TransferManager nesnenin nasıl oluşturulacağı gösterilmektedir:

TransferManager transferManager = new(new TransferManagerOptions());

İsteğe bağlı olarak oluşturucuya bir TransferManagerOptions örneği sağlayabilirsiniz. Bu örnek, nesne tarafından TransferManager başlatılan tüm aktarımlara belirli yapılandırma seçeneklerini uygular. Aşağıdaki yapılandırma seçenekleri kullanılabilir:

  • CheckpointStoreOptions: İsteğe bağlı. Aktarımların sürdürülebilmesi için aktarım durumunu kaydetmek için kullanılan bir denetim noktası oluşturma seçeneklerini tanımlar.
  • Tanılama: Aktarım yöneticisi tanılama seçeneklerini alır.
  • ErrorHandling: İsteğe bağlı. Aktarım sırasında hataların nasıl işleneceğini tanımlar. Varsayılan StopOnAnyFailure değeridir.
  • MaximumConcurrency: Paralel aktarımda kullanılabilecek en fazla çalışan sayısı.
  • ProvidersForResuming: Aktarım yöneticisinin aktarıma devam etmede kullanması için kaynak sağlayıcıları. Kullanımda olan her bir depolama sağlayıcısı için bir sağlayıcı bekler. Daha fazla bilgi edinmek için bkz Mevcut bir aktarımı sürdürme.

StorageResource Nesne oluşturma

StorageResource , bloblar ve dosyalar dahil olmak üzere tüm depolama kaynakları için temel sınıftır. Nesne StorageResource oluşturmak için aşağıdaki sağlayıcı sınıflarından birini kullanın:

StorageResource Blob Depolama için nesne oluşturma

Aşağıdaki kod, Uri kullanarak StorageResource blob kapsayıcıları ve bloblar için bir nesnenin nasıl oluşturulacağını gösterir.

// Create a token credential
TokenCredential tokenCredential = new DefaultAzureCredential();

BlobsStorageResourceProvider blobsProvider = new(tokenCredential);

// Get a container resource
StorageResource container = await blobsProvider.FromContainerAsync(
    new Uri("http://<storage-account-name>.blob.core.windows.net/sample-container"));

// Get a block blob resource - default is block blob
StorageResource blockBlob = await blobsProvider.FromBlobAsync(
    new Uri("http://<storage-account-name>.blob.core.windows.net/sample-container/sample-block-blob"),
    new BlockBlobStorageResourceOptions());

// Use a similar approach to get a page blob or append blob resource

Azure.Storage.Blobs'tan StorageResourcebir istemci nesnesi kullanarak da nesne oluşturabilirsiniz.

// Create a token credential
TokenCredential tokenCredential = new DefaultAzureCredential();

BlobContainerClient blobContainerClient = new(
    new Uri("https://<storage-account-name>.blob.core.windows.net/sample-container"),
    tokenCredential);
StorageResource containerResource = BlobsStorageResourceProvider.FromClient(blobContainerClient);

BlockBlobClient blockBlobClient = blobContainerClient.GetBlockBlobClient("sample-block-blob");
StorageResource blockBlobResource = BlobsStorageResourceProvider.FromClient(blockBlobClient);

// Use a similar approach to get a page blob or append blob resource

Yeni bir aktarım başlat

Tüm aktarımların bir kaynak ve hedef belirtmesi gerekir. Hem kaynak hem de hedef tür StorageResource olabilir ve bu türler StorageResourceContainer veya StorageResourceItem olabilir. Belirli bir aktarım için kaynak ve hedef aynı türde olmalıdır. Örneğin, kaynak bir blob kapsayıcısıysa hedef bir blob kapsayıcısı olmalıdır.

Aşağıdaki yöntemi çağırarak yeni bir aktarım başlatabilirsiniz:

Bu yöntem, aktarımı temsil eden bir TransferOperation nesnesi döndürür. Aktarım ilerleme durumunu izlemek veya aktarım kimliğini almak için TransferOperation nesnesini kullanabilirsiniz. Aktarım kimliği, aktarımı sürdürmek veya aktarımı duraklatmak için gereken aktarım için benzersiz bir tanımlayıcıdır.

İsteğe bağlı olarak, StartTransferAsync veya ResumeTransferAsync öğesine belirli aktarıma ilişkin yapılandırma seçeneklerini uygulamak için bir TransferOptions örneği sağlayabilirsiniz. Aşağıdaki yapılandırma seçenekleri kullanılabilir:

  • CreationMode: Aktarım zaten var olan bir kaynakla karşılaştığında davranışı yapılandırır. Yeni bir aktarım başlatıldığında varsayılan olarak FailIfExists seçilir. Bir aktarımı sürdürürken varsayılan değerler farklılık gösterebilir. Aktarım başlatıldığında başarıyla numaralandırılan tüm kaynaklar için varsayılan CreationMode olarak kullanılan ilk değer kullanılır. Kalan tüm kaynaklar için normal varsayılan değer uygulanır.
  • InitialTransferSize: bayt cinsinden ilk aralık isteğinin boyutu. Bu sınırdan daha küçük tekli aktarım boyutları, tek bir istekle yüklenir veya indirilir. Bu sınırdan büyük aktarımlar, MaximumTransferChunkSize boyutunda öbekler halinde indirilme veya karşıya yüklenmeye devam eder. Varsayılan değer 32 MiB'dir. Bir aktarımı sürdürürken, varsayılan değer aktarım ilk başlatıldığında belirtilen değerdir.
  • MaximumTransferChunkSize: Öbekler halinde veri aktarırken her öbek için kullanılacak en büyük boyut. Varsayılan değer 4 MiB'dir. Bir aktarımı sürdürürken, varsayılan değer aktarım ilk başlatıldığında belirtilen değerdir.
  • ProgressHandlerOptions: İsteğe bağlı. ProgressHandler'ın davranışını değiştirme seçenekleri.

Örnek: Blob kapsayıcısına yerel dizin yükleme

Aşağıdaki kod örneği, yerel dizini blob kapsayıcısına yüklemek için yeni bir aktarımın nasıl başlatılacığını gösterir:

// Create a token credential
TokenCredential tokenCredential = new DefaultAzureCredential();

TransferManager transferManager = new(new TransferManagerOptions());

BlobsStorageResourceProvider blobsProvider = new(tokenCredential);

string localDirectoryPath = "C:/path/to/directory";
Uri blobContainerUri = new Uri("https://<storage-account-name>.blob.core.windows.net/sample-container");

TransferOperation transferOperation = await transferManager.StartTransferAsync(
    sourceResource: LocalFilesStorageResourceProvider.FromDirectory(localDirectoryPath),
    destinationResource: await blobsProvider.FromContainerAsync(blobContainerUri));
await transferOperation.WaitForCompletionAsync();

Örnek: Kapsayıcı veya blob kopyala

İki StorageResource örnek arasında kopyalamak için Veri Taşıma kitaplığını kullanabilirsiniz. Blob kaynakları için aktarım, sunucudan sunucuya kopyalama gerçekleştiren URL'den Blob Yerleştir işlemini kullanır.

Aşağıdaki kod örneği, bir kaynak blob kapsayıcısında yer alan tüm blobları hedef blob kapsayıcısına kopyalamak için yeni bir aktarım başlatmayı gösterir. Hedef kapsayıcının zaten mevcut olması gerekir. Bu örnekte, CreationMode'ıOverwriteIfExists. Özelliği uygulamanızın CreationMode gereksinimlerine göre ayarlayabilirsiniz.

Uri sourceContainerUri = new Uri("https://<storage-account-name>.blob.core.windows.net/source-container");
Uri destinationContainerUri = new Uri("https://<storage-account-name>.blob.core.windows.net/dest-container");

TransferOperation transferOperation = await transferManager.StartTransferAsync(
    sourceResource: await blobsProvider.FromContainerAsync(
        sourceContainerUri,
        new BlobStorageResourceContainerOptions()
        {
            BlobPrefix = "source/directory/prefix"
        }),
    destinationResource: await blobsProvider.FromContainerAsync(
        destinationContainerUri,
        new BlobStorageResourceContainerOptions()
        {
            // All source blobs are copied as a single type of destination blob
            // Defaults to block blob, if not specified
            BlobType = BlobType.Block,
            BlobPrefix = "destination/directory/prefix"
        }),
    transferOptions: new TransferOptions()
    {
        CreationMode = StorageResourceCreationMode.OverwriteIfExists,
    }
);
await transferOperation.WaitForCompletionAsync();

Aşağıdaki kod örneğinde, bir kaynak blobu hedef bloba kopyalamak için yeni bir aktarımın nasıl başlat başlayacağı gösterilmektedir. Bu örnekte, CreationMode'u OverwriteIfExists mevcutsa hedef blobun üzerine yazacak şekilde ayarladık. Özelliği uygulamanızın CreationMode gereksinimlerine göre ayarlayabilirsiniz.

Uri sourceBlobUri = new Uri(
    "https://<storage-account-name>.blob.core.windows.net/source-container/source-blob");
Uri destinationBlobUri = new Uri(
    "https://<storage-account-name>.blob.core.windows.net/dest-container/dest-blob");

TransferOperation transferOperation = await transferManager.StartTransferAsync(
    sourceResource: await blobsProvider.FromBlobAsync(sourceBlobUri),
    destinationResource: await blobsProvider.FromBlobAsync(destinationBlobUri, new BlockBlobStorageResourceOptions()),
    transferOptions: new TransferOptions()
    {
        CreationMode = StorageResourceCreationMode.OverwriteIfExists,
    }
);
await transferOperation.WaitForCompletionAsync();

Mevcut aktarımı sürdür

Aktarım ilerleme durumunu diske kalıcı hale getiren Veri Taşıma kitaplığı, tamamlanmadan önce başarısız olan veya başka bir şekilde iptal edilmiş veya duraklatılmış bir aktarımı sürdürmenize olanak tanır. Aktarımı sürdürmek için, nesnenin TransferManager kalıcı verilerden aktarımı yeniden birleştirebilen örneklerle StorageResourceProvider yapılandırılması gerekir. Sağlayıcıları belirtmek için TransferManagerOptionsProvidersForResumingkullanabilirsiniz.

Aşağıdaki kod örneği, yerel dosya sistemi ile Blob Depolama arasında aktarımı devam ettirebilen bir nesnenin nasıl başlatıldığını TransferManager gösterir:

// Create a token credential
TokenCredential tokenCredential = new DefaultAzureCredential();

TransferManager transferManager = new(new TransferManagerOptions()
{
    ProvidersForResuming = new List<StorageResourceProvider>()
    {
        new BlobsStorageResourceProvider(tokenCredential)
    }
});

Aktarımı sürdürmek için aşağıdaki yöntemi çağırın:

Sürdürmek istediğiniz aktarımın aktarım kimliğini belirtin. Aktarım kimliği, aktarım başlatıldığında nesnenin TransferOperation bir parçası olarak döndürülen aktarım için benzersiz bir tanımlayıcıdır. Aktarım kimliği değerini bilmiyorsanız aktarımı ve karşılık gelen kimliğini bulmak için TransferManager.GetTransfersAsync'i çağırabilirsiniz.

Aşağıdaki kod örneğinde aktarımın nasıl sürdürülür olduğu gösterilmektedir:

TransferOperation resumedTransfer = await transferManager.ResumeTransferAsync(transferId: ID);

Not

TransferCheckpointStoreOptions öğesinin bir parçası olarak ayarlandıysa, kalıcı aktarım verilerinin konumu varsayılan konumdan TransferManagerOptionsfarklıdır. Özel denetim noktası deposuyla kaydedilen aktarımları sürdürmek için, aktarımı sürdüren nesne için TransferManager aynı denetim noktası deposu seçeneklerini sağlamanız gerekir.

Aktarım ilerlemesini izleme

Aktarımlar, uygulamanızın gereksinimlerine bağlı olarak çeşitli mekanizmalar aracılığıyla izlenebilir ve gözlemlenebilir. Bu bölümde, nesnesini kullanarak aktarım ilerlemesini TransferOperation izlemeyi ve olayları kullanarak TransferOptions aktarımı izlemeyi öğreneceksiniz.

Örnek: Nesnesini kullanarak aktarım ilerleme durumunu TransferOperation izleme

TransferOperation nesnesi tarafından döndürülen StartTransferAsync yöntemini kullanarak aktarım ilerlemesini izleyebilirsiniz. Ayrıca, bir nesnenin tüm aktarımlarını listelemek için TransferManager.GetTransfersAsyncTransferManager.

Aşağıdaki kod örneği, tüm aktarımları yinelemeyi ve her aktarımın durumunu bir günlük dosyasına yazmayı gösterir:

async Task CheckTransfersAsync(TransferManager transferManager)
{
    await foreach (TransferOperation transfer in transferManager.GetTransfersAsync())
    {
        using StreamWriter logStream = File.AppendText("path/to/log/file");
        logStream.WriteLine(Enum.GetName(typeof(TransferState), transfer.Status.State));
    }
}

TransferStatus , aktarım işinin durumunu tanımlar. TransferStatus aşağıdaki özellikleri içerir:

Mülkiyet Türü Açıklama
HasCompletedSuccessfully Boolean Aktarım işleminin herhangi bir hata veya atlanan öğe olmadan başarıyla tamamlanmasını temsil eder.
HasFailedItems Boolean Aktarımda herhangi bir hata öğesi olup olmadığını temsil eder. olarak ayarlanırsa trueaktarımda en az bir hata öğesi vardır. olarak falseayarlanırsa aktarımda şu anda hiçbir hata yoktur.
HasSkippedItems Boolean Aktarımda atlanan öğe olup olmadığını temsil eder. true olarak ayarlanırsa, aktarımda en az bir atlanmış öğe vardır. false olarak ayarlandığında, aktarımda atlanmış öğe yoktur. TransferOptions.CreationMode içinde SkipIfExists etkinleştirilmediğinde, hiçbir öğenin atlanmaması mümkündür.
State TransferState Aktarımın sahip olabileceği hâl türlerini tanımlar. Ayrıntılar için bkz . TransferState .

Örnek: TransferOptions olaylarını kullanarak veri aktarım ilerlemesini izleme

TransferOptions sınıfı tarafından sağlanan olayları dinleyerek aktarım ilerleme durumunu izleyebilirsiniz. Örneği TransferOptions yöntemine StartTransferAsync geçirilir ve aktarım tamamlandığında, başarısız olduğunda, atlandığında veya durumu değiştirdiğinde tetiklenen olaylar sağlar.

Aşağıdaki kod örneği, TransferOptions kullanarak aktarım tamamlama olayını nasıl dinleyeceğinizi göstermektedir.

async Task<TransferOperation> ListenToTransfersAsync(
    TransferManager transferManager,
    StorageResource source,
    StorageResource destination)
{
    TransferOptions transferOptions = new();
    transferOptions.ItemTransferCompleted += (TransferItemCompletedEventArgs args) =>
    {
        using (StreamWriter logStream = File.AppendText("path/to/log/file"))
        {
            logStream.WriteLine($"File Completed Transfer: {args.Source.Uri.AbsoluteUri}");
        }
        return Task.CompletedTask;
    };
    return await transferManager.StartTransferAsync(
        source,
        destination,
        transferOptions);
}

için uzantı yöntemlerini kullanma BlobContainerClient

Azure.Storage.BlobsBlobContainerClient kullanan mevcut koda sahip uygulamalar için, doğrudan bir BlobContainerClient nesneden aktarımları başlatmak için uzantı yöntemlerini kullanabilirsiniz. Uzantı yöntemleri BlobContainerClientExtensions sınıfında (veya Azure Dosyalar için ShareDirectoryClientExtensions) sağlanır ve en az kod değişikliğiyle kullanmanın TransferManager avantajlarından bazılarını sağlar. Bu bölümde, bir BlobContainerClient nesneden aktarımları gerçekleştirmek için uzantı yöntemlerini kullanmayı öğreneceksiniz.

Henüz sahip değilseniz Azure.Storage.Blobs paketini yükleyin:

dotnet add package Azure.Storage.Blobs

Aşağıdaki using yönergeleri kod dosyanızın en üstüne ekleyin:

using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;

Bir sample-container adlı blob kapsayıcısı için BlobContainerClient örneğini nasıl oluşturacağınızı gösteren aşağıdaki kod örneği:

// Create a token credential
TokenCredential tokenCredential = new DefaultAzureCredential();

BlobServiceClient client = new BlobServiceClient(
    new Uri("https://<storage-account-name>.blob.core.windows.net"),
    tokenCredential);

BlobContainerClient containerClient = client.GetBlobContainerClient("sample-container");

Aşağıdaki kod örneği, sample-container kullanarak yerel dizin içeriğinin UploadDirectoryAsync'e nasıl yükleneceğini göstermektedir.

TransferOperation transfer = await containerClient
    .UploadDirectoryAsync(WaitUntil.Started, "local/directory/path");

await transfer.WaitForCompletionAsync();

Aşağıdaki kod örneğinde, DownloadToDirectoryAsync kullanılarak sample-container içeriğinin yerel bir dizine nasıl indirileceği gösterilmektedir.

TransferOperation transfer = await containerClient
    .DownloadToDirectoryAsync(WaitUntil.Started, "local/directory/path");

await transfer.WaitForCompletionAsync();

BlobContainerClient uzantı yöntemleri hakkında daha fazla bilgi edinmek için, BlobContainerClient üzerindeki Uzantılar'a bakın.

Sonraki adım