سرد الكائنات الثنائية كبيرة الحجم باستخدام Python

• NET.
• Java
• JavaScript
• Python
• ذهب

توضح هذه المقالة كيفية سرد الكتل باستخدام مكتبة عملاء تخزين Azure للعبة Python.

للتعرف على كيفية إدراج الكتل باستخدام واجهات برمجة التطبيقات غير المتزامنة، راجع قائمة الكتل بشكل غير متزامن.

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

• اشتراك Azure - إنشاء اشتراك مجاني
• حساب تخزين Azure - إنشاء حساب تخزين
• بايثون 3.8+

إعداد بيئتك

إذا لم يكن لديك مشروع موجود، يوضح لك هذا القسم كيفية إعداد مشروع للعمل مع مكتبة عميل مساحة تخزين Azure Blob ل Python. لمزيد من التفاصيل، راجع بدء استخدام مساحة تخزين Azure Blob وPython.

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

تثبيت الحزم

قم بتثبيت الحزم التالية باستخدام pip install:

pip install azure-storage-blob azure-identity

إضافة عبارات الاستيراد

أضف عبارات import التالية:

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, ContainerClient, BlobPrefix

التصريح

يجب أن يكون لآلية التخويل الأذونات اللازمة لسرد كائن ثنائي كبير الحجم. للحصول على تفويض باستخدام Microsoft Entra ID (موصى به)، تحتاج إلى Azure RBAC المدمج Storage Blob Data Reader أو أعلى. لمعرفة المزيد، راجع إرشادات التخويل ل List Blobs (REST API).

إنشاء كائن عميل

لتوصيل تطبيق ب مخزن البيانات الثنائية الكبيرة، قم بإنشاء مثيل BlobServiceClient. يوضح المثال التالي كيفية إنشاء كائن عميل باستخدام DefaultAzureCredential للتخويل:

# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.windows.net"
credential = DefaultAzureCredential()

# Create the BlobServiceClient object
blob_service_client = BlobServiceClient(account_url, credential=credential)

يمكنك أيضا إنشاء كائنات العميل لحاويات أو كائنات ثنائية كبيرة الحجم معينة، إما مباشرة أو من BlobServiceClient العنصر. لمعرفة المزيد حول إنشاء كائنات العميل وإدارتها، راجع إنشاء كائنات العميل التي تتفاعل مع موارد البيانات وإدارتها.

حول خيارات إدخال قائمة الكائنات الثنائية كبيرة الحجم

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

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

• ContainerClient.list_blobs (مع الاسم، يتضمن اختياريا بيانات وصفية، وعلامات، ومعلومات أخرى مرتبطة بكل كتلة)
• ContainerClient.list_blob_names (إرجاع اسم الكائن الثنائي كبير الحجم فقط)

لسرد الكتل في حاوية باستخدام قائمة هرمية، اتصل بالطريقة التالية:

• ContainerClient.walk_blobs (مع الاسم، يتضمن اختياريا بيانات وصفية، وعلامات، ومعلومات أخرى مرتبطة بكل كتلة)

تصفية النتائج باستخدام البادئة

لتصفية قائمة الكائنات الثنائية كبيرة الحجم، حدد سلسلة وسيطة name_starts_with الكلمة الأساسية. يمكن أن تتضمن سلسلة البادئة حرفاً واحداً أو أكثر. تخزين Azure يعيد فقط الكتل التي تبدأ أسماؤها بتلك البادئة.

مقارنة بين القائمة المسطحة والقائمة الهرمية

يتم تنظيم الكائنات الثنائية كبيرة الحجم في تخزين Azure في نموذج كامل وليس نموذج هرمي (مثل نظام الملفات الكلاسيكي). ومع ذلك، يمكنك تنظيم الكتل في أدلة افتراضية لمحاكاة هيكل المجلدات. يشكل الدليل الظاهري جزءاً من اسم الكائنات الثنائية كبيرة الحجم ويشار إليه بالحرف المحدد.

لتنظيم الكائنات الثنائية كبيرة الحجم في أدلة ظاهرية، استخدم حرف محدد في اسم الكائنات الثنائية كبيرة الحجم. يعد الحرف المحدد الافتراضي هو شرطة مائلة للأمام (/)، ولكن يمكنك تحديد أي حرف كمحدد.

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

استخدام سرد البيانات المسطح

بشكل افتراضي، تقوم عملية الإدراج بإرجاع الكائنات الثنائية كبيرة الحجم في إدراج بيانات قائمة كاملة. في قائمة مسطحة، لا يتم تنظيم الكائنات الثنائية كبيرة الحجم بواسطة الدليل الظاهري.

المثال التالي يسرد الكتل في الحاوية المحددة باستخدام قائمة مسطحة:

def list_blobs_flat(self, blob_service_client: BlobServiceClient, container_name):
    container_client = blob_service_client.get_container_client(container=container_name)

    blob_list = container_client.list_blobs()

    for blob in blob_list:
        print(f"Name: {blob.name}")

عينة الإخراج مشابهة ل:

List blobs flat:
Name: file4.txt
Name: folderA/file1.txt
Name: folderA/file2.txt
Name: folderA/folderB/file3.txt

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

def list_blobs_flat_options(self, blob_service_client: BlobServiceClient, container_name):
    container_client = blob_service_client.get_container_client(container=container_name)

    blob_list = container_client.list_blobs(include=['tags'])

    for blob in blob_list:
        print(f"Name: {blob['name']}, Tags: {blob['tags']}")

عينة الإخراج مشابهة ل:

List blobs flat:
Name: file4.txt, Tags: None
Name: folderA/file1.txt, Tags: None
Name: folderA/file2.txt, Tags: None
Name: folderA/folderB/file3.txt, Tags: {'tag1': 'value1', 'tag2': 'value2'}

إشعار

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

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

استخدام إدراج القائمة الهرمية

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

لسرد الكائنات الثنائية كبيرة الحجم هرميا، استخدم الأسلوب التالي:

• ContainerClient.walk_blobs

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

depth = 0
indent = "  "
def list_blobs_hierarchical(self, container_client: ContainerClient, prefix):
    for blob in container_client.walk_blobs(name_starts_with=prefix, delimiter='/'):
        if isinstance(blob, BlobPrefix):
            # Indentation is only added to show nesting in the output
            print(f"{self.indent * self.depth}{blob.name}")
            self.depth += 1
            self.list_blobs_hierarchical(container_client, prefix=blob.name)
            self.depth -= 1
        else:
            print(f"{self.indent * self.depth}{blob.name}")

عينة الإخراج مشابهة ل:

folderA/
  folderA/folderB/
    folderA/folderB/file3.txt
  folderA/file1.txt
  folderA/file2.txt
file4.txt

إشعار

لا يمكن إدراج لقطات الكتلة في عملية إدراج هرمية.

سرد الكائنات الثنائية كبيرة الحجم بشكل غير متزامن

تدعم مكتبة عميل مساحة تخزين Azure Blob ل Python سرد الكائنات الثنائية كبيرة الحجم بشكل غير متزامن. لمعرفة المزيد حول متطلبات إعداد المشروع، راجع البرمجة غير المتزامنة.

اتبع هذه الخطوات لسرد الكتل باستخدام واجهات برمجة التطبيقات غير المتزامنة:

1. إضافة عبارات الاستيراد التالية:

   import asyncio
   
   from azure.identity.aio import DefaultAzureCredential
   from azure.storage.blob.aio import BlobServiceClient, ContainerClient, BlobPrefix
   

2. أضف كودا لتشغيل البرنامج باستخدام asyncio.run. تقوم هذه الدالة بتشغيل الروتين المتكرر (coroutine) main() في هذا المثال، وتدير حلقة asyncio الحدث. يتم إعلان الكوروتينات باستخدام صياغة غير متزامن/انتظار. في هذا المثال، يقوم الروتين main() التكراري أولا بإنشاء المستوى BlobServiceClient الأعلى باستخدام async with، ثم يستدعي الطريقة التي تسرد الكتل. يحتاج عميل المستوى الأعلى فقط إلى استخدام async with، حيث يشارك العملاء الآخرون الذين تم إنشاؤهم منه نفس تجمع الاتصال.

   async def main():
       sample = BlobSamples()
   
       # TODO: Replace <storage-account-name> with your actual storage account name
       account_url = "https://<storage-account-name>.blob.core.windows.net"
       credential = DefaultAzureCredential()
   
       async with BlobServiceClient(account_url, credential=credential) as blob_service_client:
           await sample.list_blobs_flat(blob_service_client, "sample-container")
   
   if __name__ == '__main__':
       asyncio.run(main())
   

3. إضافة تعليمة برمجية لسرد الكائنات الثنائية كبيرة الحجم. مثال الكود التالي يسرد الكتل باستخدام قائمة مسطحة. الكود هو نفسه المثال المتزامن، باستثناء أن الطريقة تعلن باستخدام async الكلمة المفتاحية وتستخدم async for عند استدعاء الطريقة list_blobs .

   async def list_blobs_flat(self, blob_service_client: BlobServiceClient, container_name):
       container_client = blob_service_client.get_container_client(container=container_name)
   
       async for blob in container_client.list_blobs():
           print(f"Name: {blob.name}")
   

مع وجود هذا الإعداد الأساسي، يمكنك تنفيذ أمثلة أخرى في هذا المقال كروتينات متزامنة باستخدام بناء الجملة غير المتزامن/الانتظار.

قائمة الكتل بصيغة Apache Arrow (معاينة)

مهم

قائمة الكتل بصيغة Apache Arrow موجودة حاليا في المعاينة. يتطلب هذا السيناريو نسخة تجريبية (معاينة) من مكتبة عميل مساحة تخزين Azure Blob للعبة Python (على سبيل المثال، azure-storage-blob إصدار المعاينة 12.31.0b1 أو إصدارات أحدث). يتم توفير ميزات المعاينة دون اتفاقية على مستوى الخدمة ولا ينصح بها لأعباء العمل الإنتاجية. قد لا تكون بعض الميزات مدعومة، أو قد تكون ذات قدرات محدودة. لمزيد من المعلومات، راجع شروط الاستخدام الإضافية لمعاينات Microsoft Azure.

هذه القدرة مبنية على واجهة برمجة التطبيقات الحالية List Blobs . بدلا من استخدام XML الافتراضي، يستخدم تنسيق Apache Arrow المدمج والعمودي كصيغة استجابة على السلك. تقوم بتفعيله عن طريق تعيين خيار واحد في استدعاء قائمة الحاويات. يقوم Python SDK بفك تشفير Apache Arrow خلف الكواليس ولا يزال يعيد نفس BlobProperties الكائنات. هذا النهج يحسن معدل نقل الإدراج ويقلل من وحدة المعالجة المركزية على جانب العميل عند تعداد الحاويات الكبيرة. يحافظ على عقد الاستجابة الذي تعتمد عليه التطبيقات.

Warning

إدراج الكتل بصيغة Apache Arrow غير مدعوم في حسابات التخزين التي تحتوي على مساحة أسماء هرمية (Azure Data Lake Storage).

لطلب نتائج منسقة ب Apache Arrow، اضبط وسيط response_format الكلمة المفتاحية عند "arrow" استدعاء ContainerClient.list_blobs أو ContainerClient.list_blob_names. عند استخدام مخرجات Apache Arrow، يمكنك أيضا ضبط start_fromend_before وسيط الكلمات المفتاحية للتحكم في نطاق المسارات المرتجعة.

إشعار

الاستخدام response_format="arrow" يتطلب تركيب حزمة النانوآرو .

المثال التالي يسرد الكتل في حاوية ويطلب النتائج بصيغة Apache Arrow:

# response_format="arrow" requires the nanoarrow package to be installed
blob_list = container_client.list_blobs(
    name_starts_with="folderA/",
    response_format="arrow",
)

for blob in blob_list:
    print("Name: " + blob.name)

الموارد

لمعرفة المزيد حول كيفية إدراج الكتل باستخدام مكتبة عملاء مساحة تخزين Azure Blob للعبة Python، راجع الموارد التالية.

نماذج التعليمات البرمجية

• عرض عينات الشيفرة المتزامنة أو غير المتزامنة من هذا المقال (GitHub).

عمليات واجهة برمجة تطبيقات REST

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

• قائمة الكائنات الثنائية كبيرة الحجم (REST API)

موارد مكتبة العميل

• الوثائق المرجعية لمكتبة العميل
• التعليمات البرمجية لمصدر مكتبة عميل
• حزمة (PyPi)

(راجع أيضًا )

• تعداد موارد الكائنات الثنائية كبيرة الحجم
• تعيين إصدار الكائن الثنائي كبير الحجم

المحتوى ذو الصلة

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