Delen via

Gegevens overdragen met de bibliotheek voor gegevensverplaatsing

  • Artikel

De Azure Storage-bibliotheek voor gegevensverplaatsing is een platformoverschrijdende open source-bibliotheek die is ontworpen voor het uploaden, downloaden en kopiëren van blobs en bestanden. De bibliotheek voor gegevensverplaatsing biedt handige methoden die niet beschikbaar zijn in de Azure Storage-clientbibliotheek voor .NET. Met deze methoden kunt u het aantal parallelle bewerkingen instellen, de voortgang van de overdracht bijhouden, een geannuleerde overdracht hervatten en meer.

De bibliotheek voor gegevensverplaatsing is alleen beschikbaar voor .NET en biedt alleen ondersteuning voor Azure Blob Storage en Azure Files. Houd rekening met deze beperkingen en andere bekende problemen bij het bepalen of u de bibliotheek voor gegevensverplaatsing wilt gebruiken.

Als u code migreert van de oudere Microsoft.Azure.Storage.DataMovement-bibliotheek (versie 2.X.X) naar de huidige Azure.Storage.DataMovement-bibliotheek (versie 12.X.X), raadpleegt u de migratiehandleiding.

Broncodepakket voor API-referentiedocumenten | | (NuGet) | Voorbeelden: Blobs / Files.Shares

Vereisten

Uw omgeving instellen

Als u geen bestaand project hebt, ziet u in deze sectie hoe u een project instelt voor gebruik met de Azure Blob Storage-clientbibliotheek voor .NET. De stappen omvatten pakketinstallatie, het toevoegen van using instructies en het maken van een geautoriseerd clientobject.

Pakketten installeren

Installeer vanuit uw projectmap pakketten voor de Azure Storage Data Movement-clientbibliotheek en de Azure Identity-clientbibliotheek met behulp van de dotnet add package opdracht. Het Azure.Identity-pakket is nodig voor verbindingen zonder wachtwoord met Azure-services.

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

Als u wilt werken met de extensiebibliotheek voor Azure Files, installeert u het pakket Azure.Storage.DataMovement.Files.Shares :

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

Voeg using-instructies toe

Als u de codevoorbeelden in dit artikel wilt uitvoeren, voegt u de volgende using instructies toe:

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

Als u de extensiebibliotheek voor Azure Files gebruikt, voegt u de volgende using instructie toe:

using Azure.Storage.DataMovement.Files.Shares;

Autorisatie

Het autorisatiemechanisme moet over de benodigde machtigingen beschikken om upload-, download- of kopieerbewerkingen uit te voeren. Voor autorisatie met Microsoft Entra ID (aanbevolen) hebt u ingebouwde Azure RBAC-rol Opslagblobgegevensbijdrager of hoger nodig.

Informatie over de bibliotheek voor gegevensverplaatsing

De Bibliotheek voor gegevensverplaatsing van Azure Storage bestaat uit een algemene clientbibliotheek en extensiebibliotheken voor Azure Blob Storage en Azure Files. De algemene bibliotheek biedt de kernfunctionaliteit voor het overdragen van gegevens, terwijl de extensiebibliotheken functionaliteit bieden die specifiek is voor Blob Storage en Azure Files. Zie de volgende bronnen voor meer informatie:

TransferManager Een object maken

TransferManager is de belangrijkste klasse voor het starten en beheren van alle typen overdrachten, waaronder uploaden, downloaden en kopiëren. In deze sectie leert u hoe u een TransferManager object maakt om te werken met een lokaal bestandssysteem, Blob Storage of Azure Files.

Notitie

Een best practice voor Azure SDK-clientbeheer is om een client als singleton te behandelen, wat betekent dat een klasse slechts één object tegelijk heeft. Het is niet nodig om meer dan één exemplaar van een client te bewaren voor een bepaalde set constructorparameters of clientopties.

De volgende code laat zien hoe u een TransferManager object maakt:

TransferManager transferManager = new(new TransferManagerOptions());

U kunt eventueel een exemplaar van TransferManagerOptions opgeven voor de constructor, waarmee bepaalde configuratieopties worden toegepast op alle overdrachten die door het TransferManager object zijn gestart. De volgende configuratieopties zijn beschikbaar:

  • CheckpointStoreOptions: Optioneel. Definieert de opties voor het maken van een controlepunt dat wordt gebruikt voor het opslaan van de overdrachtsstatus, zodat overdrachten kunnen worden hervat.
  • Diagnostische gegevens: hiermee haalt u de diagnostische opties voor overdrachtsbeheer op.
  • ErrorHandling: Optioneel. Definieert hoe fouten worden verwerkt tijdens een overdracht. Standaard is StopOnAnyFailure.
  • MaximumConcurrency: het maximum aantal werkrollen dat kan worden gebruikt in een parallelle overdracht.
  • ProvidersForResuming: Resourceproviders die de overdrachtsmanager kan gebruiken bij het hervatten van een overdracht. Verwacht één provider voor elke opslagprovider die wordt gebruikt. Zie Een bestaande overdracht hervatten voor meer informatie.

StorageResource Een object maken

StorageResource is de basisklasse voor alle opslagresources, waaronder blobs en bestanden. Gebruik een van de volgende providerklassen om een StorageResource object te maken:

StorageResource Een object maken voor Blob Storage

De volgende code laat zien hoe u een StorageResource object maakt voor blobcontainers en blobs met behulp van:Uri

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

U kunt ook een StorageResource object maken met behulp van een clientobject van 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

Een nieuwe overdracht starten

Alle overdrachten moeten een bron en een bestemming opgeven. Zowel de bron als het doel zijn type StorageResource, wat kan zijn StorageResourceContainer of StorageResourceItem. Voor een bepaalde overdracht moeten de bron en het doel van hetzelfde type zijn. Als de bron bijvoorbeeld een blobcontainer is, moet het doel een blobcontainer zijn.

U kunt een nieuwe overdracht starten door de volgende methode aan te roepen:

Met deze methode wordt een TransferOperation-object geretourneerd dat de overdracht vertegenwoordigt. U kunt het TransferOperation object gebruiken om de voortgang van de overdracht te controleren of de overdrachts-id op te halen. De overdrachts-id is een unieke id voor de overdracht die nodig is om een overdracht te hervatten of een overdracht te onderbreken.

U kunt desgewenst een exemplaar van TransferOptions opgeven op StartTransferAsync of ResumeTransferAsync, waarmee bepaalde configuratieopties worden toegepast op een specifieke overdracht. De volgende configuratieopties zijn beschikbaar:

  • CreationMode: hiermee configureert u het gedrag wanneer een overdracht een resource tegenkomt die al bestaat. Wordt standaard ingesteld FailIfExists bij het starten van een nieuwe overdracht. Wanneer u een overdracht hervat, kunnen de standaardwaarden variëren. Voor alle resources die zijn geïnventariseerd wanneer de overdracht is gestart, CreationMode wordt standaard de initiële waarde gebruikt. Voor alle resterende resources is de normale standaardwaarde van toepassing.
  • InitialTransferSize: De grootte van de eerste bereikaanvraag in bytes. Eén overdrachtsgrootte die kleiner is dan deze limiet, wordt geüpload of gedownload in één aanvraag. Overdrachten die groter zijn dan deze limiet, blijven worden gedownload of geüpload in segmenten van grootte MaximumTransferChunkSize. De standaardwaarde is 32 MiB. Wanneer u een overdracht hervat, is de standaardwaarde de waarde die is opgegeven toen de overdracht voor het eerst werd gestart.
  • MaximumTransferChunkSize: de maximale grootte die moet worden gebruikt voor elk segment bij het overdragen van gegevens in segmenten. De standaardwaarde is 4 MiB. Wanneer u een overdracht hervat, is de standaardwaarde de waarde die is opgegeven toen de overdracht voor het eerst werd gestart.
  • ProgressHandlerOptions: Optioneel. Opties voor het wijzigen van gedrag van de ProgressHandler.

Voorbeeld: Een lokale map uploaden naar een blobcontainer

In het volgende codevoorbeeld ziet u hoe u een nieuwe overdracht start om een lokale map te uploaden naar een blobcontainer:

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

Voorbeeld: Een container of blob kopiëren

U kunt de bibliotheek voor gegevensverplaatsing gebruiken om te kopiëren tussen twee StorageResource exemplaren. Voor blob-resources maakt de overdracht gebruik van de bewerking Put Blob From URL , waarmee een server-naar-server-kopie wordt uitgevoerd.

In het volgende codevoorbeeld ziet u hoe u een nieuwe overdracht start om alle blobs in een bron-blobcontainer te kopiëren naar een doel-blobcontainer. De doelcontainer moet al bestaan. In dit voorbeeld stellen we CreationMode in om OverwriteIfExists alle bestaande doel-blobs te overschrijven. U kunt de CreationMode eigenschap aanpassen op basis van de behoeften van uw app.

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

In het volgende codevoorbeeld ziet u hoe u een nieuwe overdracht start om een bron-blob te kopiëren naar een doel-blob. In dit voorbeeld stellen we CreationMode in om OverwriteIfExists de doel-blob te overschrijven als deze al bestaat. U kunt de CreationMode eigenschap aanpassen op basis van de behoeften van uw app.

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

Een bestaande overdracht hervatten

Door de voortgang van de overdracht naar schijf te behouden, kunt u met de bibliotheek voor gegevensverplaatsing een overdracht hervatten die is mislukt voordat deze is voltooid of op een andere manier is geannuleerd of onderbroken. Als u een overdracht wilt hervatten, moet het TransferManager object worden geconfigureerd met StorageResourceProvider exemplaren die de overdracht opnieuw kunnen verzamelen van de persistente gegevens. U kunt de ProvidersForResuming eigenschap van de klasse TransferManagerOptions gebruiken om de providers op te geven.

In het volgende codevoorbeeld ziet u hoe u een TransferManager object initialiseert dat een overdracht tussen het lokale bestandssysteem en Blob Storage kan hervatten:

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

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

Als u een overdracht wilt hervatten, roept u de volgende methode aan:

Geef de overdrachts-id op van de overdracht die u wilt hervatten. De overdrachts-id is een unieke id voor de overdracht die wordt geretourneerd als onderdeel van het TransferOperation object wanneer de overdracht wordt gestart. Als u de waarde van de overdrachts-id niet weet, kunt u TransferManager.GetTransfersAsync aanroepen om de overdracht en de bijbehorende id te vinden.

In het volgende codevoorbeeld ziet u hoe u een overdracht hervat:

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

Notitie

De locatie van de persistente overdrachtsgegevens wijkt af van de standaardlocatie als TransferCheckpointStoreOptions is ingesteld als onderdeel van TransferManagerOptions. Als u overdrachten wilt hervatten die zijn vastgelegd met een aangepast controlepuntarchief, moet u dezelfde opties voor het controlepuntarchief opgeven voor het TransferManager object dat de overdracht hervat.

Voortgang van overdracht bewaken

Overdrachten kunnen worden bewaakt en waargenomen via verschillende mechanismen, afhankelijk van de behoeften van uw app. In deze sectie leert u hoe u de voortgang van de overdracht bewaakt met behulp van het TransferOperation object en hoe u een overdracht bewaakt met behulp van TransferOptions gebeurtenissen.

Voorbeeld: Voortgang van overdracht bewaken met behulp van het TransferOperation object

U kunt de voortgang van de overdracht bewaken met behulp van het TransferOperation object dat door de StartTransferAsync methode wordt geretourneerd. U kunt ook TransferManager.GetTransfersAsync aanroepen om alle overdrachten voor een TransferManager object op te sommen.

In het volgende codevoorbeeld ziet u hoe u alle overdrachten kunt herhalen en de status van elke overdracht naar een logboekbestand schrijft:

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 definieert de status van de overdrachtstaak. TransferStatus bevat de volgende eigenschappen:

Eigenschap Type Beschrijving
HasCompletedSuccessfully Booleaanse waarde Geeft aan of de overdracht is voltooid zonder fouten of overgeslagen items.
HasFailedItems Booleaanse waarde Geeft aan of overdracht mislukte items bevat. Als deze optie is ingesteld true, heeft de overdracht ten minste één foutitem. Als deze optie is ingesteld false, heeft de overdracht momenteel geen fouten.
HasSkippedItems Booleaanse waarde Geeft aan of overdracht items heeft overgeslagen. Indien ingesteld op true, heeft de overdracht ten minste één overgeslagen item. Als deze optie is ingesteld false, heeft de overdracht momenteel geen overgeslagen items. Het is mogelijk om nooit items over te slaan als SkipIfExists deze niet is ingeschakeld in TransferOptions.CreationMode.
State TransferState Definieert de typen van de status die een overdracht kan hebben. Zie TransferState voor meer informatie.

Voorbeeld: Voortgang van overdracht bewaken met behulp van TransferOptions gebeurtenissen

U kunt de voortgang van de overdracht controleren door te luisteren naar gebeurtenissen die worden geleverd door de klasse TransferOptions . Het TransferOptions exemplaar wordt doorgegeven aan de StartTransferAsync methode en biedt gebeurtenissen die worden geactiveerd wanneer een overdracht is voltooid, mislukt, wordt overgeslagen of de status van wijzigingen wordt gewijzigd.

In het volgende codevoorbeeld ziet u hoe u luistert naar een gebeurtenis voor overdrachtsvoltooiing met behulp van 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);
}

Extensiemethoden gebruiken voor BlobContainerClient

Voor toepassingen met bestaande code die gebruikmaakt van de BlobContainerClient klasse van Azure.Storage.Blobs, kunt u extensiemethoden gebruiken om overdrachten rechtstreeks vanuit een BlobContainerClient object te starten. De extensiemethoden worden geleverd in de klasse BlobContainerClientExtensions (of ShareDirectoryClientExtensions voor Azure Files) en bieden enkele voordelen van het gebruik TransferManager van minimale codewijzigingen. In deze sectie leert u hoe u de extensiemethoden gebruikt om overdrachten van een BlobContainerClient object uit te voeren.

Installeer het pakket Azure.Storage.Blobs als u het nog niet hebt:

dotnet add package Azure.Storage.Blobs

Voeg de volgende using instructies toe aan het begin van het codebestand:

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

In het volgende codevoorbeeld ziet u hoe u een BlobContainerClient instantie maakt voor een blobcontainer met de naam 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");

In het volgende codevoorbeeld ziet u hoe u lokale mapinhoud uploadt naarsample-container:UploadDirectoryAsync

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

await transfer.WaitForCompletionAsync();

In het volgende codevoorbeeld ziet u hoe u de inhoud van een lokale map downloadt met behulp van sample-containerDownloadToDirectoryAsync:

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

await transfer.WaitForCompletionAsync();

Zie Extensies op BlobContainerClient voor meer informatie over de extensiemethoden.BlobContainerClient

Volgende stap