إنشاء وإدارة عقود إيجار الحاويات باستخدام Python

• NET.
• Java
• JavaScript
• Python

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

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

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

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

إعداد بيئتك

إذا لم يكن لديك مشروع موجود، يوضح لك هذا القسم كيفية إعداد مشروع للعمل مع مكتبة عميل 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, BlobLeaseClient

التصريح

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

حول عقود إيجار الحاوية

يقوم عقد الإيجار بإنشاء تأمين على حاوية وإدارتها لعمليات الحذف. يمكن أن تتراوح مدة التأمين من 15 إلى 60 ثانية، أو يمكن أن تكون غير محدودة. يوفر التأجير على حاوية وصول حذف حصري إلى الحاوية. يتحكم تأجير الحاوية فقط في القدرة على حذف الحاوية باستخدام عملية Delete Container REST API. لحذف حاوية ذات عقد إيجار نشط، يجب على العميل تضمين معرف الإيجار النشط مع طلب الحذف. تنجح جميع عمليات الحاوية الأخرى على حاوية مؤجرة دون معرف التأجير. إذا قمت بتمكين الحذف المبدئي للحاوية، يمكنك استعادة الحاويات المحذوفة.

لمعرفة المزيد حول حالات التأجير ومتى يمكنك تنفيذ إجراء معين على عقد إيجار، راجع حالات وإجراءات التأجير.

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

الحصول على عقد إيجار

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

للحصول على عقد إيجار، أنشئ مثيلا لفئة BlobLeaseClient ، ثم استخدم الأسلوب التالي:

• BlobLeaseClient.acquire

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

• ContainerClient.acquire_lease

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

def acquire_container_lease(self, blob_service_client: BlobServiceClient, container_name):
    # Instantiate a ContainerClient
    container_client = blob_service_client.get_container_client(container=container_name)

    # Acquire a 30-second lease on the container
    lease_client = container_client.acquire_lease(30)

    return lease_client

تجديد عقد الإيجار

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

لتجديد عقد إيجار، استخدم الأسلوب التالي:

• BlobLeaseClient.renew

يجدد المثال التالي عقد إيجار لحاوية:

def renew_container_lease(self, lease_client: BlobLeaseClient):
    # Renew a lease on the container
    lease_client.renew()

الإفراج عن عقد إيجار

يمكنك تحرير عقد تأجير حاوية إذا كان معرف التأجير المحدد في الطلب يطابق معرف التأجير المقترن بالحاوية. يسمح إصدار عقد إيجار لعميل آخر بالحصول على عقد إيجار للحاوية مباشرة بعد اكتمال الإصدار.

يمكنك إصدار عقد إيجار باستخدام الأسلوب التالي:

• BlobLeaseClient.release

يطلق المثال التالي عقد الإيجار على حاوية:

def release_container_lease(self, lease_client: BlobLeaseClient):
    # Release a lease on the container
    lease_client.release()

إنهاء عقد الإيجار

يمكنك قطع عقد تأجير الحاوية إذا كانت الحاوية لديها عقد إيجار نشط. يمكن لأي طلب مصرح به قطع عقد الإيجار؛ الطلب غير مطلوب لتحديد معرف تأجير مطابق. لا يمكن تجديد عقد الإيجار بعد قطعه، ويمنع قطع عقد الإيجار الحصول على عقد إيجار جديد لفترة من الوقت حتى تنتهي صلاحية عقد الإيجار الأصلي أو يتم تحريره.

يمكنك قطع عقد الإيجار باستخدام الأسلوب التالي:

• BlobLeaseClient.break_lease

يكسر المثال التالي عقد الإيجار على حاوية:

def break_container_lease(self, lease_client: BlobLeaseClient):
    # Break a lease on the container
    lease_client.break_lease()

تأجير الحاويات بشكل غير متزامن

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

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

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

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

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

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

   async def acquire_container_lease(self, blob_service_client: BlobServiceClient, container_name):
       # Instantiate a ContainerClient
       container_client = blob_service_client.get_container_client(container=container_name)
   
       # Acquire a 30-second lease on the container
       lease_client = BlobLeaseClient(container_client)
       await lease_client.acquire(lease_duration=30)
   
       return lease_client
   

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

حالات الإيجار والإجراءات

يوضح الرسم التخطيطي التالي الحالات الخمس لإيجار، والأوامر أو الأحداث التي تتسبب في تغييرات حالة التأجير.

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

حالة التأجير	‏‏الوصف	إجراءات التأجير المسموح بها
متوفر	عقد الإيجار غير مؤمن ويمكن الحصول عليه.	acquire
المؤجره	عقد الإيجار مؤمن.	acquire (معرف التأجير نفسه فقط)، renewو change، و، releaseو break
انتهت	انتهت مدة التأجير.	acquireو renewreleaseوbreak
كسر	تم قطع عقد الإيجار، ولكن سيستمر تأمين عقد الإيجار حتى انتهاء فترة التوقف.	release وbreak
مكسور	تم قطع عقد الإيجار، وانتهاء فترة التوقف.	acquire وrelease وbreak

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

إذا انتهت صلاحية عقد الإيجار بدلا من إصداره بشكل صريح، فقد يحتاج العميل إلى الانتظار لمدة تصل إلى دقيقة واحدة قبل الحصول على عقد إيجار جديد للحاوية. ومع ذلك، يمكن للعميل تجديد التأجير مع معرف التأجير منتهية الصلاحية على الفور.

الموارد

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

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

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

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

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

• حاوية التأجير (REST API)

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

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

(راجع أيضًا )

• إدارة التزامن في تخزين Blob

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

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