مكتبة عميل Azure Web PubSub ل Python

ملاحظة

يتم وصف تفاصيل حول المصطلحات المستخدمة هنا في مقالة المفاهيم الرئيسية.

تهدف SDK من جانب العميل إلى تسريع سير عمل المطور؛ بشكل أكثر تحديدا،

• يبسط إدارة اتصالات العميل
• يبسط إرسال الرسائل بين العملاء
• إعادة المحاولة تلقائيا بعد قطرات غير مقصودة من اتصال العميل
• تسليم الرسائل بشكل موثوق بالرقم وبالترتيب بعد التعافي من انخفاض الاتصال

كما هو موضح في الرسم التخطيطي، يقوم عملاؤك بإنشاء اتصالات WebSocket مع مورد Web PubSub.

الشروع في العمل

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

• Python 3.8+
• اشتراك Azure
• مورد Web PubSub

1. تثبيت حزمة azure-messaging-webpubsubclient

pip install azure-messaging-webpubsubclient

2. الاتصال بمورد Web PubSub

يستخدم Client Access URL العميل للاتصال والمصادقة مع الخدمة، والتي تتبع نمطا من wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. يمكن أن يكون لدى العميل بعض الطرق للحصول على Client Access URL. لهذا البدء السريع، يمكنك نسخ ولصق واحد من مدخل Microsoft Azure المعروض.

كما هو موضح في الرسم التخطيطي، لدى العميل أذونات لإرسال الرسائل والانضمام إلى مجموعة معينة تسمى group1.

from azure.messaging.webpubsubclient import WebPubSubClient

client = WebPubSubClient("<client-access-url>")
with client:
    # The client can join/leave groups, send/receive messages to and from those groups all in real-time
    ...

3. الانضمام إلى المجموعات

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

from azure.messaging.webpubsubclient.models import CallbackType

# ...continues the code snippet from above

# Registers a listener for the event 'group-message' early before joining a group to not miss messages
group_name = "group1";
client.subscribe(CallbackType.GROUP_MESSAGE, lambda e: print(f"Received message: {e.data}"));

# A client needs to join the group it wishes to receive messages from
client.join_group(groupName);

4. إرسال رسائل إلى مجموعة

# ...continues the code snippet from above

# Send a message to a joined group
client.send_to_group(group_name, "hello world", "text");

# In the Console tab of your developer tools found in your browser, you should see the message printed there.

امثله

إضافة عمليات رد اتصال للأحداث connecteddisconnected و و stopped

1. عند اتصال عميل بنجاح بمورد Web PubSub الخاص بك، يتم تشغيل الحدث connected.

   from azure.messaging.webpubsubclient.models import CallbackType
   
   client.subscribe(CallbackType.CONNECTED, lambda e: print(f"Connection {e.connection_id} is connected"))
   

2. عند قطع اتصال عميل وفشل استرداد الاتصال، يتم تشغيل الحدث disconnected.

   from azure.messaging.webpubsubclient.models import CallbackType
   
   client.subscribe(CallbackType.DISCONNECTED, lambda e: print(f"Connection disconnected: {e.message}"))
   

3. stopped يتم تشغيل الحدث عند قطع اتصال العميل ويتوقف العميل عن محاولة إعادة الاتصال. يحدث هذا عادة بعد استدعاء client.stop()، أو تعطيل auto_reconnect أو الوصول إلى حد محدد لمحاولة إعادة الاتصال. إذا كنت ترغب في إعادة تشغيل العميل، يمكنك استدعاء client.start() في الحدث المتوقف.

   from azure.messaging.webpubsubclient.models import CallbackType
   
   client.subscribe(CallbackType.STOPPED, lambda : print("Client has stopped"))
   

يستهلك العميل رسائل من خادم التطبيق أو المجموعات المنضمة

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

from azure.messaging.webpubsubclient.models import CallbackType

# Registers a listener for the "server-message". The callback is invoked when your application server sends message to the connectionID, to or broadcast to all connections.
client.subscribe(CallbackType.CONNECTED, lambda e: print(f"Received message {e.data}"))

# Registers a listener for the "group-message". The callback is invoked when the client receives a message from the groups it has joined.
client.subscribe(CallbackType.GROUP_MESSAGE, lambda e: print(f"Received message from {e.group}: {e.data}"))

---

معالجة فشل إعادة الانضمام

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

ومع ذلك، يجب أن تكون على علم بقيود auto_rejoin_groups.

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

from azure.messaging.webpubsubclient.models import CallbackType

# By default auto_rejoin_groups=True. You can disable it by setting to False.
client = WebPubSubClient("<client-access-url>", auto_rejoin_groups=True);

# Registers a listener to handle "rejoin-group-failed" event
client.subscribe(CallbackType.REJOIN_GROUP_FAILED, lambda e: print(f"Rejoin group {e.group} failed: {e.error}"))

العملية وإعادة المحاولة

بشكل افتراضي، تحتوي العملية مثل client.join_group()client.leave_group()client.send_to_group()client.send_event() على ثلاث محاولات. يمكنك التكوين من خلال وسيطات كلمة المفتاح. إذا فشلت جميع عمليات إعادة المحاولة، يتم طرح خطأ. يمكنك الاستمرار في إعادة المحاولة عن طريق تمرير نفس ack_id مثل عمليات إعادة المحاولة السابقة بحيث يمكن لخدمة Web PubSub إلغاء تكرار العملية.

try:
    client.join_group(group_name)
except SendMessageError as e:
    client.join_group(group_name, ack_id=e.ack_id)

استكشاف الأخطاء وإصلاحها

تمكين السجلات

يمكنك تعيين متغير البيئة التالي للحصول على سجلات تتبع الأخطاء عند استخدام هذه المكتبة.

export AZURE_LOG_LEVEL=verbose

للحصول على إرشادات أكثر تفصيلا حول كيفية تمكين السجلات، يمكنك إلقاء نظرة على مستندات حزمة @azure/المسجل.

تتبع مباشر

استخدم أداة Live Trace من مدخل Microsoft Azure لفحص حركة مرور الرسائل المباشرة من خلال مورد Web PubSub.