Azure Web PubSub-klientbibliotek för Python

SDK:et på klientsidan syftar till att påskynda utvecklarens arbetsflöde. mer specifikt,

• förenklar hanteringen av klientanslutningar
• förenklar sändning av meddelanden mellan klienter
• försöker automatiskt igen efter oavsiktliga droppar av klientanslutningen
• levererar tillförlitligt meddelanden i antal och i ordning efter att anslutningen har återställts

Som du ser i diagrammet upprättar klienterna WebSocket-anslutningar med din Web PubSub-resurs.

Komma igång

Förutsättningar

• Python 3.8+
• En prenumeration på Azure
• En Web PubSub-resurs

1. Installera azure-messaging-webpubsubclient-paketet

pip install azure-messaging-webpubsubclient

2. Anslut med din Web PubSub-resurs

En klient använder en Client Access URL för att ansluta och autentisera med tjänsten, som följer ett mönster av wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. En klient kan ha några sätt att hämta Client Access URL. För den här snabbstarten kan du kopiera och klistra in en från Azure-portalen som visas.

Som du ser i diagrammet har klienten behörighet att skicka meddelanden till och ansluta till en specifik grupp med namnet 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. Gå med i grupper

En klient kan bara ta emot meddelanden från grupper som den har anslutit och du behöver lägga till ett återanrop för att ange logiken när du tar emot meddelanden.

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. Skicka meddelanden till en grupp

# ...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.

Exempel

Lägga till återanrop för connected, disconnected och stopped händelser

1. När en klient har anslutits till din Web PubSub-resurs utlöses den connected händelsen.

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

2. När en klient kopplas från och inte kan återställa anslutningen utlöses disconnected händelsen.

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

3. Händelsen stopped utlöses när klienten är frånkopplad och klienten slutar försöka återansluta. Detta inträffar vanligtvis när client.stop() anropas eller auto_reconnect har inaktiverats eller en angiven gräns för att försöka återansluta har nåtts. Om du vill starta om klienten kan du anropa client.start() i den stoppade händelsen.

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

En klient använder meddelanden från programservern eller anslutna grupper

En klient kan lägga till återanrop för att använda meddelanden från programservern eller -grupper. Obs! För group-message händelse kan klienten bara ta emot gruppmeddelanden som den har anslutit.

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}"))

Hantera återanslutna fel

När en klient kopplas från och inte kan återställas rensas alla gruppkontexter i din Web PubSub-resurs. Det innebär att när klienten återansluter måste den återansluta till grupper. Som standard har klienten auto_rejoin_groups alternativet aktiverat.

Du bör dock vara medveten om auto_rejoin_groupsbegränsningar.

• Klienten kan bara återansluta till grupper som den ursprungligen är ansluten till av klientkoden , inte av koden på serversidan.
• Åtgärder för att "återansluta till grupp" kan misslyckas på grund av olika orsaker, till exempel att klienten inte har behörighet att ansluta till grupperna. I sådana fall måste du lägga till ett återanrop för att hantera det här felet.

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}"))

Åtgärd och försök igen

Som standard har åtgärden som client.join_group(), client.leave_group(), client.send_to_group(), client.send_event() tre återförsök. Du kan konfigurera via nyckelordsargumenten. Om alla återförsök har misslyckats utlöses ett fel. Du kan fortsätta att försöka igen genom att skicka in samma ack_id som tidigare försök så att Web PubSub-tjänsten kan deduplicera åtgärden.

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

Felsökning

Aktivera loggar

Du kan ange följande miljövariabel för att hämta felsökningsloggarna när du använder det här biblioteket.

export AZURE_LOG_LEVEL=verbose

Mer detaljerade anvisningar om hur du aktiverar loggar finns i dokument för @azure/logger-paket.

Livespårning

Använd livespårningsverktyget från Azure Portal för att inspektera livemeddelandetrafik via din Web PubSub-resurs.