مشاركة عبر

استخدام .NET لإدارة الدلائل والملفات في Azure Data Lake Storage

  • مقالة

توضح لك هذه المقالة كيفية استخدام .NET لإنشاء الدلائل والملفات وإدارتها في حسابات التخزين التي تحتوي على مساحة أسماء هرمية.

للتعرف على كيفية الحصول على قوائم التحكم في الوصول (ACL) للدلائل والملفات وتعيينها وتحديثها، راجع استخدام .NET لإدارة قوائم التحكم في الوصول في Azure Data Lake Storage.

حزمة (NuGet) | عينات | مرجع API | تعيين Gen1 to Gen2 | تقديم الملاحظات

المتطلبات الأساسية

إعداد مشروعك

للبدء، قم بتثبيت حزمة Azure.Storage.Files.DataLake NuGet.

لمزيد من المعلومات حول كيفية تثبيت حزم 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 Storage للتطبيقات استخدام كل من واجهات برمجة تطبيقات Blob وواجهات برمجة تطبيقات Data Lake Storage Gen2 للعمل مع البيانات في حسابات التخزين مع تمكين مساحة الاسم الهرمية (HNS). عند العمل مع قدرات فريدة من نوعها ل Data Lake Storage Gen2، مثل عمليات الدليل و ACLs، استخدم واجهات برمجة تطبيقات Data Lake Storage Gen2، كما هو موضح في هذه المقالة.

عند اختيار واجهات برمجة التطبيقات التي يجب استخدامها في سيناريو معين، ضع في اعتبارك حمل العمل واحتياجات التطبيق الخاص بك، بالإضافة إلى المشكلات المعروفة وتأثير HNS على أحمال العمل والتطبيقات.

تخويل الوصول إلى موارد البيانات والاتصال بها

للعمل مع أمثلة التعليمات البرمجية في هذه المقالة، تحتاج إلى إنشاء مثيل DataLakeServiceClient معتمد يمثل حساب التخزين. يمكنك تخويل كائن DataLakeServiceClient باستخدام معرف Microsoft Entra أو مفتاح الوصول إلى الحساب أو توقيع وصول مشترك (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.

إنشاء حاوية

تعمل الحاوية كنظام ملفات لملفاتك. يمكنك إنشاء حاوية باستخدام الأسلوب التالي:

ينشئ مثال التعليمات البرمجية التالي حاوية ويعيد كائن DataLakeFileSystemClient للاستخدام لاحقا:

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

إنشاء دليل

يمكنك إنشاء مرجع دليل في الحاوية باستخدام الأسلوب التالي:

يضيف مثال التعليمات البرمجية التالي دليلا إلى حاوية، ثم يضيف دليلا فرعيا ويعيد كائن DataLakeDirectoryClient لاستخدامه لاحقا:

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

    return await directoryClient.CreateSubDirectoryAsync(subdirectoryName);
}

إعادة تسمية دليل أو نقله

يمكنك إعادة تسمية دليل أو نقله باستخدام الأسلوب التالي:

قم بتمرير مسار الدليل المطلوب كمعلمة. يوضح مثال التعليمات البرمجية التالي كيفية إعادة تسمية دليل فرعي:

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

تحميل ملف إلى دليل

يمكنك تحميل المحتوى إلى ملف جديد أو موجود باستخدام الأسلوب التالي:

يوضح مثال التعليمات البرمجية التالي كيفية تحميل ملف محلي إلى دليل باستخدام 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);
}

يمكنك استخدام هذا الأسلوب لإنشاء محتوى وتحميله إلى ملف جديد، أو يمكنك تعيين المعلمة overwrite للكتابة true فوق ملف موجود.

إلحاق البيانات بالملف

يمكنك تحميل البيانات ليتم إلحاقها بملف باستخدام الأسلوب التالي:

يوضح مثال التعليمات البرمجية التالي كيفية إلحاق البيانات بنهاية ملف باستخدام الخطوات التالية:

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. استخدم أي واجهة برمجة تطبيقات لمعالجة ملفات .NET لحفظ وحدات البايت من الدفق إلى ملف.

يستخدم هذا المثال قارئًا ثنائيًا و دفق الملفات لحفظ وحدات البايت في ملف.

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

إعداد قائمة محتويات الدليل

يمكنك سرد محتويات الدليل باستخدام الأسلوب التالي وتعداد النتيجة:

قد يؤدي تعداد المسارات في النتيجة إلى تقديم طلبات متعددة إلى الخدمة أثناء إحضار القيم.

يطبع مثال التعليمات البرمجية التالي أسماء كل ملف موجود في دليل:

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

}

حذف دليل

يمكنك حذف دليل باستخدام الأسلوب التالي:

يوضح مثال التعليمات البرمجية التالي كيفية حذف دليل:

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

    await directoryClient.DeleteAsync();
}

استعادة دليل محذوف مبدئيا

يمكنك استخدام مكتبات عميل Azure Storage لاستعادة دليل محذوف مبدئيا. استخدم الأسلوب التالي لسرد المسارات المحذوفة لمثيل DataLakeFileSystemClient :

استخدم الأسلوب التالي لاستعادة دليل محذوف مبدئيا:

يوضح مثال التعليمات البرمجية التالي كيفية سرد المسارات المحذوفة واستعادة دليل محذوف مبدئيا:

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

لمعرفة المزيد حول إنشاء توقيعات الوصول المشترك لتفويض المستخدم، راجع إنشاء توقيعات الوصول المشترك لتفويض مستخدم باستخدام .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.

(راجع أيضًا )