مشاركة عبر

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

  • مقالة

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

تستخدم أساليب مكتبة العميل المغطاة في هذه المقالة عملية Copy Blob REST API، ويمكن استخدامها عندما تريد إجراء نسخة بجدولة غير متزامنة. بالنسبة لمعظم سيناريوهات النسخ حيث تريد نقل البيانات إلى حساب تخزين ولديك عنوان URL للكائن المصدر، راجع نسخ كائن ثنائي كبير الحجم من عنوان URL لكائن مصدر باستخدام Python.

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

إعداد بيئتك

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

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

تثبيت الحزم

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

pip install azure-storage-blob azure-identity

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

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

import datetime
from azure.identity import DefaultAzureCredential
from azure.storage.blob import (
    BlobServiceClient,
    BlobClient,
    BlobLeaseClient,
    BlobSasPermissions,
    generate_blob_sas
)

التصريح

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

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

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

Copy Blob يمكن لعملية تنفيذ أي من الإجراءات التالية:

  • انسخ الكائن الثنائي كبير الحجم الخاص بالمصدر إلى كائن ثنائي كبير الحجم في الوجهة باسم مختلف. يمكن أن يكون الكائن الثنائي كبير الحجم الوجهة كائن ثنائي كبير الحجم موجود من نفس نوع الكائن الثنائي كبير الحجم (كتلة أو إلحاق أو صفحة)، أو يمكن أن يكون كائنا ثنائيا جديدا تم إنشاؤه بواسطة عملية النسخ.
  • انسخ كائن ثنائي كبير الحجم المصدر إلى كائن ثنائي كبير الحجم الوجهة بنفس الاسم، والذي يحل محل الكائن الثنائي كبير الحجم الوجهة. يزيل هذا النوع من عمليات النسخ أي كتل غير ملتزمة ويستبدل بيانات تعريف الكائن الثنائي كبير الحجم الوجهة.
  • انسخ ملف مصدر في خدمة Azure File إلى كائن ثنائي كبير الحجم في الوجهة. يمكن أن يكون الكائن الثنائي كبير الحجم في الوجهة كائنًا ثنائيًّا كبير الحجم لكتلة موجودة، أو يمكن أن يكون كائناً ثنائياً كبير الحجم لكتلة جديدة تم إنشاؤه من خلال عملية النسخ. النسخ من الملفات إلى الكائنات الثنائية كبيرة الحجم للصفحة أو الكائنات الثنائية كبيرة الحجم للإلحاق غير مدعوم.
  • انسخ لقطة فوق الكائن الثنائي كبير الحجم الأساسي الخاص بها. من خلال ترقية لقطة إلى موضع الكائن الثنائي كبير الحجم الأساسي، يمكنك استعادة إصدار سابق من كائن ثنائي كبير الحجم.
  • انسخ لقطة إلى كائن ثنائي كبير الحجم في الوجهة باسم مختلف. يكون الكائن الثنائي كبير الحجم في الوجهة الناتج عبارة عن كائن ثنائي كبير الحجم قابل للكتابة وليس لقطة.

قد يكون الكائن الثنائي كبير الحجم المصدر لعملية النسخ أحد الأنواع التالية: block blob أو append blob أو page blob أو لقطة blob أو إصدار blob. تنسخ عملية النسخ دائما الكائن الثنائي كبير الحجم أو الملف المصدر بأكمله. نسخ نطاق من وحدات البايت أو مجموعة من الكتل غير مدعوم.

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

لمعرفة المزيد حول العملية، بما في Copy Blob ذلك معلومات حول الخصائص وعلامات الفهرس وبيانات التعريف والفوترة، راجع نسخ ملاحظات Blob.

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

يقدم هذا القسم نظرة عامة على الأساليب التي توفرها مكتبة عميل Azure Storage ل Python لتنفيذ عملية نسخ بجدولة غير متزامنة.

تلتف الأساليب التالية عملية Copy Blob REST API، وتبدأ نسخة غير متزامنة من البيانات من الكائن الثنائي كبير الحجم المصدر:

يقوم start_copy_from_url بإرجاع قاموس يحتوي على copy_status copy_id. تكون خاصية copy_status ناجحة إذا اكتملت النسخة بشكل متزامن أو معلق إذا تم بدء النسخة بشكل غير متزامن.

نسخ كائن ثنائي كبير الحجم من مصدر داخل Azure

إذا كنت تقوم بنسخ كائن ثنائي كبير الحجم داخل نفس حساب التخزين، يمكن أن تكتمل العملية بشكل متزامن. يمكن التصريح بالوصول إلى الكائن الثنائي كبير الحجم المصدر عبر معرف Microsoft Entra أو توقيع وصول مشترك (SAS) أو مفتاح حساب. لعملية نسخ متزامنة تبديلية، راجع نسخ كائن ثنائي كبير الحجم من عنوان URL لكائن مصدر باستخدام Python.

إذا كان مصدر النسخ كائن ثنائي كبير الحجم في حساب تخزين مختلف، يمكن أن تكتمل العملية بشكل غير متزامن. يجب أن يكون الكائن الثنائي كبير الحجم المصدر عاما أو مخولا عبر رمز SAS المميز. يحتاج رمز SAS المميز إلى تضمين إذن القراءة ('r'). لمعرفة المزيد حول رموز SAS المميزة، راجع تفويض الوصول باستخدام توقيعات الوصول المشتركة.

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

def copy_from_source_in_azure_async(self, source_blob: BlobClient, destination_blob: BlobClient, blob_service_client: BlobServiceClient):
    # Lease the source blob during copy to prevent other clients from modifying it
    lease = BlobLeaseClient(client=source_blob)

    sas_token = self.generate_user_delegation_sas(blob_service_client=blob_service_client, source_blob=source_blob)
    source_blob_sas_url = source_blob.url + "?" + sas_token

    # Create an infinite lease by passing -1 as the lease duration
    lease.acquire(lease_duration=-1)

    # Start the copy operation - specify False for the requires_sync parameter
    copy_operation = dict()
    copy_operation = destination_blob.start_copy_from_url(source_url=source_blob_sas_url, requires_sync=False)
    
    # If start_copy_from_url returns copy_status of 'pending', the operation has been started asynchronously
    # You can optionally add logic here to wait for the copy operation to complete

    # Release the lease on the source blob
    lease.break_lease()

def generate_user_delegation_sas(self, blob_service_client: BlobServiceClient, source_blob: BlobClient):
    # Get a user delegation key
    delegation_key_start_time = datetime.datetime.now(datetime.timezone.utc)
    delegation_key_expiry_time = delegation_key_start_time + datetime.timedelta(hours=1)
    key = blob_service_client.get_user_delegation_key(
        key_start_time=delegation_key_start_time,
        key_expiry_time=delegation_key_expiry_time
    )

    # Create a SAS token that's valid for one hour, as an example
    sas_token = generate_blob_sas(
        account_name=blob_service_client.account_name,
        container_name=source_blob.container_name,
        blob_name=source_blob.blob_name,
        account_key=None,
        user_delegation_key=key,
        permission=BlobSasPermissions(read=True),
        expiry=datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(hours=1),
        start=datetime.datetime.now(datetime.timezone.utc)
    )

    return sas_token

إشعار

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

نسخ كائن ثنائي كبير الحجم من مصدر خارج Azure

يمكنك تنفيذ عملية نسخ على أي كائن مصدر يمكن استرداده عبر طلب HTTP GET على عنوان URL معين، بما في ذلك الكائنات التي يمكن الوصول إليها خارج Azure. يوضح المثال التالي سيناريو لنسخ كائن ثنائي كبير الحجم من عنوان URL لكائن مصدر يمكن الوصول إليه.

def copy_from_external_source_async(self, source_url: str, destination_blob: BlobClient):
    # Start the copy operation - specify False for the requires_sync parameter
    copy_operation = dict()
    copy_operation = destination_blob.start_copy_from_url(source_url=source_url, requires_sync=False)
    
    # If start_copy_from_url returns copy_status of 'pending', the operation has been started asynchronously
    # You can optionally add logic here to wait for the copy operation to complete

التحقق من حالة عملية النسخ

للتحقق من حالة عملية غير متزامنة Copy Blob ، يمكنك استقصاء أسلوب get_blob_properties والتحقق من حالة النسخ.

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

def check_copy_status(self, destination_blob: BlobClient):
    # Get the copy status from the destination blob properties
    copy_status = destination_blob.get_blob_properties().copy.status

    return copy_status

إجهاض عملية نسخ

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

لإجهاض عملية نسخ معلقة، قم باستدعاء العملية التالية:

يلتف هذا الأسلوب عملية Abort Copy Blob REST API، والتي تلغي عملية معلقة Copy Blob . يوضح مثال التعليمات البرمجية التالي كيفية إجهاض عملية معلقة Copy Blob :

def abort_copy(self, destination_blob: BlobClient):
    # Get the copy operation details from the destination blob properties
    copy_status = destination_blob.get_blob_properties().copy.status
    copy_id = destination_blob.get_blob_properties().copy.id

    # Check the copy status and abort if pending
    if copy_status == 'pending':
        destination_blob.abort_copy(copy_id)
        print(f"Copy operation {copy_id} has been aborted")

الموارد

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

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

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

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

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

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

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