مشاركة عبر

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

  • مقالة

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

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

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

إعداد بيئتك

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

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

تثبيت الحزم

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

pip install azure-storage-blob azure-identity

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

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

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient

التصريح

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

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

لتوصيل تطبيق ب Blob Storage، قم بإنشاء مثيل 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 Storage. يمكنك تحديد عدد النتائج المراد إرجاعها في كل مجموعة من النتائج، ثم استرداد المجموعات اللاحقة. يمكنك أيضا تصفية النتائج حسب بادئة، وإرجاع بيانات تعريف الحاوية مع النتائج. يتم وصف هذه الخيارات في الأقسام التالية.

لسرد الحاويات في حساب تخزين، قم باستدعاء الطريقة التالية:

يقوم هذا الأسلوب بإرجاع قابل للتكبير من النوع ContainerProperties. يتم ترتيب الحاويات معجميا بالاسم.

إدارة عدد النتائج التي يتم إرجاعها

بشكل افتراضي، تعرض عملية السرد ما يصل إلى 5000 نتيجة في المرة الواحدة. لإرجاع مجموعة أصغر من النتائج، قم بتوفير قيمة غير صفرية لوسيطة results_per_page الكلمة الأساسية.

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

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

تضمين بيانات تعريف الحاوية

لتضمين بيانات تعريف الحاوية مع النتائج، قم بتعيين وسيطة include_metadata الكلمة الأساسية إلى True. يتضمن Azure Storage بيانات التعريف مع كل حاوية يتم إرجاعها، لذلك لا تحتاج إلى إحضار بيانات تعريف الحاوية بشكل منفصل.

تضمين الحاويات المحذوفة

لتضمين حاويات محذوفة مبدئيا مع النتائج، قم بتعيين وسيطة include_deleted الكلمة الأساسية إلى True.

أمثلة على التعليمات البرمجية

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

def list_containers(self, blob_service_client: BlobServiceClient):
    containers = blob_service_client.list_containers(include_metadata=True)
    for container in containers:
        print(container['name'], container['metadata'])

يسرد المثال التالي الحاويات التي تبدأ ببادئة محددة في المعلمة name_starts_with فقط:

def list_containers_prefix(self, blob_service_client: BlobServiceClient):
    containers = blob_service_client.list_containers(name_starts_with='test-')
    for container in containers:
        print(container['name'])

يمكنك أيضا تحديد حد لعدد النتائج لكل صفحة. يمرر results_per_page هذا المثال النتائج ويقسمها إلى صفحات:

def list_containers_pages(self, blob_service_client: BlobServiceClient):
    i=0
    all_pages = blob_service_client.list_containers(results_per_page=5).by_page()
    for container_page in all_pages:
        i += 1
        print(f"Page {i}")
        for container in container_page:
            print(container['name'])

سرد الحاويات بشكل غير متزامن

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

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

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

    import asyncio

from azure.identity.aio import DefaultAzureCredential
from azure.storage.blob.aio import BlobServiceClient

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

    async def main():
    sample = ContainerSamples()

    # 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_containers(blob_service_client)

if __name__ == '__main__':
    asyncio.run(main())

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

    async def list_containers(self, blob_service_client: BlobServiceClient):
    async for container in blob_service_client.list_containers(include_metadata=True):
        print(container['name'], container['metadata'])

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

الموارد

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

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

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

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

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

(راجع أيضًا )

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

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