استخدام Python لإدارة قوائم التحكم بالوصول في Azure Data Lake Storage

تُبين هذه المقالة كيفية استخدام Python للحصول على قوائم التحكم في الوصول للأدلة والملفات وضبطها وتحديثها.

يتوفر توريث قائمة التحكم بالوصول بالفعل للعناصر التابعة الجديدة التي تم إنشاؤها ضمن الدليل الأصل. ولكن يمكنك أيضًا إضافة قوائم التحكم في الوصول وتحديثها وإزالتها بشكل متكرر على العناصر التابعة الموجودة في دليل أصل دون الحاجة إلى إجراء هذه التغييرات بشكل فردي لكل عنصر تابع.

الحزمة (فهرس حزمة Python) | عينات | عينات ACL متكررة | مرجع API | Gen1 إلى Gen2 تعيين | تقديم ملاحظات

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

• اشتراك في Azure - أنشئ اشتراكا مجانًا.
• حساب تخزين Azure الذي تم تمكين مساحة الاسم الهرمية (HNS). اتبع هذه الإرشادات لإنشاء واحدة.
• Python 3.8+
• إصدار Azure CLI 2.6.0 أو أعلى.
• أحد أذونات الأمان التالية:
  • أساس أمان معرف Microsoft Entra تم توفيره تم تعيينه لدور "مالك بيانات كائن ثنائي كبير الحجم للتخزين"، تم تحديد نطاقه للحاوية الهدف أو حساب التخزين أو مجموعة الموارد الأصل أو الاشتراك.
  • امتلاك مستخدم للحاوية أو الدليل المستهدف الذي تخطط لتطبيق إعدادات قائمة التحكم بالوصول عليه. لتعيين ACLs بشكل متكرر، يشمل ذلك جميع العناصر الفرعية في الحاوية أو الدليل الهدف.
  • مفتاح حساب التخزين.

إعداد مشروعك

يرشدك هذا القسم خلال إعداد مشروع للعمل مع مكتبة عميل Azure Data Lake Storage ل Python.

من دليل المشروع الخاص بك، قم بتثبيت الحزم لمكتبات عميل Azure Data Lake Storage وAzure Identity باستخدام pip install الأمر . حزمة azure-identity مطلوبة للاتصالات بدون كلمة مرور بخدمات Azure.

pip install azure-storage-file-datalake azure-identity

ثم افتح ملف التعليمات البرمجية وأضف عبارات الاستيراد الضرورية. في هذا المثال، نضيف ما يلي إلى ملف .py :

from azure.identity import DefaultAzureCredential
from azure.storage.filedatalake import DataLakeServiceClient

الاتصال بالحساب

لتشغيل أمثلة التعليمات البرمجية في هذه المقالة، تحتاج إلى إنشاء مثيل DataLakeServiceClient الذي يمثل حساب التخزين. يمكنك تخويل كائن العميل باستخدام بيانات اعتماد معرف Microsoft Entra أو باستخدام مفتاح حساب.

معرف Microsoft Entra (مستحسن)

يمكنك استخدام مكتبة عميل هوية Azure ل Python لمصادقة التطبيق الخاص بك باستخدام معرف Microsoft Entra.

إشعار

إذا كنت تستخدم معرف Microsoft Entra لتخويل الوصول، فتأكد من تعيين دور مالك بيانات Storage Blob لكيان الأمان الخاص بك. لمعرفة المزيد حول كيفية تطبيق أذونات ACL وتأثيرات تغييرها، راجع نموذج التحكم في الوصول في Azure Data Lake Storage.

أولا، قم بتعيين أحد أدوار التحكم في الوصول المستندة إلى دور Azure (Azure RBAC) التالية إلى أساس الأمان الخاص بك:

الدور	إمكانية إعداد قائمة التحكم بالوصول
مالك بيانات للبيانات الثنائية الكبيرة للتخزين	جميع الدلائل والملفات في الحساب.
المساهم في بيانات مخزن البيانات الثنائية الكبيرة	فقط الدلائل والملفات التي يملكها الأمان الأساسي.

بعد ذلك، قم بإنشاء مثيل DataLakeServiceClient وتمرير مثيل جديد من فئة DefaultAzureCredential .

def get_service_client_token_credential(self, account_name) -> DataLakeServiceClient:
    account_url = f"https://{account_name}.dfs.core.windows.net"
    token_credential = DefaultAzureCredential()

    service_client = DataLakeServiceClient(account_url, credential=token_credential)

    return service_client

لمعرفة المزيد حول استخدام DefaultAzureCredential لتخويل الوصول إلى البيانات، راجع نظرة عامة: مصادقة تطبيقات Python إلى Azure باستخدام Azure SDK.

مفتاح الحساب

يمكنك تخويل الوصول إلى البيانات باستخدام مفاتيح الوصول إلى حسابك (المفتاح المشترك). ينشئ هذا المثال مثيل DataLakeServiceClient المخول بمفتاح الحساب.

def get_service_client_account_key(self, account_name, account_key) -> DataLakeServiceClient:
    account_url = f"https://{account_name}.dfs.core.windows.net"
    service_client = DataLakeServiceClient(account_url, credential=account_key)

    return service_client

تنبيه

لا يوصى بالتخويل باستخدام المفتاح المشترك لأنه قد يكون أقل أمانا. للحصول على الأمان الأمثل، قم بتعطيل التخويل عبر المفتاح المشترك لحساب التخزين الخاص بك، كما هو موضح في منع تخويل المفتاح المشترك لحساب Azure Storage.

يجب أن يقتصر استخدام مفاتيح الوصول سلسلة الاتصال على الإثبات الأولي لتطبيقات المفاهيم أو النماذج الأولية للتطوير التي لا تصل إلى الإنتاج أو البيانات الحساسة. وإلا، يجب دائما تفضيل فئات المصادقة المستندة إلى الرمز المميز المتوفرة في Azure SDK عند المصادقة على موارد Azure.

توصي Microsoft بأن يستخدم العملاء إما معرف Microsoft Entra أو توقيع وصول مشترك (SAS) لتخويل الوصول إلى البيانات في Azure Storage. لمزيد من المعلومات، راجع تخويل العمليات للوصول إلى البيانات.

تعيين قوائم التحكم في الوصول

عند تعيين ACL، يمكنك استبدال قائمة التحكم بالوصول بأكملها بما في ذلك جميع إدخالاتها. إذا كنت ترغب في تغيير مستوى الإذن الخاص بمدير الأمان أو إضافة مدير أمان جديد إلى قائمة تحكم بالوصول دون التأثير على الإدخالات الموجودة الأخرى، فيجب عليك تحديث قائمة التحكم بالوصول بدلاً من ذلك. لتحديث قائمة التحكم بالوصول بدلاً من استبدالها، راجع قسم تحديث قوائم التحكم بالوصول من هذه المقالة.

يوضح لك هذا القسم كيفية:

• تعيين قائمة التحكم بالوصول (ACL) لدليل
• تعيين قائمة التحكم بالوصول (ACL) لملف

تعيين قائمة التحكم بالوصول (ACL) لدليل

احصل على قائمة التحكم في الوصول (ACL) الخاصة بالدليل عن طريق الاتصال بطريقة DataLakeDirectoryClient.get_access_control وتعيين قائمة التحكم بالوصول عن طريق الاتصال بطريقة DataLakeDirectoryClient.set_access_control .

يحصل هذا المثال على قائمة التحكم بالوصول لدليل يُسمى my-directory. تمنح السلسلة rwxr-xrw- المستخدم المالك أذونات القراءة والكتابة والتنفيذ، وتمنح المجموعة المالكة أذونات القراءة والتنفيذ فقط، وتمنح الآخرين كلهم أذونات القراءة والكتابة.

def manage_directory_permissions():
    try:
        file_system_client = service_client.get_file_system_client(file_system="my-file-system")

        directory_client = file_system_client.get_directory_client("my-directory")
        
        acl_props = directory_client.get_access_control()
        
        print(acl_props['permissions'])
        
        new_dir_permissions = "rwxr-xrw-"
        
        directory_client.set_access_control(permissions=new_dir_permissions)
        
        acl_props = directory_client.get_access_control()
        
        print(acl_props['permissions'])
    
    except Exception as e:
     print(e)

يمكنك أيضًا الحصول على ACL الخاص بالدليل الجذري للحاوية وتعيينه. للحصول على الدليل الجذري، اتصل بالطريقة FileSystemClient._get_root_directory_client.

تعيين قائمة التحكم بالوصول (ACL) لملف

احصل على قائمة التحكم في الوصول (ACL) للملف عن طريق الاتصال بطريقة DataLakeFileClient.get_access_control وتعيين ACL عن طريق الاتصال بطريقة DataLakeFileClient.set_access_control .

يحصل هذا المثال على قائمة التحكم في الوصول لملف يُسمى my-file.txt. تمنح السلسلة rwxr-xrw- المستخدم المالك أذونات القراءة والكتابة والتنفيذ، وتمنح المجموعة المالكة أذونات القراءة والتنفيذ فقط، وتمنح الآخرين كلهم أذونات القراءة والكتابة.

def manage_file_permissions():
    try:
        file_system_client = service_client.get_file_system_client(file_system="my-file-system")

        directory_client = file_system_client.get_directory_client("my-directory")
        
        file_client = directory_client.get_file_client("uploaded-file.txt")

        acl_props = file_client.get_access_control()
        
        print(acl_props['permissions'])
        
        new_file_permissions = "rwxr-xrw-"
        
        file_client.set_access_control(permissions=new_file_permissions)
        
        acl_props = file_client.get_access_control()
        
        print(acl_props['permissions'])

    except Exception as e:
     print(e)

تعيين قوائم التحكم في الوصول بشكل متكرر

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

عيِن قوائم التحكم في الوصول بشكل متكرر عن طريق استدعاء طريقة DataLakeDirectoryClient.set_access_control_recursive.

إذا كنت ترغب في تعيين إدخال افتراضي لقائمة التحكم في الوصول، فقم بإضافة السلسلة default: إلى بداية كل سلسلة إدخال لقائمة التحكم في الوصول.

يُعين هذا المثال قائمة التحكم بالوصول لدليل يُسمى my-parent-directory.

يقبل هذا الأسلوب معلمة منطقية تُسمى is_default_scope التي تحدد ما إذا كان سيتم تعيين ACL الافتراضي أم لا. إذا كانت هذه المعلمة هي True، فإن قائمة إدخالات ACL مسبوقة بالسلسلة default:. تمنح الإدخالات في هذا المثال الأذونات التالية: أذونات القراءة والكتابة والتنفيذ للمستخدم المالك، وقراءة الأذونات وتنفيذها للمجموعة المالكة، وأذونات القراءة لجميع الآخرين. يعطي إدخال ACL الأخير في هذا المثال مستخدما معينا لديه أذونات قراءة معرف xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx الكائن.

def set_permission_recursively(is_default_scope):
    
    try:
        file_system_client = service_client.get_file_system_client(file_system="my-container")

        directory_client = file_system_client.get_directory_client("my-parent-directory")

        acl = 'user::rwx,group::r-x,other::r--,user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:r--'   

        if is_default_scope:
           acl = 'default:user::rwx,default:group::r-x,default:other::r--,default:user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:r--'

        directory_client.set_access_control_recursive(acl=acl)
        
        acl_props = directory_client.get_access_control()
        
        print(acl_props['permissions'])

    except Exception as e:
     print(e)

للاطلاع على مثال يعالج قوائم التحكم في الوصول بشكل متكرر على دفعات من خلال تحديد حجم الدفعة، راجع عينة Python .

تحديث قوائم التحكم في الوصول بشكل متكرر

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

لتحديث قائمة التحكم بالوصول بشكل متكرر، أنشئ عنصر ACL جديداً باستخدام إدخال ACL الذي تريد تحديثه، ثم استخدم هذا الكائن في عملية قائمة التحكم بالوصول المحدثة. لا تحصل على ACL الموجود، ما عليك سوى توفير إدخالات ACL ليتم تحديثها. حدِث قائمة التحكم بالوصول بشكل متكرر عن طريق استدعاء الطريقة DataLakeDirectoryClient.update_access_control_recursive. إذا كنت تريد تحديث إدخال قائمة التحكم في الوصول افتراضية، فأضف السلسلة default: إلى بداية كل سلسلة إدخال قائمة التحكم في الوصول.

يقوم هذا المثال بتحديث إدخال قائمة التحكم في الوصول بإذن كتابة.

يُعين هذا المثال قائمة التحكم بالوصول لدليل يُسمى my-parent-directory. يقبل هذا الأسلوب معلمة منطقية تُسمى is_default_scope التي تحدد ما إذا كان سيتم تحديث ACL الافتراضي أم لا. إذا كان هذا الضابط True، فإن إدخال قائمة التحكم في الوصول المُحَدَثة تسبقه السلسلة default:.

def update_permission_recursively(is_default_scope):
    
    try:
        file_system_client = service_client.get_file_system_client(file_system="my-container")

        directory_client = file_system_client.get_directory_client("my-parent-directory")
              
        acl = 'user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:rwx'   

        if is_default_scope:
           acl = 'default:user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:rwx'

        directory_client.update_access_control_recursive(acl=acl)

        acl_props = directory_client.get_access_control()
        
        print(acl_props['permissions'])

    except Exception as e:
     print(e)

للاطلاع على مثال يعالج قوائم التحكم في الوصول بشكل متكرر على دفعات من خلال تحديد حجم الدفعة، راجع عينة Python .

إزالة إدخالات قائمة التحكم في الوصول بشكل متكرر

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

قم بإزالة إدخالات قائمة التحكم في الوصول عن طريق استدعاء الطريقة DataLakeDirectoryClient.remove_access_control_recursive. إذا كنت تريد إزالة إدخال قائمة التحكم في الوصول افتراضية، فقم بإضافة السلسلة default: إلى بداية سلسلة إدخال قائمة التحكم في الوصول.

يزيل هذا المثال إدخال ACL من قائمة التحكم بالوصول للدليل المسمى my-parent-directory. تقبل هذه الطريقة الضابط المنطقي المُسمى is_default_scope التي تحدد ما إذا كان سيتم إزالة الإدخال من قائمة التحكم في الوصول الافتراضية. إذا كانت هذه المعلمة هي True، فإن إدخال ACL المحدث يسبقه السلسلة default:.

def remove_permission_recursively(is_default_scope):

    try:
        file_system_client = service_client.get_file_system_client(file_system="my-container")

        directory_client = file_system_client.get_directory_client("my-parent-directory")

        acl = 'user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

        if is_default_scope:
           acl = 'default:user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

        directory_client.remove_access_control_recursive(acl=acl)

    except Exception as e:
     print(e)

للاطلاع على مثال يعالج قوائم التحكم في الوصول بشكل متكرر على دفعات من خلال تحديد حجم الدفعة، راجع عينة Python .

التعافي من حالات الفشل

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

يُرجع هذا المثال رمز المتابعة المميز في حالة حدوث فشل. يمكن للتطبيق استدعاء أسلوب المثال هذا مرة أخرى بعد معالجة الخطأ، وتمرير رمز المتابعة المميز. في حالة استدعاء أسلوب المثال هذا لأول مرة، يمكن أن يُمرر التطبيق قيمة None لمعلمة رمز المتابعة المميز.

def resume_set_acl_recursive(continuation_token):
    
    try:
        file_system_client = service_client.get_file_system_client(file_system="my-container")

        directory_client = file_system_client.get_directory_client("my-parent-directory")
              
        acl = 'user::rwx,group::rwx,other::rwx,user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:r--'

        acl_change_result = directory_client.set_access_control_recursive(acl=acl, continuation=continuation_token)

        continuation_token = acl_change_result.continuation

        return continuation_token
        
    except Exception as e:
     print(e) 
     return continuation_token

للاطلاع على مثال يعالج قوائم التحكم في الوصول بشكل متكرر على دفعات من خلال تحديد حجم الدفعة، راجع عينة Python .

إذا كنت تريد أن تكتمل العملية دون انقطاع بسبب أخطاء الأذونات، فيمكنك تحديد ذلك.

لضمان اكتمال العملية دون انقطاع، لا تمرر رمزا مميزا للاستمرار في طريقة DataLakeDirectoryClient.set_access_control_recursive.

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

def continue_on_failure():
    
    try:
        file_system_client = service_client.get_file_system_client(file_system="my-container")

        directory_client = file_system_client.get_directory_client("my-parent-directory")
              
        acl = 'user::rwx,group::rwx,other::rwx,user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:r--'

        acl_change_result = directory_client.set_access_control_recursive(acl=acl)

        print("Summary: {} directories and {} files were updated successfully, {} failures were counted."
          .format(acl_change_result.counters.directories_successful, acl_change_result.counters.files_successful,
                  acl_change_result.counters.failure_count))
        
    except Exception as e:
     print(e)

للاطلاع على مثال يعالج قوائم التحكم في الوصول بشكل متكرر على دفعات من خلال تحديد حجم الدفعة، راجع عينة Python .

أفضل الممارسات

يوفر لك هذا القسم بعض إرشادات أفضل الممارسات لإعداد قوائم التحكم بالوصول بشكل متكرر.

التعامل مع أخطاء وقت التشغيل

يمكن أن يحدث خطأ في وقت التشغيل لأسباب عديدة (على سبيل المثال: انقطاع أو مشكلة في اتصال العميل). إذا واجهت خطأ وقت التشغيل، فأعد تشغيل عملية قائمة التحكم بالوصول المتكررة. يمكن إعادة تطبيق قوائم التحكم بالوصول على العناصر دون التسبب في تأثير سلبي.

معالجة أخطاء الأذونات (403)

إذا واجهت استثناءً للتحكم في الوصول أثناء تشغيل عملية ACL متكررة، فقد لا يكون لدى AD خاصتك إذنًا كافيًا لتطبيق ACL على واحد أو أكثر من العناصر التابعة في التسلسل الهرمي للدليل. عند حدوث خطأ في الإذن، تتوقف العملية ويتم توفير رمز مميز للمتابعة. عالج مشكلة الأذونات، ثم استخدم رمز المتابعة المميز لمعالجة مجموعة البيانات المتبقية. لن تُعالج الدلائل والملفات التي تمت معالجتها بنجاح بالفعل مرة أخرى. يمكنك أيضاً اختيار إعادة تشغيل عملية قائمة التحكم بالوصول المتكررة. يمكن إعادة تطبيق قوائم التحكم بالوصول على العناصر دون التسبب في تأثير سلبي.

بيانات الاعتماد

نوصي بتوفير أساس أمان Microsoft Entra الذي تم تعيينه لدور Storage Blob Data Owner في نطاق حساب التخزين الهدف أو الحاوية.

الأداء

لتقليل زمن الانتقال، نوصي بتشغيل عملية ACL المتكررة في جهاز Azure Virtual Machine (VM) الموجود في نفس منطقة حساب التخزين خاصتك.

حدود ACL

الحد الأقصى لعدد قوائم التحكم في الوصول التي يمكنك تطبيقها على دليل أو ملف هو 32 قائمة تحكم بالوصول و32 قائمة تحكم بالوصول افتراضية. لمزيد من المعلومات، راجع التحكم في الوصول في Azure Data Lake Storage Gen2.

(راجع أيضًا )

• وثائق مرجع API
• الحزمة (Python Package Index)
• العينات
• تعيين Gen1 إلى Gen2
• المشاكل المعروفة
• تقديم ملاحظات
• نموذج التحكم في الوصول في Azure Data Lake Storage
• قوائم التحكم بالوصول (ACLs) في Azure Data Lake Storage