Läs på engelska

Dela via

Överföra data med dataflyttbiblioteket

  • Artikel

Azure Storage Data Movement-biblioteket är ett plattformsoberoende öppen källkod bibliotek som är utformat för uppladdning, nedladdning och kopiering av blobar och filer med höga prestanda. Data movement-biblioteket innehåller praktiska metoder som inte är tillgängliga i Azure Storage-klientbiblioteket för .NET. Med de här metoderna kan du ange antalet parallella åtgärder, spåra överföringsframsteg, återuppta en avbruten överföring med mera.

Dataförflyttningsbiblioteket är endast tillgängligt för .NET och stöder endast Azure Blob Storage och Azure Files. Du bör överväga dessa begränsningar och andra kända problem när du bestämmer dig för om du vill använda dataflyttbiblioteket.

Om du migrerar kod från det äldre Microsoft.Azure.Storage.DataMovement-biblioteket (version 2.X.X) till det aktuella Azure.Storage.DataMovement-biblioteket (version 12.X.X) läser du migreringsguiden.

API-referensdokument Källkodspaket | | (NuGet) | Exempel: Blobar / Files.Shares

Förutsättningar

Konfigurera din miljö

Om du inte har ett befintligt projekt visar det här avsnittet hur du konfigurerar ett projekt för att arbeta med Azure Blob Storage-klientbiblioteket för .NET. Stegen omfattar paketinstallation, tillägg av using direktiv och skapande av ett auktoriserat klientobjekt.

Installera paket

Från projektkatalogen installerar du paket för Azure Storage Data Movement-klientbiblioteket och Azure Identity-klientbiblioteket med hjälp av dotnet add package kommandot . Azure.Identity-paketet behövs för lösenordslösa anslutningar till Azure-tjänster.

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

Om du vill arbeta med tilläggsbiblioteket för Azure Files installerar du paketet Azure.Storage.DataMovement.Files.Shares :

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

Lägga till using direktiv

Om du vill köra kodexemplen i den här artikeln lägger du till följande using direktiv:

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

Om du använder tilläggsbiblioteket för Azure Files lägger du till följande using direktiv:

C# 
using Azure.Storage.DataMovement.Files.Shares;

Auktorisering

Auktoriseringsmekanismen måste ha de behörigheter som krävs för att utföra uppladdnings-, nedladdnings- eller kopieringsåtgärder. För auktorisering med Microsoft Entra-ID (rekommenderas) behöver du den inbyggda rollen Storage Blob Data Contributor eller senare.

Om dataflyttbiblioteket

Azure Storage Data Movement-biblioteket består av ett gemensamt klientbibliotek och tilläggsbibliotek för Azure Blob Storage och Azure Files. Det gemensamma biblioteket tillhandahåller kärnfunktionerna för överföring av data, medan tilläggsbiblioteken tillhandahåller funktioner som är specifika för Blob Storage och Azure Files. Mer information finns i följande resurser:

Skapa ett TransferManager objekt

TransferManager är huvudklassen för att starta och kontrollera alla typer av överföringar, inklusive uppladdning, nedladdning och kopiering. I det här avsnittet får du lära dig hur du skapar ett TransferManager objekt som fungerar med ett lokalt filsystem, Blob Storage eller Azure Files.

Anteckning

Bästa praxis för Azure SDK-klienthantering är att behandla en klient som en singleton, vilket innebär att en klass bara har ett objekt i taget. Du behöver inte behålla mer än en instans av en klient för en viss uppsättning konstruktorparametrar eller klientalternativ.

Följande kod visar hur du skapar ett TransferManager objekt:

C# 
TransferManager transferManager = new(new TransferManagerOptions());

Du kan också ange en instans av TransferManagerOptions för konstruktorn, som tillämpar vissa konfigurationsalternativ på alla överföringar som startas av TransferManager objektet. Följande konfigurationsalternativ är tillgängliga:

  • CheckpointStoreOptions: Valfritt. Definierar alternativen för att skapa en kontrollpunkt som används för att spara överföringstillstånd så att överföringar kan återupptas.
  • Diagnostik: Hämtar diagnostikalternativ för överföringshanteraren.
  • ErrorHandling: Valfritt. Definierar hur fel hanteras under en överföring. Standard är StopOnAnyFailure.
  • MaximumConcurrency: Det maximala antalet arbetare som kan användas i en parallell överföring.
  • ProvidersForResuming: Resursprovidrar som överföringshanteraren kan använda för att återuppta en överföring. Förväntar sig en provider för varje lagringsprovider som används. Mer information finns i Återuppta en befintlig överföring.

Skapa ett StorageResource objekt

StorageResource är basklassen för alla lagringsresurser, inklusive blobar och filer. Om du vill skapa ett StorageResource objekt använder du någon av följande providerklasser:

Skapa ett StorageResource objekt för Blob Storage

Följande kod visar hur du skapar ett StorageResource objekt för blobcontainrar och blobar med hjälp av en Uri:

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

Du kan också skapa ett StorageResource objekt med hjälp av ett klientobjekt från Azure.Storage.Blobs.

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

Starta en ny överföring

Alla överföringar måste ange en källa och ett mål. Både källan och målet är typ StorageResource, som kan vara antingen StorageResourceContainer eller StorageResourceItem. För en viss överföring måste källan och målet vara av samma slag. Om källan till exempel är en blobcontainer måste målet vara en blobcontainer.

Du kan starta en ny överföring genom att anropa följande metod:

Den här metoden returnerar ett TransferOperation-objekt som representerar överföringen. Du kan använda TransferOperation objektet för att övervaka överföringsstatusen eller hämta överförings-ID:t. Överförings-ID:t är en unik identifierare för överföringen som behövs för att återuppta en överföring eller pausa en överföring.

Du kan också ange en instans av TransferOptions till StartTransferAsync eller ResumeTransferAsync, som tillämpar vissa konfigurationsalternativ på en viss överföring. Följande konfigurationsalternativ är tillgängliga:

  • CreationMode: Konfigurerar beteendet när en överföring påträffar en resurs som redan finns. Standardvärdet är FailIfExists när du startar en ny överföring. När du återupptar en överföring kan standardinställningarna variera. För alla resurser som har räknats upp när överföringen startade är CreationMode standardvärdet det ursprungliga värde som används. För eventuella återstående resurser gäller det vanliga standardvärdet.
  • InitialTransferSize: Storleken på den första intervallbegäran i byte. Enstaka överföringsstorlekar som är mindre än den här gränsen laddas upp eller laddas ned i en enda begäran. Överföringar som är större än den här gränsen fortsätter att laddas ned eller laddas upp i segment av storleken MaximumTransferChunkSize. Standardvärdet är 32 MiB. När du återupptar en överföring är standardvärdet det värde som angavs när överföringen började.
  • MaximumTransferChunkSize: Den maximala storleken som ska användas för varje segment vid överföring av data i segment. Standardvärdet är 4 MiB. När du återupptar en överföring är standardvärdet det värde som angavs när överföringen började.
  • ProgressHandlerOptions: Valfritt. Alternativ för att ändra beteende för ProgressHandler.

Exempel: Ladda upp en lokal katalog till en blobcontainer

Följande kodexempel visar hur du startar en ny överföring för att ladda upp en lokal katalog till en blobcontainer:

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

Exempel: Kopiera en container eller blob

Du kan använda dataflyttbiblioteket för att kopiera mellan två StorageResource instanser. För blobresurser använder överföringen åtgärden Put Blob From URL ,som utför en server-till-server-kopia.

Följande kodexempel visar hur du startar en ny överföring för att kopiera alla blobar i en källblobcontainer till en målblobcontainer. Målcontainern måste redan finnas. I det här exemplet anger vi CreationMode till för OverwriteIfExists att skriva över alla målblobar som redan finns. Du kan justera CreationMode egenskapen baserat på appens behov.

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

I följande kodexempel visas hur du startar en ny överföring för att kopiera en källblob till en målblob. I det här exemplet anger vi CreationMode till för OverwriteIfExists att skriva över målbloben om den redan finns. Du kan justera CreationMode egenskapen baserat på appens behov.

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

Återuppta en befintlig överföring

Genom att spara överföringsförloppet till disken kan du med Data Movement-biblioteket återuppta en överföring som misslyckades före slutförandet, eller som på annat sätt avbröts eller pausades. För att återuppta en överföring TransferManager måste objektet konfigureras med StorageResourceProvider instanser som kan sätta ihop överföringen från de bevarade data igen. Du kan använda ProvidersForResuming egenskapen för klassen TransferManagerOptions för att ange providern.

I följande kodexempel visas hur du initierar ett TransferManager objekt som kan återuppta en överföring mellan det lokala filsystemet och Blob Storage:

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

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

Om du vill återuppta en överföring anropar du följande metod:

Ange överförings-ID för den överföring som du vill återuppta. Överförings-ID:t är en unik identifierare för överföringen som returneras som en del av TransferOperation objektet när överföringen startas. Om du inte känner till överförings-ID-värdet kan du anropa TransferManager.GetTransfersAsync för att hitta överföringen och dess motsvarande ID.

Följande kodexempel visar hur du återupptar en överföring:

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

Anteckning

Platsen för de bevarade överföringsdata skiljer sig från standardplatsen om TransferCheckpointStoreOptions anges som en del av TransferManagerOptions. Om du vill återuppta överföringar som registrerats med ett anpassat kontrollpunktsarkiv måste du ange samma alternativ för kontrollpunktsarkivet för objektet TransferManager som återupptar överföringen.

Övervaka överföringsstatus

Överföringar kan övervakas och observeras via flera mekanismer, beroende på appens behov. I det här avsnittet får du lära dig hur du övervakar överföringsframstatus med TransferOperation hjälp av objektet och hur du övervakar en överföring med hjälp av TransferOptions händelser.

Exempel: Övervaka överföringsstatus med hjälp av TransferOperation objektet

Du kan övervaka överföringsstatusen med hjälp av objektet TransferOperation som returneras av StartTransferAsync metoden. Du kan också anropa TransferManager.GetTransfersAsync för att räkna upp alla överföringar för ett TransferManager objekt.

I följande kodexempel visas hur du itererar över alla överföringar och skriver tillståndet för varje överföring till en loggfil:

C# 
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 definierar status för överföringsjobbet. TransferStatus innehåller följande egenskaper:

Property Type Beskrivning
HasCompletedSuccessfully Booleskt Representerar om överföringen slutförs utan fel eller överhoppade objekt.
HasFailedItems Booleskt Representerar om överföringen har några felobjekt. Om värdet är truehar överföringen minst ett felobjekt. Om värdet är falsehar överföringen för närvarande inga fel.
HasSkippedItems Booleskt Representerar om överföringen har några överhoppade objekt. Om värdet är truehar överföringen minst ett överhoppat objekt. Om värdet är falsehar överföringen för närvarande inga överhoppade objekt. Det går att aldrig hoppas över några objekt om SkipIfExists de inte är aktiverade i TransferOptions.CreationMode.
State TransferState Definierar vilka typer av tillstånd en överföring kan ha. Mer information finns i TransferState .

Exempel: Övervaka överföringsstatus med hjälp av TransferOptions händelser

Du kan övervaka överföringsförloppet genom att lyssna efter händelser som tillhandahålls av klassen TransferOptions . Instansen TransferOptionsStartTransferAsync skickas till metoden och tillhandahåller händelser som utlöses när en överföring slutförs, misslyckas, hoppas över eller ändrar status.

Följande kodexempel visar hur du lyssnar efter en överföringshändelse med hjälp av TransferOptions:

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

Använd tilläggsmetoder för BlobContainerClient

För program med befintlig kod som använder BlobContainerClient klassen från Azure.Storage.Blobs kan du använda tilläggsmetoder för att starta överföringar direkt från ett BlobContainerClient objekt. Tilläggsmetoderna finns i klassen BlobContainerClientExtensions (eller ShareDirectoryClientExtensions för Azure Files) och ger några av fördelarna med att använda TransferManager med minimala kodändringar. I det här avsnittet får du lära dig hur du använder tilläggsmetoderna för att utföra överföringar från ett BlobContainerClient objekt.

Installera Azure.Storage.Blobs-paketet om du inte redan har det:

.NET CLI 
dotnet add package Azure.Storage.Blobs

Lägg till följande using direktiv överst i kodfilen:

C# 
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;

I följande kodexempel visas hur du instansierar en BlobContainerClient för en blobcontainer med namnet sample-container:

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

Följande kodexempel visar hur du laddar upp lokalt kataloginnehåll till sample-container med hjälp av UploadDirectoryAsync:

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

await transfer.WaitForCompletionAsync();

Följande kodexempel visar hur du laddar ned innehållet i till en lokal katalog med hjälp av sample-containerDownloadToDirectoryAsync:

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

await transfer.WaitForCompletionAsync();

Mer information om tilläggsmetoderna för BlobContainerClientfinns i Tillägg på BlobContainerClient.

Gå vidare