Přenos dat s využitím knihovny pro přesun dat

Knihovna pro přesun dat ve službě Azure Storage je multiplatformní opensourcová knihovna, která je navržená pro vysoce výkonné nahrávání, stahování a kopírování objektů blob a souborů. Knihovna pro přesun dat poskytuje vhodné metody, které nejsou dostupné v klientské knihovně Azure Storage pro .NET. Tyto metody umožňují nastavit počet paralelních operací, sledovat průběh přenosu, obnovit zrušený přenos a další.

Knihovna pro přesun dat je k dispozici pouze pro .NET a podporuje pouze službu Azure Blob Storage a Soubory Azure. Při rozhodování o použití knihovny pro přesun dat byste měli zvážit tato omezení a další známé problémy .

Pokud migrujete kód ze starší knihovny Microsoft.Azure.Storage.DataMovement (verze 2.X.X) do aktuální knihovny Azure.Storage.DataMovement (verze 12.X.X), přečtěte si průvodce migrací.

Referenční dokumentace k rozhraní API – Balíček zdrojového | kódu | (NuGet) | Ukázky: Blobs / Files.Shares

Požadavky

• Předplatné Azure – vytvoření bezplatného předplatného
• Účet úložiště Azure – Vytvoření účtu úložiště
• Nejnovější sada .NET SDK pro váš operační systém Nezapomeňte získat sadu SDK a ne modul runtime.

Nastavení prostředí

Pokud nemáte existující projekt, v této části se dozvíte, jak nastavit projekt pro práci s klientskou knihovnou Azure Blob Storage pro .NET. Kroky zahrnují instalaci balíčku, přidání using direktiv a vytvoření autorizovaného objektu klienta.

Instalace balíčků

Z adresáře projektu nainstalujte balíčky pro klientskou knihovnu pro přesun dat služby Azure Storage a klientskou knihovnu dotnet add package Azure Identity pomocí příkazu. Balíček Azure.Identity je potřeba pro připojení bez hesla ke službám Azure.

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

Pokud chcete pracovat s knihovnou rozšíření pro Azure Files, nainstalujte balíček Azure.Storage.DataMovement.Files.Shares :

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

Přidání using direktiv

Pokud chcete spustit příklady kódu v tomto článku, přidejte následující using direktivy:

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

Pokud používáte knihovnu rozšíření pro Azure Files, přidejte následující using direktivu:

using Azure.Storage.DataMovement.Files.Shares;

Autorizace

Autorizační mechanismus musí mít potřebná oprávnění k provádění operací nahrávání, stahování nebo kopírování. K autorizaci pomocí Microsoft Entra ID (doporučeno) potřebujete předdefinovanou roli Přispěvatel dat objektů blob služby Azure RBAC nebo vyšší.

Informace o knihovně přesunu dat

Knihovna pro přesun dat ve službě Azure Storage se skládá z společné klientské knihovny a knihoven rozšíření pro Azure Blob Storage a Soubory Azure. Společná knihovna poskytuje základní funkce pro přenos dat, zatímco rozšiřující knihovny poskytují funkce specifické pro Blob Storage a Soubory Azure. Další informace najdete v následujících zdrojích informací:

• Azure.Storage.DataMovement
• Azure.Storage.DataMovement.Blobs
• Azure.Storage.DataMovement.Files.Shares

Vytvoření objektu TransferManager

TransferManager je hlavní třídou pro spuštění a řízení všech typů přenosů, včetně nahrávání, stahování a kopírování. V této části se dozvíte, jak vytvořit objekt pro práci s místním systémem souborů, službou Blob Storage nebo službou TransferManager Azure Files.

Poznámka:

Osvědčeným postupem pro správu klientů sady Azure SDK je považovat klienta za jednoúčelový, což znamená, že třída má najednou pouze jeden objekt. Není nutné uchovávat více než jednu instanci klienta pro danou sadu parametrů konstruktoru nebo možnosti klienta.

Následující kód ukazuje, jak vytvořit TransferManager objekt:

TransferManager transferManager = new(new TransferManagerOptions());

Volitelně můžete zadat instanci TransferManagerOptions konstruktoru, která aplikuje určité možnosti konfigurace na všechny přenosy spuštěné objektem TransferManager . K dispozici jsou následující možnosti konfigurace:

• CheckpointStoreOptions: Volitelné. Definuje možnosti pro vytvoření kontrolního bodu použitého k uložení stavu přenosu, aby bylo možné pokračovat v přenosech.
• Diagnostika: Získá diagnostické možnosti správce přenosu.
• ChybaHandling: Volitelné. Definuje způsob zpracování chyb během přenosu. Výchozí hodnota je StopOnAnyFailure.
• MaximumConcurrency: Maximální počet pracovních procesů, které lze použít v paralelním přenosu.
• ProvidersForResuming: Poskytovatelé prostředků pro správce přenosu, kteří se mají použít při obnovení přenosu. Očekává jednoho poskytovatele pro každého zprostředkovatele úložiště, který se používá. Další informace najdete v tématu Obnovení existujícího přenosu.

Vytvoření objektu StorageResource

StorageResource je základní třída pro všechny prostředky úložiště, včetně objektů blob a souborů. K vytvoření objektu StorageResource použijte jednu z následujících tříd zprostředkovatele:

• BlobsStorageResourceProvider: Pomocí této třídy můžete vytvářet StorageResource instance pro kontejner objektů blob, objekt blob bloku, doplňovací objekt blob nebo objekt blob stránky.
• ShareFilesStorageResourceProvider: Tuto třídu použijte k vytvoření StorageResource instancí pro soubor nebo adresář.
• LocalFilesStorageResourceProvider: Pomocí této třídy vytvořte StorageResource instance pro místní systém souborů.

Vytvoření objektu StorageResource pro Blob Storage

Následující kód ukazuje, jak vytvořit StorageResource objekt pro kontejnery objektů blob a objekty blob pomocí Uripříkazu :

// 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

Objekt můžete také vytvořit pomocí klientského StorageResource objektu z Azure.Storage.Blobs.

// 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

Zahájení nového převodu

Všechny přenosy musí zadat zdroj a cíl. Zdroj i cíl jsou typ StorageResource, který může být buď StorageResourceContainer nebo StorageResourceItem. Pro daný přenos musí být zdroj a cíl stejného typu. Pokud je zdrojem například kontejner objektů blob, musí být cílem kontejner objektů blob.

Nový přenos můžete zahájit voláním následující metody:

• TransferManager.StartTransferAsync

Tato metoda vrátí TransferOperation objekt, který představuje přenos. Objekt můžete použít TransferOperation ke sledování průběhu přenosu nebo získání ID přenosu. ID přenosu je jedinečný identifikátor pro přenos, který je nutný k obnovení převodu nebo pozastavení přenosu.

Volitelně můžete zadat instanci TransferOptions do StartTransferAsync nebo ResumeTransferAsync, která aplikuje určité možnosti konfigurace na konkrétní přenos. K dispozici jsou následující možnosti konfigurace:

• CreationMode: Konfiguruje chování při přenosu narazí na prostředek, který již existuje. Výchozí hodnota FailIfExists je při spuštění nového přenosu. Když obnovíte přenos, výchozí hodnoty se mohou lišit. Pro všechny prostředky úspěšně vyčíslit při spuštění přenosu, CreationMode výchozí hodnota je použitá počáteční hodnota. U všech zbývajících prostředků platí běžná výchozí hodnota.
• InitialTransferSize: Velikost prvního požadavku rozsahu v bajtech. Velikosti jednoho přenosu menší než tento limit se nahrají nebo stáhnou v jediné žádosti. Přenosy větší, než je tento limit, budou nadále stahovány nebo nahrávány do bloků velikosti MaximumTransferChunkSize. Výchozí hodnota je 32 MiB. Když obnovíte přenos, výchozí hodnota je hodnota zadaná při prvním spuštění přenosu.
• MaximumTransferChunkSize: Maximální velikost, která se má použít pro každý blok dat při přenosu dat v blocích. Výchozí hodnota je 4 MiB. Když obnovíte přenos, výchozí hodnota je hodnota zadaná při prvním spuštění přenosu.
• ProgressHandlerOptions: Volitelné. Možnosti pro změnu chování progresshandleru

Příklad: Nahrání místního adresáře do kontejneru objektů blob

Následující příklad kódu ukazuje, jak spustit nový přenos pro nahrání místního adresáře do kontejneru objektů blob:

// 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();

Příklad: Kopírování kontejneru nebo objektu blob

Knihovnu přesunu dat můžete použít ke kopírování mezi dvěma StorageResource instancemi. Pro prostředky objektů blob používá přenos operaci Put Blob From URL , která provádí kopírování mezi servery.

Následující příklad kódu ukazuje, jak spustit nový přenos pro kopírování všech objektů blob ve zdrojovém kontejneru objektů blob do cílového kontejneru objektů blob. Cílový kontejner už musí existovat. V tomto příkladu nastavíme CreationMode tak, aby OverwriteIfExists přepsal všechny cílové objekty blob, které již existují. Vlastnost můžete upravit CreationMode podle potřeb vaší aplikace.

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();

Následující příklad kódu ukazuje, jak spustit nový přenos pro zkopírování zdrojového objektu blob do cílového objektu blob. V tomto příkladu nastavíme CreationMode tak, aby OverwriteIfExists přepsal cílový objekt blob, pokud již existuje. Vlastnost můžete upravit CreationMode podle potřeb vaší aplikace.

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();

Obnovení existujícího převodu

Díky trvalému průběhu přenosu na disk umožňuje knihovna přesunu dat obnovit přenos, který selhal před dokončením, nebo byl jinak zrušen nebo pozastaven. Aby bylo možné pokračovat v přenosu, TransferManager musí být objekt nakonfigurovaný s instancemi StorageResourceProvider , které jsou schopné znovu sestavit přenos z trvalých dat. Vlastnost TransferManagerOptions třídy můžete použít ProvidersForResumingk určení zprostředkovatelů.

Následující příklad kódu ukazuje, jak inicializovat TransferManager objekt, který dokáže obnovit přenos mezi místním systémem souborů a službou Blob Storage:

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

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

Pokud chcete pokračovat v přenosu, zavolejte následující metodu:

• TransferManager.ResumeTransferAsync

Zadejte ID přenosu přenosu, který chcete obnovit. ID přenosu je jedinečný identifikátor přenosu, který se vrátí jako součást objektu TransferOperation při spuštění přenosu. Pokud hodnotu ID přenosu neznáte, můžete zavolat TransferManager.GetTransfersAsync a najít přenos a jeho odpovídající ID.

Následující příklad kódu ukazuje, jak pokračovat v přenosu:

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

Poznámka:

Umístění trvalých přenosových dat se liší od výchozího umístění, pokud je transferCheckpointStoreOptions nastaven jako součást TransferManagerOptions. Chcete-li obnovit přenosy zaznamenané pomocí vlastního úložiště kontrolních bodů, je nutné zadat stejné možnosti úložiště kontrolních bodů pro TransferManager objekt, který obnoví přenos.

Monitorování průběhu přenosu

Přenosy je možné monitorovat a sledovat prostřednictvím několika mechanismů v závislosti na potřebách vaší aplikace. V této části se dozvíte, jak monitorovat průběh přenosu pomocí objektu TransferOperation a jak monitorovat přenos pomocí TransferOptions událostí.

Příklad: Monitorování průběhu přenosu pomocí objektu TransferOperation

Průběh přenosu můžete monitorovat pomocí objektu TransferOperation vráceného metodou StartTransferAsync . Můžete také volat TransferManager.GetTransfersAsync k vytvoření výčtu všech přenosů pro TransferManager objekt.

Následující příklad kódu ukazuje, jak iterovat všechny přenosy a zapisovat stav každého přenosu do souboru protokolu:

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));
    }
}

Funkce TransferStatus definuje stav úlohy přenosu. TransferStatus obsahuje následující vlastnosti:

Vlastnost	Type	Popis
HasCompletedSuccessfully	Logické	Představuje, pokud se přenos úspěšně dokončí bez selhání nebo vynechání položek.
HasFailedItems	Logická hodnota	Představuje, zda má přenos nějaké položky selhání. Pokud je nastavená hodnota true, má přenos alespoň jednu položku selhání. Pokud je nastavená hodnota false, přenos aktuálně nemá žádné chyby.
HasSkippedItems	Logická hodnota	Představuje, jestli má přenos nějaké přeskočené položky. Pokud je nastavená hodnota true, má přenos alespoň jednu přeskočenou položku. Pokud je nastavená hodnota false, převod aktuálně nemá žádné přeskočené položky. Pokud není v režimu TransferOptions.CreationMode povolená žádná položka, je možné nikdy vynechat žádné položkySkipIfExists.
State	TransferState	Definuje typy stavu, který může mít přenos. Podrobnosti najdete v části TransferState .

Příklad: Monitorování průběhu přenosu pomocí TransferOptions událostí

Průběh přenosu můžete monitorovat nasloucháním událostí poskytovaných třídou TransferOptions . Instance TransferOptions se předá StartTransferAsync metodě a poskytuje události , které se aktivují při dokončení přenosu, selhání, přeskočení nebo změny stavu.

Následující příklad kódu ukazuje, jak naslouchat události dokončení přenosu pomocí TransferOptions:

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);
}

Použití rozšiřujících metod pro BlobContainerClient

Pro aplikace s existujícím kódem, který používá BlobContainerClient třídu z Azure.Storage.Blobs, můžete pomocí rozšiřujících metod spustit přenosy přímo z objektu BlobContainerClient . Metody rozšíření jsou k dispozici ve třídě BlobContainerClientExtensions (nebo ShareDirectoryClientExtensions pro Soubory Azure) a poskytují některé výhody použití TransferManager s minimálními změnami kódu. V této části se dozvíte, jak pomocí rozšiřujících metod provádět přenosy z objektu BlobContainerClient .

Pokud ho ještě nemáte, nainstalujte balíček Azure.Storage.Blobs :

dotnet add package Azure.Storage.Blobs

Na začátek souboru kódu přidejte následující using direktivy:

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

Následující příklad kódu ukazuje, jak vytvořit instanci BlobContainerClient kontejneru objektů blob s názvem sample-container:

// 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");

Následující příklad kódu ukazuje, jak nahrát obsah místního adresáře dosample-container:UploadDirectoryAsync

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

await transfer.WaitForCompletionAsync();

Následující příklad kódu ukazuje, jak stáhnout obsah sample-container do místního adresáře pomocí DownloadToDirectoryAsync:

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

await transfer.WaitForCompletionAsync();

Další informace o metodách BlobContainerClientrozšíření najdete v tématu Rozšíření v BlobContainerClient.

Další krok

• Ukázky kódu pro DataMovement.Blobs a DataMovement.Files.Shares jsou k dispozici v úložišti Azure SDK pro .NET Na GitHubu.