Управление каталогами и файлами в Azure Data Lake Storage 2-го поколения с помощью .NET

Статья
04/09/2024

В этой статье показано, как использовать .NET для создания каталогов и файлов в учетных записях хранения с иерархическим пространством имен, а также управления ими.

Дополнительные сведения о получении, установке и обновлении списков управления доступом (ACL) для каталогов и файлов см. в разделе Использование .NET для управления списками ACL в Azure Data Lake Storage 2-го поколения.

Пакет (NuGet) | Примеры | Справочник по API | Сопоставление Gen1 с Gen2 | Отправить отзыв

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

Подписка Azure. См. страницу бесплатной пробной версии Azure.
Учетная запись хранения, в которой включено иерархическое пространство имен. Выполните эти инструкции, чтобы создать учетную запись.

Настройка проекта

Чтобы приступить к работе, установите пакет NuGet Azure.Storage.Files.DataLake.

Дополнительные сведения об установке пакетов NuGet см. в статье Установка пакетов в Visual Studio и управление ими с помощью диспетчера пакетов NuGet.

После этого добавьте это в начало файла кода.

using Azure;
using Azure.Storage.Files.DataLake;
using Azure.Storage.Files.DataLake.Models;
using Azure.Storage;
using System.IO;

Примечание.

Доступ с несколькими протоколами в Data Lake служба хранилища позволяет приложениям использовать API BLOB-объектов и DATA LAKE STORAGE 2-ГО ПОКОЛЕНИЯ API для работы с данными в учетных записях хранения с включенным иерархическим пространством имен (HNS). При работе с возможностями, уникальными для Data Lake Storage 2-го поколения, таких как операции каталогов и списки управления доступом, используйте API Data Lake Storage 2-го поколения, как показано в этой статье.

При выборе API для использования в данном сценарии рассмотрите рабочую нагрузку и потребности приложения, а также известные проблемы и влияние HNS на рабочие нагрузки и приложения.

Авторизация доступа к ресурсам данных и подключение к ним

Для работы с примерами кода в этой статье необходимо создать авторизованный экземпляр DataLakeServiceClient , представляющий учетную запись хранения. Вы можете авторизовать DataLakeServiceClient объект с помощью идентификатора Microsoft Entra, ключа доступа к учетной записи или подписанного URL-адреса (SAS).

Клиентская библиотека удостоверений Azure для .NET можно использовать для проверки подлинности приложения с помощью идентификатора Microsoft Entra.

Создайте экземпляр DataLakeServiceClient и передайте новый экземпляр класса DefaultAzureCredential.

public static DataLakeServiceClient GetDataLakeServiceClient(string accountName)
{
    string dfsUri = $"https://{accountName}.dfs.core.windows.net";

    DataLakeServiceClient dataLakeServiceClient = new DataLakeServiceClient(
        new Uri(dfsUri),
        new DefaultAzureCredential());

    return dataLakeServiceClient;
}

Дополнительные сведения об использовании DefaultAzureCredential для авторизации доступа к данным см. в статье "Проверка подлинности приложений .NET с помощью служб Azure".

Чтобы использовать маркер подписанного URL-адреса (SAS), предоставьте маркер в виде строки и инициализировать объект DataLakeServiceClient . Если URL-адрес учетной записи содержит маркер SAS, опустите параметр учетных данных.

public static DataLakeServiceClient GetDataLakeServiceClientSAS(string accountName, string sasToken)
{
    string dfsUri = $"https://{accountName}.dfs.core.windows.net";

    DataLakeServiceClient dataLakeServiceClient = new DataLakeServiceClient(
        new Uri(dfsUri),
        new AzureSasCredential(sasToken));

    return dataLakeServiceClient;
}

Дополнительные сведения о создании маркеров SAS и управлении ими см. в следующей статье:

Предоставление ограниченного доступа к ресурсам службы хранилища Azure с помощью подписанных URL-адресов (SAS)

Вы можете авторизовать доступ к данным с помощью ключей доступа к учетной записи (общий ключ). В этом примере создается экземпляр DataLakeServiceClient, авторизованный с помощью ключа учетной записи.

public static DataLakeServiceClient GetDataLakeServiceClient(string accountName, string accountKey)
{
    StorageSharedKeyCredential sharedKeyCredential =
        new StorageSharedKeyCredential(accountName, accountKey);

    string dfsUri = $"https://{accountName}.dfs.core.windows.net";

    DataLakeServiceClient dataLakeServiceClient = new DataLakeServiceClient(
        new Uri(dfsUri),
        sharedKeyCredential);

    return dataLakeServiceClient;
}

Внимание

Авторизация с помощью общего ключа не рекомендуется, так как она может быть менее безопасной. Чтобы обеспечить оптимальную безопасность, отключите авторизацию через общий ключ для учетной записи хранения, как описано в разделе "Запрет авторизации общего ключа" для учетной записи служба хранилища Azure.

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

Корпорация Майкрософт рекомендует клиентам использовать идентификатор Microsoft Entra или подписанный URL-адрес (SAS), чтобы авторизовать доступ к данным в служба хранилища Azure. Дополнительные сведения см. в разделе "Авторизация операций для доступа к данным".

Создание контейнера

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

DataLakeServiceClient.CreateFileSystem

В следующем примере кода создается контейнер и возвращается объект DataLakeFileSystemClient для последующего использования:

public async Task<DataLakeFileSystemClient> CreateFileSystem(
    DataLakeServiceClient serviceClient,
    string fileSystemName)
{
    return await serviceClient.CreateFileSystemAsync(fileSystemName);
}

Создание каталога

Ссылку на каталог в контейнере можно создать с помощью следующего метода:

DataLakeFileSystemClient.CreateDirectoryAsync

Следующий пример кода добавляет каталог в контейнер, затем добавляет подкаталог и возвращает объект DataLakeDirectoryClient для последующего использования:

public async Task<DataLakeDirectoryClient> CreateDirectory(
    DataLakeFileSystemClient fileSystemClient,
    string directoryName,
    string subdirectoryName)
{
    DataLakeDirectoryClient directoryClient =
        await fileSystemClient.CreateDirectoryAsync(directoryName);

    return await directoryClient.CreateSubDirectoryAsync(subdirectoryName);
}

Переименование или перемещение каталога

Вы можете переименовать или переместить каталог с помощью следующего метода:

DataLakeDirectoryClient.RenameAsync

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

public async Task<DataLakeDirectoryClient> RenameDirectory(
    DataLakeFileSystemClient fileSystemClient,
    string directoryPath,
    string subdirectoryName,
    string subdirectoryNameNew)
{
    DataLakeDirectoryClient directoryClient =
        fileSystemClient.GetDirectoryClient(string.Join('/', directoryPath, subdirectoryName));

    return await directoryClient.RenameAsync(string.Join('/', directoryPath, subdirectoryNameNew));
}

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

public async Task<DataLakeDirectoryClient> MoveDirectory(
    DataLakeFileSystemClient fileSystemClient,
    string directoryPathFrom,
    string directoryPathTo,
    string subdirectoryName)
{
    DataLakeDirectoryClient directoryClient =
         fileSystemClient.GetDirectoryClient(string.Join('/', directoryPathFrom, subdirectoryName));

    return await directoryClient.RenameAsync(string.Join('/', directoryPathTo, subdirectoryName));
}

Отправка файла в каталог

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

DataLakeFileClient.UploadAsync

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

public async Task UploadFile(
    DataLakeDirectoryClient directoryClient,
    string fileName,
    string localPath)
{
    DataLakeFileClient fileClient = 
        directoryClient.GetFileClient(fileName);

    FileStream fileStream = File.OpenRead(localPath);

    await fileClient.UploadAsync(content: fileStream, overwrite: true);
}

Этот метод можно использовать для создания и отправки содержимого в новый файл или overwritetrue для перезаписи существующего файла.

Добавление данных в файл

Данные можно добавить в файл с помощью следующего метода:

DataLakeFileClient.AppendAsync

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

Создайте объект DataLakeFileClient, чтобы представить файловый ресурс, с которым вы работаете.
Отправьте данные в файл с помощью метода DataLakeFileClient.AppendAsync .
Завершите отправку , вызвав метод DataLakeFileClient.FlushAsync , чтобы записать ранее отправленные данные в файл.

public async Task AppendDataToFile(
    DataLakeDirectoryClient directoryClient,
    string fileName,
    Stream stream)
{
    DataLakeFileClient fileClient = 
        directoryClient.GetFileClient(fileName);

    long fileSize = fileClient.GetProperties().Value.ContentLength;

    await fileClient.AppendAsync(stream, offset: fileSize);

    await fileClient.FlushAsync(position: fileSize + stream.Length);
}

Скачивание из каталога

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

Создайте экземпляр DataLakeFileClient для представления файла, который требуется скачать.
Используйте метод DataLakeFileClient.ReadAsync, а затем синтаксический анализ возвращаемого значения для получения объекта Stream. Используйте любой API-интерфейс обработки файлов .NET для сохранения байтов из потока в файл.

В этом примере для сохранения байтов в файл используются объекты BinaryReader и FileStream.

public async Task DownloadFile(
    DataLakeDirectoryClient directoryClient,
    string fileName,
    string localPath)
{
    DataLakeFileClient fileClient =
        directoryClient.GetFileClient(fileName);

    Response<FileDownloadInfo> downloadResponse = await fileClient.ReadAsync();

    BinaryReader reader = new BinaryReader(downloadResponse.Value.Content);

    FileStream fileStream = File.OpenWrite(localPath);

    int bufferSize = 4096;

    byte[] buffer = new byte[bufferSize];

    int count;

    while ((count = reader.Read(buffer, 0, buffer.Length)) != 0)
    {
        fileStream.Write(buffer, 0, count);
    }

    await fileStream.FlushAsync();

    fileStream.Close();
}

Вывод содержимого каталогов

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

FileSystemClient.GetPathsAsync

Перечисление путей в результате может выполнять несколько запросов к службе при выборе значений.

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

public async Task ListFilesInDirectory(
    DataLakeFileSystemClient fileSystemClient,
    string directoryName)
{
    IAsyncEnumerator<PathItem> enumerator =
        fileSystemClient.GetPathsAsync(directoryName).GetAsyncEnumerator();

    await enumerator.MoveNextAsync();

    PathItem item = enumerator.Current;

    while (item != null)
    {
        Console.WriteLine(item.Name);

        if (!await enumerator.MoveNextAsync())
        {
            break;
        }

        item = enumerator.Current;
    }

}

Удаление каталога

Вы можете удалить каталог с помощью следующего метода:

DataLakeDirectoryClient.Delete

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

public async Task DeleteDirectory(
    DataLakeFileSystemClient fileSystemClient,
    string directoryName)
{
    DataLakeDirectoryClient directoryClient =
        fileSystemClient.GetDirectoryClient(directoryName);

    await directoryClient.DeleteAsync();
}

Восстановление обратимого удаленного каталога

Для восстановления обратимого удаленного каталога можно использовать клиентские библиотеки служба хранилища Azure. Используйте следующий метод для перечисления удаленных путей для экземпляра DataLakeFileSystemClient :

GetDeletedPathsAsync

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

Отмена letePathAsync

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

public async Task RestoreDirectory(
    DataLakeFileSystemClient fileSystemClient,
    string directoryName)
{
    DataLakeDirectoryClient directoryClient =
        fileSystemClient.GetDirectoryClient(directoryName);

    // List deleted paths
    List<PathDeletedItem> deletedItems = new List<PathDeletedItem>();
    await foreach (PathDeletedItem deletedItem in fileSystemClient.GetDeletedPathsAsync(directoryName))
    {
        deletedItems.Add(deletedItem);
    }

    // Restore deleted directory
    Response<DataLakePathClient> restoreResponse = await fileSystemClient.UndeletePathAsync(
        deletedItems[0].Path,
        deletedItems[0].DeletionId);
}

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

Создание SAS делегирования пользователей для каталога

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

using Azure.Storage.Sas;

В следующем примере кода показано, как создать SAS для делегирования пользователей для каталога, если для учетной записи хранения включено иерархическое пространство имен:

async static Task<Uri> GetUserDelegationSasDirectory(DataLakeDirectoryClient directoryClient)
{
    try
    {
        // Get service endpoint from the directory URI.
        DataLakeUriBuilder dataLakeServiceUri = new DataLakeUriBuilder(directoryClient.Uri)
        {
            FileSystemName = null,
            DirectoryOrFilePath = null
        };

        // Get service client.
        DataLakeServiceClient dataLakeServiceClient =
            new DataLakeServiceClient(dataLakeServiceUri.ToUri(),
                                      new DefaultAzureCredential());

        // Get a user delegation key that's valid for seven days.
        // You can use the key to generate any number of shared access signatures 
        // over the lifetime of the key.
        Azure.Storage.Files.DataLake.Models.UserDelegationKey userDelegationKey =
            await dataLakeServiceClient.GetUserDelegationKeyAsync(DateTimeOffset.UtcNow,
                                                                  DateTimeOffset.UtcNow.AddDays(7));

        // Create a SAS token that's valid for seven days.
        DataLakeSasBuilder sasBuilder = new DataLakeSasBuilder()
        {
            // Specify the file system name and path, and indicate that
            // the client object points to a directory.
            FileSystemName = directoryClient.FileSystemName,
            Resource = "d",
            IsDirectory = true,
            Path = directoryClient.Path,
            ExpiresOn = DateTimeOffset.UtcNow.AddDays(7)
        };

        // Specify racwl permissions for the SAS.
        sasBuilder.SetPermissions(
            DataLakeSasPermissions.Read |
            DataLakeSasPermissions.Add |
            DataLakeSasPermissions.Create |
            DataLakeSasPermissions.Write |
            DataLakeSasPermissions.List
            );

        // Construct the full URI, including the SAS token.
        DataLakeUriBuilder fullUri = new DataLakeUriBuilder(directoryClient.Uri)
        {
            Sas = sasBuilder.ToSasQueryParameters(userDelegationKey,
                                                  dataLakeServiceClient.AccountName)
        };

        Console.WriteLine("Directory user delegation SAS URI: {0}", fullUri);
        Console.WriteLine();
        return fullUri.ToUri();
    }
    catch (Exception e)
    {
        Console.WriteLine(e.Message);
        throw;
    }
}

В следующем примере выполняется проверка SAS для делегирования пользователя, созданного в предыдущем примере, из имитированного клиентского приложения. Если SAS является допустимым, клиентское приложение сможет вывести пути к файлам для этого каталога. Если SAS недопустим (например, срок действия SAS истек), служба служба хранилища возвращает код ошибки 403 (запрещено).

private static async Task ListFilesPathsWithDirectorySasAsync(Uri sasUri)
{
    // Try performing an operation using the directory SAS provided.

    // Create a directory client object for listing operations.
    DataLakeDirectoryClient dataLakeDirectoryClient = new DataLakeDirectoryClient(sasUri);

    // List file paths in the directory.
    try
    {
        // Call the listing operation and return pages of the specified size.
        var resultSegment = dataLakeDirectoryClient.GetPathsAsync(false, false).AsPages();

        // Enumerate the file paths returned with each page.
        await foreach (Page<PathItem> pathPage in resultSegment)
        {
            foreach (PathItem pathItem in pathPage.Values)
            {
                Console.WriteLine("File name: {0}", pathItem.Name);
            }
            Console.WriteLine();
        }

        Console.WriteLine();
        Console.WriteLine("Directory listing operation succeeded for SAS {0}", sasUri);
    }
    catch (RequestFailedException e)
    {
        // Check for a 403 (Forbidden) error. If the SAS is invalid, 
        // Azure Storage returns this error.
        if (e.Status == 403)
        {
            Console.WriteLine("Directory listing operation failed for SAS {0}", sasUri);
            Console.WriteLine("Additional error information: " + e.Message);
            Console.WriteLine();
        }
        else
        {
            Console.WriteLine(e.Message);
            Console.ReadLine();
            throw;
        }
    }
}

Дополнительные сведения о создании SAS делегирования пользователей см. в статье "Создание SAS делегирования пользователей с помощью .NET".

Создание SAS службы для каталога

Вы можете создать SAS службы для каталога в учетной записи хранения с включенным иерархическим пространством имен. Чтобы создать SAS службы, убедитесь, что у вас установлена версия 12.5.0 или более поздняя версия пакета Azure.Storage.Files.DataLake.

В следующем примере показано, как создать SAS службы для каталога:

private static Uri GetServiceSasUriForDirectory(DataLakeDirectoryClient directoryClient,
                                          string storedPolicyName = null)
{
    if (directoryClient.CanGenerateSasUri)
    {
        // Create a SAS token that's valid for one hour.
        DataLakeSasBuilder sasBuilder = new DataLakeSasBuilder()
        {
            // Specify the file system name, the path, and indicate that
            // the client object points to a directory.
            FileSystemName = directoryClient.FileSystemName,
            Resource = "d",
            IsDirectory = true,
            Path = directoryClient.Path,
        };

        // If no stored access policy is specified, create the policy
        // by specifying expiry and permissions.
        if (storedPolicyName == null)
        {
            sasBuilder.ExpiresOn = DateTimeOffset.UtcNow.AddHours(1);
            sasBuilder.SetPermissions(DataLakeSasPermissions.Read |
                DataLakeSasPermissions.Write |
                DataLakeSasPermissions.List);
        }
        else
        {
            sasBuilder.Identifier = storedPolicyName;
        }

        // Get the SAS URI for the specified directory.
        Uri sasUri = directoryClient.GenerateSasUri(sasBuilder);
        Console.WriteLine("SAS URI for ADLS directory is: {0}", sasUri);
        Console.WriteLine();

        return sasUri;
    }
    else
    {
        Console.WriteLine(@"DataLakeDirectoryClient must be authorized with Shared Key 
                          credentials to create a service SAS.");
        return null;
    }
}

Дополнительные сведения о создании SAS службы см. в статье "Создание SAS службы с помощью .NET".