Udostępnij za pośrednictwem

Przenoszenie danych za pomocą biblioteki przenoszenia danych

  • Artykuł

Biblioteka przenoszenia danych usługi Azure Storage to międzyplatformowa biblioteka typu open source przeznaczona do przekazywania, pobierania i kopiowania obiektów blob i plików o wysokiej wydajności. Biblioteka przenoszenia danych udostępnia wygodne metody, które nie są dostępne w bibliotece klienta usługi Azure Storage dla platformy .NET. Te metody umożliwiają ustawianie liczby operacji równoległych, śledzenie postępu transferu, wznawianie anulowanego transferu i nie tylko.

Biblioteka przenoszenia danych jest dostępna tylko dla platformy .NET i obsługuje tylko usługi Azure Blob Storage i Azure Files. Należy rozważyć te ograniczenia i inne znane problemy podczas podejmowania decyzji, czy używać biblioteki przenoszenia danych.

Jeśli migrujesz kod ze starszej biblioteki Microsoft.Azure.Storage.DataMovement (w wersji 2.X.X.X) do bieżącej biblioteki Azure.Storage.DataMovement (wersja 12.X.X.X), zobacz Przewodnik migracji.

Dokumentacja interfejsu API — pakiet kodu | źródłowego (NuGet) | | Przykłady: Blobs / Files.Shares

Wymagania wstępne

Konfigurowanie środowiska

Jeśli nie masz istniejącego projektu, w tej sekcji pokazano, jak skonfigurować projekt do pracy z biblioteką klienta usługi Azure Blob Storage dla platformy .NET. Kroki obejmują instalację pakietu, dodawanie using dyrektyw i tworzenie autoryzowanego obiektu klienta.

Instalowanie pakietów

Z katalogu projektu zainstaluj pakiety dla biblioteki klienta przenoszenia danych usługi Azure Storage i biblioteki klienta tożsamości platformy Azure przy użyciu dotnet add package polecenia . Pakiet Azure.Identity jest wymagany w przypadku połączeń bez hasła z usługami platformy Azure.

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

Aby pracować z biblioteką rozszerzeń dla usługi Azure Files, zainstaluj pakiet Azure.Storage.DataMovement.Files.Shares :

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

Dodawanie using dyrektyw

Aby uruchomić przykłady kodu w tym artykule, dodaj następujące using dyrektywy:

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

Jeśli używasz biblioteki rozszerzeń dla usługi Azure Files, dodaj następującą using dyrektywę:

using Azure.Storage.DataMovement.Files.Shares;

Autoryzacja

Mechanizm autoryzacji musi mieć niezbędne uprawnienia do wykonywania operacji przekazywania, pobierania lub kopiowania. Aby uzyskać autoryzację przy użyciu identyfikatora Entra firmy Microsoft (zalecane), potrzebujesz wbudowanej kontroli dostępu opartej na rolach platformy Azure współautora danych obiektów blob usługi Storage lub nowszego.

Informacje o bibliotece przenoszenia danych

Biblioteka przenoszenia danych usługi Azure Storage składa się z wspólnej biblioteki klienta i bibliotek rozszerzeń dla usług Azure Blob Storage i Azure Files. Wspólna biblioteka udostępnia podstawowe funkcje przesyłania danych, podczas gdy biblioteki rozszerzeń zapewniają funkcjonalność specyficzną dla usługi Blob Storage i Azure Files. Aby dowiedzieć się więcej, zobacz następujące zasoby:

Tworzenie TransferManager obiektu

TransferManager jest główną klasą do uruchamiania i kontrolowania wszystkich typów transferów, w tym przekazywania, pobierania i kopiowania. W tej sekcji dowiesz się, jak utworzyć TransferManager obiekt do pracy z lokalnym systemem plików, usługą Blob Storage lub usługą Azure Files.

Uwaga

Najlepszym rozwiązaniem do zarządzania klientami zestawu Azure SDK jest traktowanie klienta jako pojedynczego, co oznacza, że klasa ma tylko jeden obiekt naraz. Nie ma potrzeby przechowywania więcej niż jednego wystąpienia klienta dla danego zestawu parametrów konstruktora lub opcji klienta.

Poniższy kod pokazuje, jak utworzyć TransferManager obiekt:

TransferManager transferManager = new(new TransferManagerOptions());

Opcjonalnie można podać wystąpienie elementu TransferManagerOptions konstruktorowi, które stosuje pewne opcje konfiguracji do wszystkich transferów uruchomionych przez TransferManager obiekt. Dostępne są następujące opcje konfiguracji:

  • CheckpointStoreOptions: opcjonalne. Definiuje opcje tworzenia punktu kontrolnego używanego do zapisywania stanu transferu, aby można było wznowić transfery.
  • Diagnostyka: pobiera opcje diagnostyczne menedżera transferu.
  • ErrorHandling: opcjonalne. Definiuje sposób obsługi błędów podczas transferu. Wartość domyślna to StopOnAnyFailure.
  • MaximumConcurrency: maksymalna liczba procesów roboczych, które mogą być używane w transferze równoległym.
  • ProvidersForResuming: Dostawcy zasobów dla menedżera transferu do użycia w wznowieniu transferu. Oczekuje jednego dostawcy dla każdego dostawcy magazynu używanego. Aby dowiedzieć się więcej, zobacz Wznów istniejący transfer.

Tworzenie StorageResource obiektu

StorageResource to klasa bazowa dla wszystkich zasobów magazynu, w tym obiektów blob i plików. Aby utworzyć StorageResource obiekt, użyj jednej z następujących klas dostawcy:

Tworzenie StorageResource obiektu dla usługi Blob Storage

Poniższy kod pokazuje, jak utworzyć StorageResource obiekt dla kontenerów obiektów blob i obiektów blob przy użyciu elementu 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

Obiekt można również utworzyć StorageResource przy użyciu obiektu klienta z witryny 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

Rozpoczynanie nowego transferu

Wszystkie transfery muszą określać źródło i miejsce docelowe. Zarówno źródło, jak i lokalizacja docelowa to typ StorageResource, który może mieć StorageResourceContainer wartość lub StorageResourceItem. W przypadku danego transferu źródło i miejsce docelowe muszą być tego samego rodzaju. Jeśli na przykład źródło jest kontenerem obiektów blob, miejsce docelowe musi być kontenerem obiektów blob.

Nowy transfer można rozpocząć, wywołując następującą metodę:

Ta metoda zwraca obiekt TransferOperation reprezentujący transfer. Za pomocą TransferOperation obiektu można monitorować postęp transferu lub uzyskać identyfikator transferu. Identyfikator transferu to unikatowy identyfikator transferu potrzebny do wznowienia transferu lub wstrzymania transferu.

Opcjonalnie możesz podać wystąpienie funkcji TransferOptions do StartTransferAsync lub ResumeTransferAsync, które stosuje pewne opcje konfiguracji do określonego transferu. Dostępne są następujące opcje konfiguracji:

  • CreationMode: konfiguruje zachowanie, gdy transfer napotka już zasób, który już istnieje. Wartość domyślna to FailIfExists podczas uruchamiania nowego transferu. Po wznowieniu transferu wartości domyślne mogą się różnić. Dla wszystkich zasobów pomyślnie wyliczonych po rozpoczęciu CreationMode transferu domyślnie jest używana wartość początkowa. W przypadku pozostałych zasobów obowiązuje zwykła wartość domyślna.
  • InitialTransferSize: rozmiar pierwszego żądania zakresu w bajtach. Pojedyncze rozmiary transferu mniejsze niż ten limit są przekazywane lub pobierane w jednym żądaniu. Transfery większe niż ten limit są pobierane lub przekazywane we fragmentach o rozmiarze MaximumTransferChunkSize. Wartość domyślna to 32 MiB. Po wznowieniu transferu wartość domyślna to wartość określona podczas pierwszego uruchomienia transferu.
  • MaximumTransferChunkSize: maksymalny rozmiar używany dla każdego fragmentu podczas przesyłania danych we fragmentach. Wartość domyślna to 4 MiB. Po wznowieniu transferu wartość domyślna to wartość określona podczas pierwszego uruchomienia transferu.
  • ProgressHandlerOptions: opcjonalne. Opcje zmiany zachowania programu ProgressHandler.

Przykład: przekazywanie katalogu lokalnego do kontenera obiektów blob

W poniższym przykładzie kodu pokazano, jak rozpocząć nowy transfer w celu przekazania katalogu lokalnego do kontenera obiektów 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();

Przykład: kopiowanie kontenera lub obiektu blob

Bibliotekę przenoszenia danych można użyć do kopiowania między dwoma StorageResource wystąpieniami. W przypadku zasobów obiektów blob transfer używa operacji Put Blob From URL , która wykonuje kopię serwer-serwer.

W poniższym przykładzie kodu pokazano, jak rozpocząć nowy transfer w celu skopiowania wszystkich obiektów blob w źródłowym kontenerze obiektów blob do docelowego kontenera obiektów blob. Kontener docelowy musi już istnieć. W tym przykładzie ustawiliśmy wartość CreationMode , aby zastąpić OverwriteIfExists wszystkie docelowe obiekty blob, które już istnieją. Właściwość można dostosować CreationMode na podstawie potrzeb aplikacji.

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

Poniższy przykład kodu pokazuje, jak rozpocząć nowy transfer w celu skopiowania źródłowego obiektu blob do docelowego obiektu blob. W tym przykładzie ustawiliśmy wartość CreationMode , aby OverwriteIfExists zastąpić docelowy obiekt blob, jeśli już istnieje. Właściwość można dostosować CreationMode na podstawie potrzeb aplikacji.

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

Wznawianie istniejącego transferu

Utrzymując postęp transferu na dysku, biblioteka przenoszenia danych umożliwia wznowienie transferu, który zakończył się niepowodzeniem przed ukończeniem, lub został w inny sposób anulowany lub wstrzymany. Aby wznowić transfer, TransferManager obiekt musi być skonfigurowany z StorageResourceProvider wystąpieniami, które mogą ponownie rozsyłać transfer z utrwalonego danych. Aby określić dostawców, można użyć ProvidersForResuming właściwości klasy TransferManagerOptions .

W poniższym przykładzie kodu pokazano, jak zainicjować TransferManager obiekt, który może wznowić transfer między lokalnym systemem plików a usługą Blob Storage:

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

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

Aby wznowić transfer, wywołaj następującą metodę:

Podaj identyfikator transferu, który chcesz wznowić. Identyfikator transferu jest unikatowym identyfikatorem transferu zwróconego w ramach TransferOperation obiektu podczas uruchamiania transferu. Jeśli nie znasz wartości identyfikatora transferu, możesz wywołać metodę TransferManager.GetTransfersAsync , aby znaleźć transfer i odpowiadający mu identyfikator.

Poniższy przykład kodu pokazuje, jak wznowić transfer:

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

Uwaga

Lokalizacja utrwalonego transferu danych różni się od lokalizacji domyślnej, jeśli parametr TransferCheckpointStoreOptions jest ustawiony jako część TransferManagerOptions. Aby wznowić transfery zarejestrowane w niestandardowym magazynie punktów kontrolnych, należy podać te same opcje magazynu punktów kontrolnych dla TransferManager obiektu, który wznowi transfer.

Monitorowanie postępu transferu

Transfery mogą być monitorowane i obserwowane za pomocą kilku mechanizmów, w zależności od potrzeb aplikacji. W tej sekcji dowiesz się, jak monitorować postęp transferu przy użyciu obiektu oraz jak monitorować transfer przy użyciu TransferOperation zdarzeń TransferOptions .

Przykład: Monitorowanie postępu transferu przy użyciu TransferOperation obiektu

Postęp transferu można monitorować przy użyciu TransferOperation obiektu zwróconego przez metodę StartTransferAsync . Można również wywołać metodę TransferManager.GetTransfersAsync , aby wyliczyć wszystkie transfery dla TransferManager obiektu.

W poniższym przykładzie kodu pokazano, jak iterować wszystkie transfery i zapisywać stan każdego transferu do pliku dziennika:

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 definiuje stan zadania transferu. TransferStatus zawiera następujące właściwości:

Właściwość Type Opis
HasCompletedSuccessfully Logiczny Określa, czy transfer zakończy się pomyślnie bez żadnych niepowodzeń lub pominiętych elementów.
HasFailedItems Wartość logiczna Określa, czy transfer zawiera jakiekolwiek elementy niepowodzenia. Jeśli ustawiono wartość true, transfer ma co najmniej jeden element błędu. Jeśli ustawiono wartość false, transfer nie ma obecnie żadnych błędów.
HasSkippedItems Wartość logiczna Określa, czy transfer zawiera pominięte elementy. Jeśli ustawiono wartość true, transfer ma co najmniej jeden pominięty element. Jeśli ustawiono wartość false, transfer nie ma obecnie pominiętych elementów. Nie można nigdy pominąć żadnych elementów, jeśli SkipIfExists nie jest włączona w elemecie TransferOptions.CreationMode.
State TransferState Definiuje typy stanu, które może mieć transfer. Aby uzyskać szczegółowe informacje, zobacz TransferState .

Przykład: Monitorowanie postępu transferu przy użyciu TransferOptions zdarzeń

Postęp transferu można monitorować, nasłuchiwanie zdarzeń dostarczonych przez klasę TransferOptions . Wystąpienie TransferOptions jest przekazywane do metody i dostarcza zdarzenia wyzwalane po zakończeniu StartTransferAsync transferu, niepomyślnie, pomijaniu lub zmienianiu stanu.

Poniższy przykład kodu pokazuje, jak nasłuchiwać zdarzenia ukończenia transferu przy użyciu polecenia 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);
}

Używanie metod rozszerzeń dla BlobContainerClient

W przypadku aplikacji z istniejącym kodem używającym BlobContainerClient klasy Azure.Storage.Blobs można użyć metod rozszerzeń, aby rozpocząć transfery bezpośrednio z BlobContainerClient obiektu. Metody rozszerzenia są dostępne w klasie BlobContainerClientExtensions (lub ShareDirectoryClientExtensions dla usługi Azure Files) i zapewniają niektóre korzyści wynikające z używania TransferManager z minimalnymi zmianami kodu. W tej sekcji dowiesz się, jak używać metod rozszerzeń do wykonywania transferów z BlobContainerClient obiektu.

Zainstaluj pakiet Azure.Storage.Blobs, jeśli jeszcze go nie masz:

dotnet add package Azure.Storage.Blobs

Dodaj następujące using dyrektywy na początku pliku kodu:

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

W poniższym przykładzie kodu pokazano, jak utworzyć wystąpienie BlobContainerClient kontenera obiektów blob o nazwie 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");

W poniższym przykładzie kodu pokazano, jak przekazać zawartość katalogu lokalnego do sample-container metody :UploadDirectoryAsync

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

await transfer.WaitForCompletionAsync();

Poniższy przykład kodu pokazuje, jak pobrać zawartość sample-container do katalogu lokalnego przy użyciu polecenia DownloadToDirectoryAsync:

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

await transfer.WaitForCompletionAsync();

Aby dowiedzieć się więcej na temat metod rozszerzeń dla BlobContainerClientprogramu , zobacz Rozszerzenia w obiekcie BlobContainerClient.

Następny krok