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

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

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

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

Справочная документация API | Исходный код | Пакет (NuGet) | Примеры: Blobs / Files.Shares

Prerequisites

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

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

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

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

В каталоге вашего проекта установите пакеты клиентской библиотеки перемещения данных хранилища Azure и клиентской библиотеки Azure Identity с помощью команды 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;

Authorization

Механизм авторизации должен иметь необходимые разрешения для выполнения операций отправки, скачивания или копирования. Для авторизации с помощью Microsoft Entra ID (рекомендуется) требуется встроенная роль Azure RBAC Storage Blob Data Contributor или более высокая.

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

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

• Azure.Storage.DataMovement
• Azure.Storage.DataMovement.Blobs
• Azure.Storage.DataMovement.Files.Shares

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

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

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

TransferManager transferManager = new(new TransferManagerOptions());

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

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

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

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

• BlobsStorageResourceProvider: используйте этот класс для создания StorageResource экземпляров для контейнера BLOB, блочного блоба, блоба дополнения или страничного блоба.
• ShareFilesStorageResourceProvider: используйте этот класс для создания StorageResource экземпляров для файла или каталога.
• LocalFilesStorageResourceProvider: используйте этот класс для создания 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, который может быть либо StorageResourceContainer, либо StorageResourceItem. Для данной передачи источник и назначение должны быть одинаковыми. Например, если источник является контейнером BLOB, назначение должно быть контейнером BLOB.

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

• TransferManager.StartTransferAsync

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

При необходимости можно указать экземпляр TransferOptions, чтобы применить определенные параметры конфигурации к StartTransferAsync или 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();

Пример: Копирование контейнера или объекта BLOB

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

В следующем примере кода показано, как начать новую передачу для копирования всех объектов blob из исходного контейнера blob в целевой контейнер blob. Целевой контейнер должен уже существовать. В этом примере мы устанавливаем CreationMode как OverwriteIfExists, чтобы перезаписать любые объекты-назначения (blobs), которые уже существуют. Вы можете настроить 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 экземплярами, способными повторно сбирать передачу из сохраненных данных. Свойство ProvidersForResuming класса TransferManagerOptions используется для указания поставщиков.

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

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

Передачи можно отслеживать и наблюдать с помощью нескольких механизмов в зависимости от потребностей приложения. В этом разделе описано, как отслеживать ход передачи с помощью 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 включает следующие свойства:

Пример. Мониторинг хода передачи с помощью 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.