استخدم Python لإدارة ACLs في Azure Data Lake Storage Gen2

مقالة
05/16/2022
قراءة خلال 10 دقائق

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

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

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

اشتراك Azure. لمزيد من المعلومات، راجع الحصول على نسخة تجريبية مجانية من Azure.
حساب تخزين يحتوي على مساحة أسماء هرمية (HNS) مُمَكَنة. اتبع هذه التعليمات لإنشاء واحدة.
إصدار واجهة سطر الأوامر Azure 2.6.0 أو أعلى.
أحد أذونات الأمان التالية:
- مدير أمان Azure Active Directory (AD) تم توفيره وتم تعيينه دور مالك بيانات كائن ثنائي كبير الحجم التخزين في نطاق الحاوية الهدف أو مجموعة الموارد الأصلية أوالاشتراك.
- امتلاك مستخدم للحاوية أو الدليل المستهدف الذي تخطط لتطبيق إعدادات قائمة التحكم بالوصول عليه. لتعيين ACLs بشكل متكرر، يشمل ذلك جميع العناصر التابعة في الحاوية أو الدليل الهدف.
- مفتاح حساب التخزين.

إعداد مشروعك

ثبِت مكتبة عميل Azure Data Lake Storage لـ Python باستخدام PIP.

pip install azure-storage-file-datalake

أضف بيانات الاستيراد هذه إلى أعلى ملف التعليمات البرمجية خاصتك.

import os, uuid, sys
from azure.storage.filedatalake import DataLakeServiceClient
from azure.core._match_conditions import MatchConditions
from azure.storage.filedatalake._models import ContentSettings

اتصل بالحساب

لاستخدام المقتطفات الموجودة في هذه المقالة، ستحتاج إلى إنشاء مثيل DataLakeServiceClient يُمثل حساب التخزين.

الاتصال باستخدام Azure Active Directory (AD)

ملاحظة

إذا كنت تستخدم Azure Active Directory (Azure AD) للسماح بالوصول، فتأكد من تعيين دور مالك بيانات كائن ثنائي كبير الحجم للتخزين لمدير الأمان. لمعرفة المزيد حول كيفية تطبيق أذونات قائمة التحكم بالوصول وتأثيرات تغييرها، راجع نموذج التحكم في الوصول في Azure Data Lake Storage Gen2 .

يمكنك استخدام مكتبة عميل هوية Azure لـ Python لمصادقة التطبيق خاصتك مع Azure AD.

احصل على ID عميل وسر عميل وID مستأجر. للقيام بذلك، راجع الحصول على رمز من Azure AD للتصريح بالطلبات من تطبيق العميل . كجزء من هذه العملية، سيتعين عليك تعيين أحد الأدوار التالية للتحكم في الوصول القائم على الأدوار (Azure RBAC) إلى مدير الأمن خاصتك.

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

ينشئ هذا المثال مثال DataLakeServiceClient باستخدام ID العميل وسر العميل و ID المستأجر.

def initialize_storage_account_ad(storage_account_name, client_id, client_secret, tenant_id):
    
    try:  
        global service_client

        credential = ClientSecretCredential(tenant_id, client_id, client_secret)

        service_client = DataLakeServiceClient(account_url="{}://{}.dfs.core.windows.net".format(
            "https", storage_account_name), credential=credential)
    
    except Exception as e:
        print(e)

ملاحظة

لمزيد من الأمثلة، راجع مكتبة عميل هوية Azure للحصول على وثائق Python.

الاتصال باستخدام مفتاح حساب

هذه هي أسهل طريقة للاتصال بحساب.

ينشئ هذا المثال مثيل DataLakeServiceClient باستخدام مفتاح حساب.

def initialize_storage_account(storage_account_name, storage_account_key):
    
    try:  
        global service_client

        service_client = DataLakeServiceClient(account_url="{}://{}.dfs.core.windows.net".format(
            "https", storage_account_name), credential=storage_account_key)
    
    except Exception as e:
        print(e)

استبدل قيمة العنصر النائب storage_account_name باسم حساب التخزين الخاص بك.
استبدل storage_account_key قيمة العنصر النائب باسم حساب التخزين خاصتك.

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

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

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

تعيين قائمة التحكم بالوصول (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)

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

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

احصل على قائمة التحكم في الوصول (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)

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

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

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

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

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

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

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::rwx,other::rwx,user:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:r--'   

        if is_default_scope:
           acl = 'default:user::rwx,default:group::rwx,default:other::rwx,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 .

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

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

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

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

يحدد هذا المثال قائمة التحكم بالوصول لدليل يُسمى my-parent-directory. تقبل هذه الطريقة الضابط المنطقي المسمى is_default_scope التي تحدد ما إذا كان سيتم تحديث قائمة التحكم في الوصول الافتراضية. إذا كان هذا الضابط 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: إلى بداية سلسلة إدخال قائمة التحكم في الوصول.

يزيل هذا المثال إدخال قائمة التحكم في الوصول من قائمة التحكم بالوصول للدليل المسمى my-parent-directory. تقبل هذه الطريقة الضابط المنطقي المُسمى is_default_scope التي تحدد ما إذا كان سيتم إزالة الإدخال من قائمة التحكم في الوصول الافتراضية. إذا كان هذا الضابط True، فإن إدخال قائمة التحكم في الوصول المُحَدَثة تسبقه السلسلة 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 على واحد أو أكثر من العناصر التابعة في التسلسل الهرمي للدليل. عند حدوث خطأ في الإذن، تتوقف العملية ويتم توفير رمز متابعة. أصلِح مشكلة الإذن، ثم استخدم رمز الاستمرار لمعالجة مجموعة البيانات المتبقية. لن يكون من الضروري معالجة الأدلة والملفات التي تمت معالجتها بنجاح مرة أخرى. يمكنك أيضًا اختيار إعادة تشغيل عملية قائمة التحكم في الوصول المتكررة. يمكن إعادة تطبيق قوائم التحكم في الوصول على العناصر دون التسبب في تأثير سلبي.

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

نوصيك بتوفير مدير أمان Azure AD الذي تم تعيين دور مالك بيانات التخزين في نطاق حساب التخزين المستهدف أو الحاوية.

الأداء

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

حدود قائمة التحكم في الوصول

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

استخدم Python لإدارة ACLs في Azure Data Lake Storage Gen2

هل هذه الصفحة مفيدة؟

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

إعداد مشروعك

اتصل بالحساب

الاتصال باستخدام Azure Active Directory (AD)

الاتصال باستخدام مفتاح حساب

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

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

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

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

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

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

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

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

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

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

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

الأداء

حدود قائمة التحكم في الوصول

راجع أيضًا