Udostępnij za pośrednictwem

Przenoszenie danych za pomocą biblioteki przenoszenia danych

Biblioteka przesyłania danych Azure Storage to międzyplatformowa biblioteka open source przeznaczona do wysokowydajnego przekazywania, pobierania i kopiowania blobów i plików. 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 referencyjna API | Kod źródłowy | Pakiet (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

Dodaj using dyrektywy

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 Microsoft Entra ID (zalecane), potrzebujesz wbudowanej roli Azure RBAC Współtwórca danych obiektów blob pamięci lub wyższej.

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, jak obsługiwane są błędy 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 wykorzystania przy wznowieniu transferu. Oczekuje jednego dostawcy dla każdego używanego dostawcy magazynu. 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 blob i obiektów blob przy użyciu narzędzia 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

Można również utworzyć obiekt StorageResource przy użyciu obiektu klienta 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

Rozpoczynanie nowego transferu

Wszystkie transfery muszą określać źródło i miejsce docelowe. Zarówno źródło, jak i miejsce docelowe są typu StorageResource, który może być albo StorageResourceContainer, albo 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ć instancję TransferOptions do StartTransferAsync lub ResumeTransferAsync, które stosują pewne opcje konfiguracji do określonego transferu. Dostępne są następujące opcje konfiguracji:

  • CreationMode: konfiguruje zachowanie, gdy transfer napotka zasób, który 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, gdy transfer się rozpoczął, CreationMode domyślnie ustawia się na wartość początkową używaną. 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: przesyłanie lokalnego katalogu do kontenera blobów

W poniższym przykładzie kodu pokazano, jak rozpocząć nowy transfer w celu przeniesienia lokalnego katalogu do kontenera blobów.

// 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: Skopiować kontener lub blob

Można użyć biblioteki przenoszenia danych do kopiowania między dwoma StorageResource wystąpieniami. W przypadku zasobów typu blob transfer używa operacji Put Blob From URL, która wykonuje kopiowanie z serwera na 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 CreationMode na OverwriteIfExists, aby nadpisać wszystkie docelowe obiekty blob, które już istnieją. Możesz dostosować właściwość CreationMode w zależności od potrzeb swojej 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 ustawiamy CreationMode tak, aby OverwriteIfExists zastąpić docelowy obiekt blob, jeśli już istnieje. Możesz dostosować właściwość CreationMode w zależności od potrzeb swojej 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, obiekt TransferManager musi być skonfigurowany z wystąpieniami StorageResourceProvider, które mogą ponownie złożyć transfer z utrwalonych 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 unikalnym identyfikatorem transferu, który jest zwracany jako część obiektu TransferOperation, kiedy transfer jest uruchamiany. 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 wznawia transfer.

Monitoruj postęp 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 obiektu TransferOperation, 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ść Typ Opis
HasCompletedSuccessfully Logiczny Określa, czy transfer zakończy się pomyślnie bez żadnych niepowodzeń lub pominiętych elementów.
HasFailedItems Logiczny 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 Logiczny 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: Monitoruj postęp transferu używając zdarzeń TransferOptions

Monitoruj postęp transferu, nasłuchując na zdarzeniach dostarczonych przez klasę TransferOptions. Wystąpienie TransferOptions jest przekazywane do metody i dostarcza StartTransferAsync wyzwalane po zakończeniu 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żyj 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 dla 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 za pomocą 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 rozszerzających dla BlobContainerClient, zobacz Rozszerzenia dla BlobContainerClient.

Następny krok