Перенос данных с помощью библиотеки перемещения данных

Библиотека перемещения данных службы хранилища Azure — это кроссплатформенная библиотека открытого кода, предназначенная для высокопроизводительной передачи, скачивания и копирования больших двоичных объектов и файлов. Библиотека перемещения данных предоставляет удобные методы, которые недоступны в клиентской библиотеке службы хранилища Azure для .NET. Эти методы позволяют задать количество параллельных операций, отслеживать ход передачи, возобновлять отмененную передачу и многое другое.

Библиотека перемещения данных доступна только для .NET и поддерживает только Хранилище BLOB-объектов Azure и Файлы Azure. При принятии решения об использовании библиотеки перемещения данных следует учитывать эти ограничения и другие известные проблемы .

Если вы переносите код из старой библиотеки Microsoft.Azure.Storage.DataMovement (версия 2.X.X) в текущую библиотеку Azure.Storage.DataMovement (версия 12.X.X),см. руководство по миграции.

Справочная документация | по API— пакет исходного кода | (NuGet) | Примеры: большие двоичные объекты / Files.Shares

Необходимые компоненты

• Подписка Azure — создайте бесплатную учетную запись.
• Учетная запись хранения Azure — создайте такую учетную запись.
• Последний пакет SDK для .NET для операционной системы. Обязательно получите пакет SDK, а не среду выполнения.

Настройка среды

Если у вас нет существующего проекта, в этом разделе показано, как настроить проект для работы с клиентской библиотекой Хранилище BLOB-объектов Azure для .NET. Ниже приведены шаги по установке пакета, добавлению using директив и созданию авторизованного клиентского объекта.

Установка пакетов

В каталоге проекта установите пакеты для клиентской библиотеки служба хранилища Azure перемещения данных и клиентской библиотеки удостоверений Azure с помощью dotnet add package команды. Пакет Azure.Identity необходим для бессерверных подключений к службам Azure.

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

Чтобы работать с библиотекой расширений для Файлы Azure, установите пакет Azure.Storage.DataMovement.Files.Shares:

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

Добавьте директивы using.

Чтобы запустить примеры кода в этой статье, добавьте следующие using директивы:

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

Если вы используете библиотеку расширений для Файлы Azure, добавьте следующую using директиву:

using Azure.Storage.DataMovement.Files.Shares;

Авторизация

Механизм авторизации должен иметь необходимые разрешения для выполнения операций отправки, скачивания или копирования. Для авторизации с помощью идентификатора Microsoft Entra (рекомендуется), требуется встроенный участник данных хранилища BLOB-объектов хранилища ролей или более поздней версии.

Сведения о библиотеке перемещения данных

Библиотека перемещения данных служба хранилища Azure состоит из общей клиентской библиотеки и библиотек расширений для Хранилище BLOB-объектов Azure и Файлы Azure. Общая библиотека предоставляет основные функции для передачи данных, а библиотеки расширений предоставляют функциональные возможности, относящиеся к хранилищу BLOB-объектов и Файлы Azure. Для получения дополнительных сведений ознакомьтесь со следующими ресурсами:

• Azure.Storage.DataMovement
• Blob-объекты Azure.Storage.DataMovement.Blobs
• Azure.Storage.DataMovement.Files.Shares

TransferManager Создание объекта

TransferManager — это основной класс для запуска и управления всеми типами передачи, включая отправку, скачивание и копирование. В этом разделе описано, как создать объект для работы с локальной файловой TransferManager системой, хранилищем BLOB-объектов или Файлы Azure.

Примечание.

Рекомендуется управлять клиентом пакета SDK Для Azure как одноэлементным, что означает, что класс имеет только один объект одновременно. Нет необходимости хранить несколько экземпляров клиента для заданного набора параметров конструктора или параметров клиента.

В следующем коде показано, как создать TransferManager объект:

TransferManager transferManager = new(new TransferManagerOptions());

При необходимости можно предоставить экземпляр TransferManagerOptions конструктору, который применяет определенные параметры конфигурации ко всем передачам, запущенным TransferManager объектом. Доступны следующие параметры конфигурации:

• CheckpointStoreOptions: необязательно. Определяет параметры создания контрольной точки, используемой для сохранения состояния передачи, чтобы можно было возобновить передачу.
• Диагностика: получает параметры диагностики диспетчера передачи.
• ErrorHandling: необязательно. Определяет способ обработки ошибок во время передачи. По умолчанию — StopOnAnyFailure.
• MaximumConcurrency: максимальное количество рабочих ролей, которые можно использовать в параллельной передаче.
• ProvidersForResuming: поставщики ресурсов для диспетчера передачи данных, которые будут использоваться при возобновлении передачи. Ожидается один поставщик для каждого используемого поставщика хранилища. Дополнительные сведения см. в статье "Возобновление существующей передачи".

StorageResource Создание объекта

StorageResource — это базовый класс для всех ресурсов хранилища, включая большие двоичные объекты и файлы. Чтобы создать StorageResource объект, используйте один из следующих классов поставщика:

• BlobsStorageResourceProvider: используйте этот класс для создания StorageResource экземпляров для контейнера BLOB-объектов, блочного BLOB-объекта, добавления большого двоичного объекта или страничного BLOB-объекта.
• ShareFilesStorageResourceProvider: используйте этот класс для создания StorageResource экземпляров для файла или каталога.
• LocalFilesStorageResourceProvider: используйте этот класс для создания StorageResource экземпляров для локальной файловой системы.

StorageResource Создание объекта для хранилища BLOB-объектов

В следующем коде показано, как создать StorageResource объект для контейнеров больших двоичных объектов и больших двоичных объектов с помощью 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

Вы также можете создать StorageResource объект с помощью клиентского объекта из 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

Запуск новой передачи

Все передачи должны указывать источник и назначение. Исходный и конечный типы — это тип StorageResource, который может быть либо StorageResourceContainerStorageResourceItemлибо. Для данной передачи источник и назначение должны быть одинаковыми. Например, если источник является контейнером BLOB-объектов, назначение должно быть контейнером BLOB-объектов.

Вы можете запустить новую передачу, вызвав следующий метод:

• TransferManager.StartTransferAsync

Этот метод возвращает объект TransferOperation , представляющий передачу. Объект можно использовать TransferOperation для мониторинга хода передачи или получения идентификатора передачи. Идентификатор передачи является уникальным идентификатором для передачи, необходимой для возобновления передачи или приостановки передачи.

При необходимости можно указать экземпляр TransferOptionsStartTransferAsync или ResumeTransferAsyncприменить определенные параметры конфигурации к определенной передаче. Доступны следующие параметры конфигурации:

• CreationMode: настраивает поведение при обнаружении ресурса, который уже существует. По умолчанию при запуске новой передачи FailIfExists . При возобновлении передачи значения по умолчанию могут отличаться. Для всех ресурсов, успешно перечисленных при запуске передачи, CreationMode по умолчанию используется исходное значение. Для остальных ресурсов применяется обычное значение по умолчанию.
• InitialTransferSize: размер первого запроса диапазона в байтах. Размеры одной передачи меньше, чем это ограничение, отправляются или скачиваются в одном запросе. Передача, превышающая это ограничение, продолжает загружаться или отправляться в блоки размера MaximumTransferChunkSize. Значение по умолчанию — 32 МиБ. При возобновлении передачи значение по умолчанию — это значение, указанное при первом запуске передачи.
• MaximumTransferChunkSize: максимальный размер, используемый для каждого блока при передаче данных в блоках. Значение по умолчанию — 4 МиБ. При возобновлении передачи значение по умолчанию — это значение, указанное при первом запуске передачи.
• ProgressHandlerOptions: необязательно. Параметры изменения поведения ProgressHandler.

Пример. Отправка локального каталога в контейнер BLOB-объектов

В следующем примере кода показано, как начать новую передачу для отправки локального каталога в контейнер 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();

Пример. Копирование контейнера или большого двоичного объекта

Библиотеку перемещения данных можно использовать для копирования между двумя StorageResource экземплярами. Для ресурсов BLOB-объектов передача использует операцию Put BLOB-адрес из URL-адреса , которая выполняет копию сервера на сервер.

В следующем примере кода показано, как начать новую передачу для копирования всех больших двоичных объектов в контейнер исходного большого двоичного объекта в целевой контейнер BLOB-объектов. К этому моменту целевой контейнер уже должен существовать. В этом примере мы зададим CreationMode значение OverwriteIfExists для перезаписи всех уже существующих больших двоичных объектов назначения. Вы можете настроить CreationMode свойство в зависимости от потребностей приложения.

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

В следующем примере кода показано, как начать новую передачу для копирования исходного большого двоичного объекта в целевой большой двоичный объект. В этом примере мы зададим CreationMode значение OverwriteIfExists для перезаписи целевого большого двоичного объекта, если он уже существует. Вы можете настроить CreationMode свойство в зависимости от потребностей приложения.

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

Возобновление существующей передачи

Сохраняя ход передачи на диск, библиотека перемещения данных позволяет возобновить передачу, которая завершилась сбоем или была отменена или приостановлена. Чтобы возобновить передачу, TransferManager объект должен быть настроен с StorageResourceProvider экземплярами, способными повторно сбирать передачу из сохраненных данных. Свойство класса TransferManagerOptions можно использовать ProvidersForResumingдля указания поставщиков.

В следующем примере кода показано, как инициализировать TransferManager объект, способный возобновить передачу между локальной файловой системой и хранилищем BLOB-объектов:

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

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

Чтобы возобновить передачу, вызовите следующий метод:

• TransferManager.ResumeTransferAsync

Укажите идентификатор передачи, который вы хотите возобновить. Идентификатор передачи — это уникальный идентификатор передачи, возвращаемой в рамках TransferOperation объекта при запуске передачи. Если вы не знаете значение идентификатора передачи, можно вызвать TransferManager.GetTransfersAsync , чтобы найти передачу и соответствующий идентификатор.

В следующем примере кода показано, как возобновить передачу:

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

Примечание.

Расположение сохраненных данных передачи отличается от расположения по умолчанию, если Параметр TransferCheckpointStoreOptions задан как часть TransferManagerOptions. Чтобы возобновить передачу, записанную с помощью пользовательского хранилища контрольных точек, необходимо предоставить те же параметры хранилища контрольных точек для TransferManager объекта, который возобновляет передачу.

Мониторинг хода передачи

Передачи можно отслеживать и наблюдать с помощью нескольких механизмов в зависимости от потребностей приложения. В этом разделе описано, как отслеживать ход передачи с помощью TransferOperation объекта и как отслеживать передачу с помощью TransferOptions событий.

Пример. Мониторинг хода передачи TransferOperation с помощью объекта

Вы можете отслеживать ход передачи с помощью объекта, TransferOperation возвращаемого методом StartTransferAsync . Вы также можете вызвать TransferManager.GetTransfersAsync , чтобы перечислить все передачи TransferManager для объекта.

В следующем примере кода показано, как выполнять итерацию по всем передачам и записывать состояние каждой передачи в файл журнала:

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 определяет состояние задания передачи. TransferStatus включает следующие свойства:

Свойство	Type	Описание
HasCompletedSuccessfully	Boolean	Представляет, успешно ли передача завершается без сбоя или пропущенных элементов.
HasFailedItems	Логический	Представляет, есть ли у передачи элементы сбоя. Если задано значение true, передача имеет по крайней мере один элемент сбоя. Если задано значение false, передача в данный момент не имеет сбоев.
HasSkippedItems	Логический	Представляет, есть ли у передачи пропущенные элементы. Если задано значение true, передача имеет по крайней мере один пропущенный элемент. Если задано значение false, передача в настоящее время не пропускает элементы. Если не включена функция TransferOptions.CreationMode, можно никогда не пропускать SkipIfExists какие-либо элементы.
State	TransferState	Определяет типы состояния, которые может иметь передача. Дополнительные сведения см. в разделе TransferState .

Пример. Мониторинг хода передачи с помощью TransferOptions событий

Вы можете отслеживать ход передачи, прослушивая события, предоставляемые классом TransferOptions . Экземпляр TransferOptions передается методу StartTransferAsync и предоставляет события , которые активируются при завершении передачи, сбое, пропускаются или изменяют состояние.

В следующем примере кода показано, как прослушивать событие завершения передачи с помощью 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);
}

Использование методов расширения для BlobContainerClient

Для приложений с существующим кодом, использующим BlobContainerClient класс из Azure.Storage.Blobs, можно использовать методы расширения для запуска передачи непосредственно из BlobContainerClient объекта. Методы расширения предоставляются в классе BlobContainerClientExtensions (или ShareDirectoryClientExtensions для Файлы Azure) и предоставляют некоторые преимущества использования TransferManager с минимальными изменениями кода. В этом разделе описано, как использовать методы расширения для выполнения передачи из BlobContainerClient объекта.

Установите пакет Azure.Storage.Blobs, если у вас еще нет:

dotnet add package Azure.Storage.Blobs

Добавьте следующие using директивы в начало файла кода:

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

В следующем примере кода показано, как создать экземпляр BlobContainerClient контейнера BLOB-объектов с именем 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");

В следующем примере кода показано, как отправить содержимое локального каталога в sample-container использование UploadDirectoryAsync:

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

await transfer.WaitForCompletionAsync();

В следующем примере кода показано, как скачать содержимое локального sample-container каталога с помощью DownloadToDirectoryAsync:

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

await transfer.WaitForCompletionAsync();

Дополнительные сведения о методах расширения см BlobContainerClient. в разделе Extensions on BlobContainerClient.

Следующий шаг

• Примеры кода для DataMovement.Blobs и DataMovement.Files.Shares доступны в репозитории Azure SDK для .NET GitHub.