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

• NET.
• Java
• جافا سكريبت
• TypeScript
• Python

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

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

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

• تفترض هذه المقالة أن لديك بالفعل مشروعا تم إعداده للعمل مع مكتبة عميل Azure Blob Storage ل Python. للتعرف على إعداد مشروعك، بما في ذلك تثبيت الحزمة وإضافة import عبارات وإنشاء كائن عميل معتمد، راجع بدء استخدام Azure Blob Storage وPython.
• لاستخدام واجهات برمجة التطبيقات غير المتزامنة في التعليمات البرمجية الخاصة بك، راجع المتطلبات في قسم البرمجة غير المتزامنة.
• يجب أن يكون لآلية التخويل أذونات لتنفيذ عملية تحميل. لمعرفة المزيد، راجع إرشادات التخويل لعمليات واجهة برمجة تطبيقات REST التالية:
  • ضع الكائن الثنائي كبير الحجم
  • وضع كتلة

تحميل البيانات إلى كائن ثنائي كبير الحجم للكتلة

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

• upload_blob

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

تحميل كائن ثنائي كبير الحجم للكتلة من مسار ملف محلي

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

def upload_blob_file(self, blob_service_client: BlobServiceClient, container_name: str):
    container_client = blob_service_client.get_container_client(container=container_name)
    with open(file=os.path.join('filepath', 'filename'), mode="rb") as data:
        blob_client = container_client.upload_blob(name="sample-blob.txt", data=data, overwrite=True)

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

ينشئ المثال التالي وحدات بايت عشوائية من البيانات ويحمل كائنا BytesIO إلى كائن ثنائي كبير الحجم للكتلة باستخدام كائن BlobClient :

def upload_blob_stream(self, blob_service_client: BlobServiceClient, container_name: str):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
    input_stream = io.BytesIO(os.urandom(15))
    blob_client.upload_blob(input_stream, blob_type="BlockBlob")

تحميل البيانات الثنائية إلى كائن ثنائي كبير الحجم للكتلة

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

def upload_blob_data(self, blob_service_client: BlobServiceClient, container_name: str):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
    data = b"Sample data for blob"

    # Upload the blob data - default blob type is BlockBlob
    blob_client.upload_blob(data, blob_type="BlockBlob")

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

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

def upload_blob_tags(self, blob_service_client: BlobServiceClient, container_name: str):
    container_client = blob_service_client.get_container_client(container=container_name)
    sample_tags = {"Content": "image", "Date": "2022-01-01"}
    with open(file=os.path.join('filepath', 'filename'), mode="rb") as data:
        blob_client = container_client.upload_blob(name="sample-blob.txt", data=data, tags=sample_tags)

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

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

تحديد خيارات نقل البيانات للتحميل

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

• max_block_size - الحد الأقصى لحجم المجموعة لتحميل كتلة كائن ثنائي كبير الحجم في مجموعات. الافتراضيات إلى 4 ميبي بايت.
• max_single_put_size - إذا كان حجم الكائن الثنائي كبير الحجم أقل من أو يساوي max_single_put_size، يتم تحميل الكائن الثنائي كبير الحجم بطلب واحد Put Blob . إذا كان حجم الكائن الثنائي كبير الحجم أكبر من max_single_put_size أو غير معروف، يتم تحميل الكائن الثنائي كبير الحجم في مجموعات باستخدام Put Block وتثبيته باستخدام Put Block List. الافتراضيات إلى 64 ميبي بايت.

لمزيد من المعلومات حول حدود حجم النقل لتخزين Blob، راجع أهداف المقياس لتخزين Blob.

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

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

def upload_blob_transfer_options(self, account_url: str, container_name: str, blob_name: str):
    # Create a BlobClient object with data transfer options for upload
    blob_client = BlobClient(
        account_url=account_url, 
        container_name=container_name, 
        blob_name=blob_name,
        credential=DefaultAzureCredential(),
        max_block_size=1024*1024*4, # 4 MiB
        max_single_put_size=1024*1024*8 # 8 MiB
    )
    
    with open(file=os.path.join(r'file_path', blob_name), mode="rb") as data:
        blob_client = blob_client.upload_blob(data=data, overwrite=True, max_concurrency=2)

لمعرفة المزيد حول خيارات ضبط نقل البيانات، راجع ضبط الأداء للتحميلات والتنزيلات باستخدام Python.

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

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

يوضح مثال التعليمات البرمجية التالي كيفية تعيين طبقة الوصول عند تحميل كائن ثنائي كبير الحجم:

def upload_blob_access_tier(self, blob_service_client: BlobServiceClient, container_name: str, blob_name: str):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob=blob_name)
    
    #Upload blob to the cool tier
    with open(file=os.path.join(r'file_path', blob_name), mode="rb") as data:
        blob_client = blob_client.upload_blob(data=data, overwrite=True, standard_blob_tier=StandardBlobTier.COOL)

يسمح بتعيين طبقة الوصول فقط لكتل الكائنات الثنائية كبيرة الحجم. يمكنك تعيين طبقة الوصول لكتلة كائن ثنائي كبير الحجم إلى Hotأو CoolColdأو أو Archive. لتعيين مستوى الوصول إلى Cold، يجب استخدام الحد الأدنى لإصدار مكتبة العميل من 12.15.0.

لمعرفة المزيد حول مستويات الوصول، راجع نظرة عامة على مستويات الوصول.

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

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

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

• stage_block

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

• commit_block_list

يقرأ المثال التالي البيانات من ملف ويرحل كتل ليتم الالتزام بها كجزء من كائن ثنائي كبير الحجم:

def upload_blocks(self, blob_container_client: ContainerClient, local_file_path: str, block_size: int):
    file_name = os.path.basename(local_file_path)
    blob_client = blob_container_client.get_blob_client(file_name)

    with open(file=local_file_path, mode="rb") as file_stream:
        block_id_list = []

        while True:
            buffer = file_stream.read(block_size)
            if not buffer:
                break

            block_id = uuid.uuid4().hex
            block_id_list.append(BlobBlock(block_id=block_id))

            blob_client.stage_block(block_id=block_id, data=buffer, length=len(buffer))

        blob_client.commit_block_list(block_id_list)

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

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

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

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

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

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.upload_blob_file(blob_service_client, "sample-container")
   
   if __name__ == '__main__':
       asyncio.run(main())
   

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

   async def upload_blob_file(self, blob_service_client: BlobServiceClient, container_name: str):
       container_client = blob_service_client.get_container_client(container=container_name)
       with open(file=os.path.join('filepath', 'filename'), mode="rb") as data:
           blob_client = await container_client.upload_blob(name="sample-blob.txt", data=data, overwrite=True)
   

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

الموارد

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

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

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

• وضع كائن ثنائي كبير الحجم (واجهة برمجة تطبيقات REST)
• وضع كتلة (واجهة برمجة تطبيقات REST)

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

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

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

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

(راجع أيضًا )

• إدارة بيانات Azure Blob والعثور عليها باستخدام علامات فهرس كائن ثنائي كبير الحجم
• استخدام علامات فهرسة الكائنات الثنائية كبيرة الحجم لإدارة البيانات والعثور عليها في مساحة تخزين Azure Blob