Freigeben über

Übertragen von Daten mit der Datenverschiebungsbibliothek

  • Artikel

Die Azure Storage-Datenverschiebungsbibliothek ist eine plattformübergreifende Open-Source-Bibliothek, die für das Hochladen, Herunterladen und Kopieren von Blobs und Dateien mit hoher Leistung entwickelt wurde. Die Datenverschiebungsbibliothek stellt praktische Methoden bereit, die nicht in der Azure Storage-Clientbibliothek für .NET verfügbar sind. Diese Methoden ermöglichen Ihnen das Festlegen der Anzahl paralleler Vorgänge, das Nachverfolgen des Übertragungsfortschritts, das Fortsetzen einer abgebrochenen Übertragung und mehr.

Die Datenverschiebungsbibliothek ist nur für .NET verfügbar und unterstützt nur Azure Blob Storage und Azure Files. Sie sollten diese Einschränkungen und andere bekannte Probleme berücksichtigen, wenn Sie entscheiden, ob Sie die Datenverschiebungsbibliothek verwenden.

Wenn Sie Code aus der älteren Microsoft.Azure.Storage.DataMovement-Bibliothek (Version 2.X.X) zur aktuellen Azure.Storage.DataMovement-Bibliothek (Version 12.X.X) migrieren, lesen Sie das Migrationshandbuch.

API-Referenzdokumente | Quellcode | Paket (NuGet) | Beispiele: Blobs / Files.Shares

Voraussetzungen

Erstellen Ihrer Umgebung

Wenn Sie nicht über ein vorhandenes Projekt verfügen, wird in diesem Abschnitt gezeigt, wie Sie ein Projekt für die Arbeit mit der Azure Blob Storage-Clientbibliothek für .NET einrichten. Die Schritte umfassen die Paketinstallation, das Hinzufügen von using-Anweisungen und das Erstellen eines autorisierten Clientobjekts.

Installieren von Paketen

Installieren Sie aus Ihrem Projektverzeichnis Pakete für die Azure Storage-Datenverschiebung-Clientbibliothek und die Azure Identity-Clientbibliothek mit dem Befehl dotnet add package. Für kennwortlose Verbindungen mit Azure-Diensten wird das Azure.Identity-Paket benötigt.

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

Um mit der Erweiterungsbibliothek für Azure Files arbeiten zu können, installieren Sie das Paket Azure.Storage.DataMovement.Files.Shares:

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

Fügen Sie Anweisungen vom Typ using hinzu.

Um die Codebeispiele in diesem Artikel auszuführen, fügen Sie die folgenden using-Direktiven hinzu:

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

Wenn Sie die Erweiterungsbibliothek für Azure Files verwenden, fügen Sie die folgende using-Direktive hinzu:

using Azure.Storage.DataMovement.Files.Shares;

Autorisierung

Der Autorisierungsmechanismus muss über die erforderlichen Berechtigungen zum Ausführen von Upload-, Download- und Kopiervorgängen verfügen. Für die Autorisierung mit Microsoft Entra ID (empfohlen) benötigen Sie mindestens die integrierte Azure RBAC-Rolle Mitwirkender an Storage-Blobdaten.

Informationen zur Datenverschiebungsbibliothek

Die Azure Storage-Datenverschiebungsbibliothek besteht aus einer gemeinsamen Clientbibliothek und Erweiterungsbibliotheken für Azure Blob Storage und Azure Files. Die allgemeine Bibliothek bietet die Kernfunktionen zum Übertragen von Daten, während die Erweiterungsbibliotheken Funktionen speziell für Blob Storage und Azure Files bereitstellen. Weitere Informationen finden Sie in den folgenden Ressourcen:

Erstellen eines TransferManager-Objekts

TransferManager ist die Hauptklasse zum Starten und Steuern aller Arten von Übertragungen, einschließlich Upload, Download und Kopie. In diesem Abschnitt erfahren Sie, wie Sie ein TransferManager-Objekt zum Arbeiten mit einem lokalen Dateisystem, Blob Storage oder Azure Files erstellen.

Hinweis

Eine bewährte Methode für die Azure SDK-Clientverwaltung besteht darin, einen Client als Singleton zu behandeln, was bedeutet, dass eine Klasse zu einem gegebenem Zeitpunkt jeweils nur ein Objekt aufweist. Es ist nicht erforderlich, mehr als eine Instanz eines Clients für einen bestimmten Satz von Konstruktorparametern oder Clientoptionen beizubehalten.

Der folgende Code zeigt, wie ein TransferManager-Objekt erstellt wird.

TransferManager transferManager = new(new TransferManagerOptions());

Optional können Sie eine Instanz von TransferManagerOptions für den Konstruktor bereitstellen, die bestimmte Konfigurationsoptionen auf alle vom TransferManager-Objekt gestarteten Übertragungen anwendet. Die folgenden Konfigurationsoptionen sind verfügbar:

  • CheckpointStoreOptions: Optional. Definiert die Optionen zum Erstellen eines Prüfpunkts, der zum Speichern des Übertragungszustands verwendet wird, damit Übertragungen fortgesetzt werden können.
  • Diagnose: Ruft die Diagnoseoptionen des Übertragungs-Managers ab.
  • ErrorHandling: Optional. Definiert, wie Fehler während einer Übertragung behandelt werden. Der Standardwert ist StopOnAnyFailure.
  • MaximumConcurrency: Die maximale Anzahl von Workern, die in einer parallelen Übertragung verwendet werden können.
  • ProvidersForResuming: Ressourcenanbieter für den Übertragungs-Manager, der beim Fortsetzen einer Übertragung verwendet werden soll. Erwartet einen Anbieter für jeden verwendeten Speicheranbieter. Weitere Informationen finden Sie unter Fortsetzen einer vorhandenen Übertragung.

Erstellen eines StorageResource-Objekts

StorageResource ist die Basisklasse für alle Speicherressourcen, einschließlich Blobs und Dateien. Verwenden Sie zum Erstellen eines StorageResource-Objekts eine der folgenden Anbieterklassen:

Erstellen eines StorageResource-Objekts für Blob Storage

Der folgende Code zeigt, wie Sie mithilfe einer Uri ein StorageResource-Objekt für BLOB-Container und Blobs erstellen:

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

Sie können ein StorageResource-Objekt auch mithilfe eines Clientobjekts aus Azure.Storage.Blobs erstellen.

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

Starten einer neuen Übertragung

Für alle Übertragungen müssen eine Quelle und ein Ziel angegeben werden. Sowohl die Quelle als auch das Ziel sind vom Typ StorageResource und entweder StorageResourceContainer oder StorageResourceItem. Bei einer bestimmten Übertragung müssen Quelle und Ziel vom gleichen Typ sein. Wenn es sich bei der Quelle beispielsweise um einen BLOB-Container handelt, muss es sich auch beim Ziel um einen BLOB-Container handeln.

Sie können eine neue Übertragung starten, indem Sie die folgende Methode aufrufen:

Diese Methode gibt ein TransferOperation-Objekt zurück, das die Übertragung darstellt. Sie können das TransferOperation-Objekt verwenden, um den Übertragungsfortschritt zu überwachen oder die Übertragungs-ID abzurufen. Die Übertragungs-ID ist ein eindeutiger Bezeichner für die Übertragung, die zum Fortsetzen der Übertragung oder zum Anhalten der Übertragung erforderlich ist.

Optional können Sie eine Instanz von TransferOptions für StartTransferAsync oder ResumeTransferAsync bereitstellen, um bestimmte Konfigurationsoptionen auf eine bestimmte Übertragung anzuwenden. Die folgenden Konfigurationsoptionen sind verfügbar:

  • CreationMode: Konfiguriert das Verhalten, wenn eine Übertragung auf eine bereits vorhandene Ressource trifft. Standardmäßig wird FailIfExists beim Starten einer neuen Übertragung verwendet. Wenn Sie eine Übertragung fortsetzen, können die Standardwerte variieren. Für alle Ressourcen, die beim Start der Übertragung erfolgreich aufgezählt wurden, wird für CreationMode standardmäßig der verwendete Anfangswert eingesetzt. Für alle verbleibenden Ressourcen gilt der reguläre Standardwert.
  • InitialTransferSize: Die Größe der ersten Bereichsanforderung in Bytes. Einzelne Übertragungen mit einer Größe, die kleiner als dieser Grenzwert sind, werden in einer einzigen Anforderung hochgeladen oder heruntergeladen. Übertragungen, die größer als dieser Grenzwert sind, werden weiterhin heruntergeladen oder in Blöcken der Größe MaximumTransferChunkSizehochgeladen. Der Standardwert ist 32 MiB. Wenn Sie eine Übertragung fortsetzen, ist der Standardwert der Wert, der beim ersten Start der Übertragung angegeben wird.
  • MaximumTransferChunkSize: Die maximale Größe, die beim Übertragen von Daten in Datenblöcken für jeden Block verwendet werden soll. Der Standardwert ist 4 MiB. Wenn Sie eine Übertragung fortsetzen, ist der Standardwert der Wert, der beim ersten Start der Übertragung angegeben wird.
  • ProgressHandlerOptions: Optional. Optionen zum Ändern des Verhaltens des ProgressHandler-Objekts.

Beispiel: Hochladen eines lokalen Verzeichnisses in einen BLOB-Container

Das folgende Codebeispiel zeigt, wie sie eine neue Übertragung starten, um ein lokales Verzeichnis in einen BLOB-Container hochzuladen:

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

Beispiel: Kopieren eines Containers oder Blobs

Sie können die Datenverschiebungsbibliothek verwenden, um Daten zwischen zwei StorageResource-Instanzen zu kopieren. Für Blob-Ressourcen wird zur Übertragung der Vorgang Put Blob From URL verwendet, der eine Server-zu-Server-Kopie ausführt.

Das folgende Codebeispiel zeigt, wie Sie eine neue Übertragung starten, um alle in einem Quell-BLOB-Container enthaltenen Blobs in einen Ziel-Blob-Container zu kopieren. Der Zielcontainer muss bereits vorhanden sein. In diesem Beispiel legen wir CreationMode auf OverwriteIfExists fest, so dass alle bereits vorhandenen Zielblobs überschrieben werden. Sie können die Eigenschaft CreationMode basierend auf den Anforderungen Ihrer App anpassen.

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

Das folgende Codebeispiel zeigt, wie eine neue Übertragung gestartet wird, um ein Quell-Blob in ein Ziel-Blob zu kopieren. In diesem Beispiel legen wir CreationMode auf OverwriteIfExists fest, so dass das Ziel-Blob überschrieben wird, wenn es bereits vorhanden ist. Sie können die Eigenschaft CreationMode basierend auf den Anforderungen Ihrer App anpassen.

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

Fortsetzen einer vorhandenen Übertragung

Durch das Speichern des Übertragungsfortschritts auf den Datenträger können Sie mit der Datenverschiebungsbibliothek eine Übertragung fortsetzen, die vor dem Abschluss fehlgeschlagen ist oder aus anderen Gründen abgebrochen oder angehalten wurde. Um eine Übertragung fortzusetzen, muss das TransferManager-Objekt mit StorageResourceProvider-Instanzen, die die Übertragung aus den gespeicherten Daten erneut zusammenführen können, konfiguriert werden. Sie können die Eigenschaft ProvidersForResuming der TransferManagerOptions-Klasse verwenden, um die Anbieter anzugeben.

Das folgende Codebeispiel zeigt, wie Sie ein TransferManager-Objekt initialisieren, das eine Übertragung zwischen dem lokalen Dateisystem und Blob Storage fortsetzen kann:

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

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

Um eine Übertragung fortzusetzen, rufen Sie die folgende Methode auf:

Geben Sie die Übertragungs-ID der Übertragung an, die Sie fortsetzen möchten. Die Übertragungs-ID ist ein eindeutiger Bezeichner für die Übertragung, die beim Start der Übertragung als Teil des TransferOperation-Objekts zurückgegeben wird. Wenn Sie den Wert der Übertragungs-ID nicht kennen, können Sie TransferManager.GetTransfersAsync aufrufen, um die Übertragung und die entsprechende ID zu finden.

Das folgende Codebeispiel zeigt, wie eine Übertragung fortgesetzt wird:

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

Hinweis

Der Speicherort der gespeicherten Übertragungsdaten unterscheidet sich vom Standardspeicherort, wenn TransferCheckpointStoreOptions als Teil von TransferManagerOptions festgelegt wird. Um Übertragungen fortzusetzen, die mit einem benutzerdefinierten Prüfpunktspeicher aufgezeichnet wurden, müssen Sie die gleichen Prüfpunktspeicheroptionen für das TransferManager-Objekt, das die Übertragung fortsetzt, bereitstellen.

Überwachen des Übertragungsfortschritts

Übertragungen können abhängig von den Anforderungen Ihrer App über mehrere Mechanismen überwacht und beobachtet werden. In diesem Abschnitt erfahren Sie, wie Sie den Übertragungsfortschritt mithilfe des TransferOperation-Objekts überwachen und wie Sie eine Übertragung mithilfe von TransferOptions-Ereignissen überwachen.

Beispiel: Überwachen des Übertragungsfortschritts mithilfe des TransferOperation-Objekts

Sie können den Übertragungsfortschritt mithilfe des TransferOperation-Objekts überwachen, das von der StartTransferAsync-Methode zurückgegeben wird. Sie können auch TransferManager.GetTransfersAsync aufrufen, um alle Übertragungen für ein TransferManager-Objekt aufzuzählen.

Das folgende Codebeispiel zeigt, wie Sie alle Übertragungen durchlaufen und den Status jeder Übertragung in eine Protokolldatei schreiben:

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 definiert den Status des Übertragungsauftrags. TransferStatus beinhaltet die folgenden Eigenschaften:

Eigenschaft Typ Beschreibung
HasCompletedSuccessfully Boolean Gibt an, ob die Übertragung ohne Fehler oder übersprungene Elemente erfolgreich abgeschlossen wird.
HasFailedItems Boolean Gibt an, ob bei der Übertragung Fehlerelemente vorhanden sind. Wenn diese Option auf true festgelegt ist, weist die Übertragung mindestens ein Fehlerelement auf. Bei Festlegung auf false enthält die Übertragung derzeit keine Fehler.
HasSkippedItems Boolean Gibt an, ob die Übertragung über übersprungene Elemente verfügt. Bei Festlegung auf true enthält die Übertragung mindestens ein übersprungenes Element. Wenn diese Option auf false festgelegt ist, weist die Übertragung derzeit keine übersprungenen Elemente auf. Es ist möglich, nie übersprungene Elemente zu enthalten, wenn SkipIfExists in TransferOptions.CreationMode nicht aktiviert ist.
State TransferState Definiert die Typen des Zustands, den eine Übertragung annehmen kann. Details finden Sie unter TransferState.

Beispiel: Überwachen des Übertragungsfortschritts mithilfe von TransferOptions-Ereignissen

Sie können den Übertragungsfortschritt überwachen, indem Sie Ereignisse überwachen, die von der TransferOptions-Klasse bereitgestellt werden. Die TransferOptions-Instanz wird an die StartTransferAsync-Methode übergeben und stellt Ereignisse bereit, die ausgelöst werden, wenn eine Übertragung abgeschlossen wird, fehlschlägt, übersprungen wird oder wenn ihr Status geändert wird.

Das folgende Codebeispiel zeigt, wie Sie mit TransferOptions auf ein Übertragungsabschlussereignis lauschen:

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

Verwenden von Erweiterungsmethoden für BlobContainerClient

Für Anwendungen mit vorhandenem Code, die die BlobContainerClient-Klasse aus Azure.Storage.Blobs verwenden, können Sie Erweiterungsmethoden verwenden, um Übertragungen direkt von einem BlobContainerClient-Objekt aus zu starten. Die Erweiterungsmethoden werden in der BlobContainerClientExtensions-Klasse (oder ShareDirectoryClientExtensions für Azure Files) bereitgestellt und bieten einige Vorteile der Verwendung von TransferManager mit minimalen Codeänderungen. In diesem Abschnitt erfahren Sie, wie Sie die Erweiterungsmethoden verwenden, um Übertragungen von einem BlobContainerClient-Objekt auszuführen.

Installieren Sie das Azure.Storage.Blobs-Paket, sofern noch nicht geschehen:

dotnet add package Azure.Storage.Blobs

Fügen Sie am Anfang Ihres Codes die folgenden using-Anweisungen hinzu:

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

Das folgende Codebeispiel zeigt, wie Sie ein BlobContainerClient für einen Blobcontainer namens sample-container instanziieren:

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

Das folgende Codebeispiel zeigt, wie sie lokale Verzeichnisinhalte unter Verwendung von UploadDirectoryAsync in sample-container hochladen:

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

await transfer.WaitForCompletionAsync();

Das folgende Codebeispiel zeigt, wie Sie den Inhalt von sample-container mithilfe von DownloadToDirectoryAsync in ein lokales Verzeichnis herunterladen:

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

await transfer.WaitForCompletionAsync();

Weitere Informationen zu den Erweiterungsmethoden für BlobContainerClient finden Sie unter Erweiterungen für BlobContainerClient.

Nächster Schritt