مشاركة عبر

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

  • مقالة

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

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

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

إعداد بيئتك

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

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

تثبيت الحزم

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

pip install azure-storage-blob azure-identity

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

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

import io
import os
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, BlobClient

التصريح

يجب أن يكون لآلية التخويل الأذونات اللازمة لتنفيذ عملية التنزيل. للحصول على تخويل باستخدام معرف Microsoft Entra (مستحسن)، تحتاج إلى دور Azure RBAC المضمن Storage Blob Data Reader أو أعلى. لمعرفة المزيد، راجع إرشادات التخويل للحصول على Blob (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 العنصر. لمعرفة المزيد حول إنشاء كائنات العميل وإدارتها، راجع إنشاء كائنات العميل التي تتفاعل مع موارد البيانات وإدارتها.

تنزيل كائن ثنائي كبير الحجم

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

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

تنزيل إلى مسار ملف

يقوم المثال التالي بتنزيل كائن ثنائي كبير الحجم إلى مسار ملف:

def download_blob_to_file(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
    with open(file=os.path.join(r'filepath', 'filename'), mode="wb") as sample_blob:
        download_stream = blob_client.download_blob()
        sample_blob.write(download_stream.readall())

تنزيل إلى دفق

يقوم المثال التالي بتنزيل كائن ثنائي كبير الحجم إلى دفق. في هذا المثال، يقوم StorageStreamDownloader.read_into بتنزيل محتويات الكائن الثنائي كبير الحجم إلى دفق وإرجاع عدد وحدات البايت المقروءة:

def download_blob_to_stream(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # readinto() downloads the blob contents to a stream and returns the number of bytes read
    stream = io.BytesIO()
    num_bytes = blob_client.download_blob().readinto(stream)
    print(f"Number of bytes: {num_bytes}")

تنزيل كائن ثنائي كبير الحجم في مجموعات

يقوم المثال التالي بتنزيل كائن ثنائي كبير الحجم ويكرر عبر المجموعات في دفق التنزيل. في هذا المثال، تقوم StorageStreamDownloader.chunks بإرجاع مكرر، والذي يسمح لك بقراءة محتوى الكائن الثنائي كبير الحجم في مجموعات:

def download_blob_chunks(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # This returns a StorageStreamDownloader
    stream = blob_client.download_blob()
    chunk_list = []

    # Read data in chunks to avoid loading all into memory at once
    for chunk in stream.chunks():
        # Process your data (anything can be done here - 'chunk' is a byte array)
        chunk_list.append(chunk)

تنزيل إلى سلسلة

يقوم المثال التالي بتنزيل محتويات الكائن الثنائي كبير الحجم كنص. في هذا المثال، المعلمة encoding ضرورية readall() لإرجاع سلسلة، وإلا فإنها ترجع وحدات البايت:

def download_blob_to_string(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # encoding param is necessary for readall() to return str, otherwise it returns bytes
    downloader = blob_client.download_blob(max_concurrency=1, encoding='UTF-8')
    blob_text = downloader.readall()
    print(f"Blob contents: {blob_text}")

تنزيل كائن ثنائي كبير الحجم للكتلة مع خيارات التكوين

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

تحديد خيارات نقل البيانات عند التنزيل

يمكنك تعيين خيارات التكوين عند إنشاء مثيل لعميل لتحسين الأداء لعمليات نقل البيانات. يمكنك تمرير وسيطات الكلمة الأساسية التالية عند إنشاء كائن عميل في Python:

  • max_chunk_get_size - الحد الأقصى لحجم المجموعة المستخدمة لتنزيل كائن ثنائي كبير الحجم. الافتراضيات إلى 4 ميبي بايت.
  • max_single_get_size - الحد الأقصى لحجم الكائن الثنائي كبير الحجم الذي سيتم تنزيله في مكالمة واحدة. إذا تجاوز الحجم الإجمالي للكائن الثنائي max_single_get_sizeكبير الحجم ، يتم تنزيل باقي بيانات الكائن الثنائي كبير الحجم في مجموعات. الإعدادات الافتراضية إلى 32 ميبي بايت.

لعمليات التنزيل، يمكنك أيضا تمرير الوسيطة max_concurrency عند استدعاء download_blob. تحدد هذه الوسيطة الحد الأقصى لعدد الاتصالات المتوازية لعملية التنزيل.

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

def download_blob_transfer_options(self, account_url: str, container_name: str, blob_name: str):
    # Create a BlobClient object with data transfer options for download
    blob_client = BlobClient(
        account_url=account_url, 
        container_name=container_name, 
        blob_name=blob_name,
        credential=DefaultAzureCredential(),
        max_single_get_size=1024*1024*32, # 32 MiB
        max_chunk_get_size=1024*1024*4 # 4 MiB
    )

    with open(file=os.path.join(r'file_path', 'file_name'), mode="wb") as sample_blob:
        download_stream = blob_client.download_blob(max_concurrency=2)
        sample_blob.write(download_stream.readall())

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

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

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

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

    import asyncio

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

  2. أضف التعليمات البرمجية لتشغيل البرنامج باستخدام asyncio.run. تقوم هذه الدالة بتشغيل coroutine الذي تم تمريره، main() في مثالنا، وتدير asyncio حلقة الحدث. يتم الإعلان عن Coroutines باستخدام بناء الجملة غير المتزامن/انتظار. في هذا المثال، main() يقوم coroutine أولا بإنشاء المستوى 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.download_blob_to_file(blob_service_client, "sample-container")

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

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

    async def download_blob_to_file(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
    with open(file=os.path.join(r'filepath', 'filename'), mode="wb") as sample_blob:
        download_stream = await blob_client.download_blob()
        data = await download_stream.readall()
        sample_blob.write(data)

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

الموارد

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

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

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

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

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

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

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