Azure Data Lake Storage 2. Nesil dizinleri ve dosyaları yönetmek için .NET kullanma

  • Makale

Bu makalede, hiyerarşik ad alanına sahip depolama hesaplarında dizinleri ve dosyaları oluşturmak ve yönetmek için .NET'in nasıl kullanılacağı gösterilmektedir.

Dizinlerin ve dosyaların erişim denetim listelerini (ACL) alma, ayarlama ve güncelleştirme hakkında bilgi edinmek için bkz. Azure Data Lake Storage 2. Nesil'da ACL'leri yönetmek için .NET kullanma.

Paket (NuGet) | Örnekler | API başvurusu | 1. Nesil ile 2. Nesil eşlemesi | Geri Bildirim Ver

Önkoşullar

Projenizi ayarlama

Başlamak için Azure.Depolama yükleyin. Files.DataLake NuGet paketi.

NuGet paketlerini yükleme hakkında daha fazla bilgi için bkz. NuGet Paket Yöneticisi kullanarak Visual Studio'da paketleri yükleme ve yönetme.

Ardından, bunları kod dosyanızın en üstüne using deyimleri ekleyin.

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

Not

Data Lake Depolama üzerinde çok protokollü erişim, uygulamaların hiyerarşik ad alanı (HNS) etkinleştirilmiş depolama hesaplarındaki verilerle çalışmak için hem Blob API'lerini hem de Data Lake Storage 2. Nesil API'lerini kullanmasını sağlar. Dizin işlemleri ve ACL'ler gibi Data Lake Storage 2. Nesil benzersiz özelliklerle çalışırken, bu makalede gösterildiği gibi Data Lake Storage 2. Nesil API'lerini kullanın.

Belirli bir senaryoda kullanılacak API'leri seçerken, HNS'nin iş yükleri ve uygulamalar üzerindeki bilinen sorunları ve etkisinin yanı sıra uygulamanızın iş yükünü ve gereksinimlerini göz önünde bulundurun.

Erişimi yetkilendirme ve veri kaynaklarına bağlanma

Bu makaledeki kod örnekleriyle çalışmak için depolama hesabını temsil eden yetkili bir DataLakeServiceClient örneği oluşturmanız gerekir. Bir nesneyi Microsoft Entra Id, hesap erişim anahtarı veya paylaşılan erişim imzası (SAS) kullanarak yetkilandırabilirsiniz DataLakeServiceClient .

Microsoft Entra ID ile uygulamanızın kimliğini doğrulamak için .NET için Azure kimlik istemci kitaplığını kullanabilirsiniz.

DataLakeServiceClient örneği oluşturun ve DefaultAzureCredential sınıfının yeni bir örneğini geçirin.

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;
}

Verilere erişimi yetkilendirmek için kullanma DefaultAzureCredential hakkında daha fazla bilgi edinmek için bkz . Azure hizmetleriyle .NET uygulamalarının kimliğini doğrulama.

Kapsayıcı oluşturma

Kapsayıcı, dosyalarınız için dosya sistemi görevi görür. Aşağıdaki yöntemi kullanarak kapsayıcı oluşturabilirsiniz:

Aşağıdaki kod örneği bir kapsayıcı oluşturur ve daha sonra kullanmak üzere bir DataLakeFileSystemClient nesnesi döndürür:

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

Dizin oluşturma

Aşağıdaki yöntemi kullanarak kapsayıcıda dizin başvurusu oluşturabilirsiniz:

Aşağıdaki kod örneği kapsayıcıya bir dizin ekler, ardından bir alt dizin ekler ve daha sonra kullanmak üzere bir DataLakeDirectoryClient nesnesi döndürür:

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

    return await directoryClient.CreateSubDirectoryAsync(subdirectoryName);
}

Bir dizini yeniden adlandırma veya taşıma

Aşağıdaki yöntemi kullanarak dizini yeniden adlandırabilir veya taşıyabilirsiniz:

İstenen dizinin yolunu parametre olarak geçirin. Aşağıdaki kod örneğinde bir alt dizinin nasıl yeniden adlandırılası gösterilmektedir:

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

Aşağıdaki kod örneğinde bir alt dizinin bir dizinden farklı bir dizine nasıl taşınacakları gösterilmektedir:

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

Dizine dosya yükleme

Aşağıdaki yöntemi kullanarak içeriği yeni veya mevcut bir dosyaya yükleyebilirsiniz:

Aşağıdaki kod örneği, yöntemini kullanarak yerel bir dosyanın bir dizine nasıl yüklendiğini UploadAsync gösterir:

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

Bu yöntemi kullanarak yeni bir dosyaya içerik oluşturabilir ve karşıya yükleyebilir veya parametresini overwrite varolan bir dosyanın üzerine yazacak şekilde true ayarlayabilirsiniz.

Dosyaya veri ekleme

Aşağıdaki yöntemi kullanarak bir dosyaya eklenecek verileri karşıya yükleyebilirsiniz:

Aşağıdaki kod örneği, aşağıdaki adımları kullanarak dosyanın sonuna veri eklemeyi gösterir:

  • Üzerinde çalıştığınız dosya kaynağını temsil eden bir DataLakeFileClient nesnesi oluşturun.
  • DataLakeFileClient.AppendAsync yöntemini kullanarak verileri dosyaya yükleyin.
  • Daha önce karşıya yüklenen verileri dosyaya yazmak için DataLakeFileClient.FlushAsync yöntemini çağırarak karşıya yüklemeyi tamamlayın.
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);
}

Dizinden indirme

Aşağıdaki kod örneğinde, aşağıdaki adımları kullanarak bir dizinden yerel dosyaya dosya indirme işlemi gösterilmektedir:

  • İndirmek istediğiniz dosyayı temsil eden bir DataLakeFileClient örneği oluşturun.
  • DataLakeFileClient.ReadAsync yöntemini kullanın, ardından bir Stream nesnesi almak için dönüş değerini ayrıştırın. Akıştan dosyaya bayt kaydetmek için herhangi bir .NET dosya işleme API'sini kullanın.

Bu örnekte, dosyaya bayt kaydetmek için BinaryReader ve FileStream kullanılır.

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

Dizin içeriğini listeleme

Dizin içeriğini listelemek için aşağıdaki yöntemi kullanabilir ve sonucu numaralandırabilirsiniz:

Sonuçta yolların numaralandırılması, değerleri getirirken hizmete birden çok istekte bulunabilir.

Aşağıdaki kod örneği, bir dizinde bulunan her dosyanın adlarını yazdırır:

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;
    }

}

Bir dizini silme

Aşağıdaki yöntemi kullanarak bir dizini silebilirsiniz:

Aşağıdaki kod örneğinde bir dizinin nasıl silineceği gösterilmektedir:

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

    await directoryClient.DeleteAsync();
}

Geçici olarak silinen dizini geri yükleme

Geçici olarak silinen bir dizini geri yüklemek için Azure Depolama istemci kitaplıklarını kullanabilirsiniz. DataLakeFileSystemClient örneğinin silinmiş yollarını listelemek için aşağıdaki yöntemi kullanın:

Geçici olarak silinen bir dizini geri yüklemek için aşağıdaki yöntemi kullanın:

Aşağıdaki kod örneğinde silinen yolları listeleme ve geçici olarak silinmiş bir dizini geri yükleme işlemleri gösterilmektedir:

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

Geçici olarak silinen öğeleri içeren dizini yeniden adlandırırsanız, bu öğelerin dizinle bağlantısı kesilir. Bu öğeleri geri yüklemek istiyorsanız, dizinin adını özgün adına geri döndürmeniz veya özgün dizin adını kullanan ayrı bir dizin oluşturmanız gerekir. Aksi takdirde, geçici olarak silinen öğeleri geri yüklemeye çalıştığınızda bir hata alırsınız.

Dizin için kullanıcı temsilcisi SAS'i oluşturma

Bu bölümdeki kod örnekleriyle çalışmak için aşağıdaki using yönergeyi ekleyin:

using Azure.Storage.Sas;

Aşağıdaki kod örneğinde, depolama hesabı için hiyerarşik bir ad alanı etkinleştirildiğinde dizin için kullanıcı temsilcisi SAS'sinin nasıl oluşturulacağı gösterilmektedir:

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;
    }
}

Aşağıdaki örnek, bir sanal istemci uygulamasından önceki örnekte oluşturulan kullanıcı temsilcisi SAS'sini test eder. SAS geçerliyse, istemci uygulaması bu dizin için dosya yollarını listeleyebiliyor. SAS geçersizse (örneğin, SAS'nin süresi dolduysa), Depolama hizmeti 403 (Yasak) hata kodunu döndürür.

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;
        }
    }
}

Kullanıcı temsilcisi SAS'i oluşturma hakkında daha fazla bilgi edinmek için bkz . .NET ile kullanıcı temsilcisi SAS'ı oluşturma.

Dizin için hizmet SAS'i oluşturma

Hiyerarşik ad alanı etkinleştirilmiş bir depolama hesabında, bir dizin için hizmet SAS'i oluşturabilirsiniz. Hizmet SAS'sini oluşturmak için Azure.Depolama 12.5.0 veya sonraki bir sürümünü yüklediğinizden emin olun. Files.DataLake paketi.

Aşağıdaki örnekte, bir dizin için hizmet SAS'sinin nasıl oluşturulacağı gösterilmektedir:

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;
    }
}

Hizmet SAS'i oluşturma hakkında daha fazla bilgi edinmek için bkz . .NET ile hizmet SAS'i oluşturma.

Ayrıca bkz.