Klientská knihovna Azure Web PubSub pro Python

Poznámka:

Podrobnosti o zde použitých termínech jsou popsány v klíčovém článku o konceptech .

Cílem sady SDK na straně klienta je urychlit pracovní postup vývojáře; konkrétněji,

• zjednodušuje správu klientských připojení.
• zjednodušuje odesílání zpráv mezi klienty.
• automatické opakování po nezamýšlených poklesech připojení klienta
• spolehlivé doručování zpráv v čísle a v pořadí po obnovení z výpadků připojení

Jak je znázorněno v diagramu, vaši klienti navazují připojení WebSocket s prostředkem Web PubSub.

Začínáme

Požadavky

• Python 3.8 nebo novější
• Předplatné Azure
• Prostředek Web PubSub

1. Instalace azure-messaging-webpubsubclient balíčku

pip install azure-messaging-webpubsubclient

2. Připojení k prostředku Web PubSub

Klient používá Client Access URL k připojení a ověření se službou, která se řídí vzorem wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Klient může mít několik způsobů, jak získat Client Access URL. Pro účely tohoto rychlého startu můžete ho zkopírovat a vložit ze zobrazeného webu Azure Portal.

Jak je znázorněno v diagramu, má klient oprávnění k odesílání zpráv a připojení ke konkrétní skupině s názvem 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. Připojte se ke skupinám

Klient může přijímat zprávy pouze ze skupin, které se připojil, a potřebujete přidat zpětné volání, abyste při přijímání zpráv zadali logiku.

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. Odesílání zpráv skupině

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

Příklady

Přidání zpětných volání pro connecteddisconnected a stopped události

1. Když se klient úspěšně připojí k vašemu prostředku Web PubSub, connected aktivuje se událost.

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

2. Když se klient odpojí a připojení se nepodaří obnovit, disconnected aktivuje se událost.

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

3. Událost stopped se aktivuje, když se klient odpojí a klient se přestane pokoušet znovu připojit. K tomu obvykle dochází po client.stop() zavolání nebo auto_reconnect zakázání nebo zadaném limitu, ke kterému se pokoušíte znovu připojit. Pokud chcete klienta restartovat, můžete zavolat client.start() v zastavené události.

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

Klient využívá zprávy z aplikačního serveru nebo připojených skupin.

Klient může přidat zpětná volání, která budou přijímat zprávy z aplikačního serveru nebo skupin. Upozorňujeme, že v group-message případě události může klient přijímat pouze zprávy skupiny, ke kterým se připojil.

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

---

Zpracování selhání opětovného připojení

Když se klient odpojí a nepodaří se obnovit, všechny kontexty skupin se vyčistí v prostředku Web PubSub. To znamená, že když se klient znovu připojí, musí se znovu připojit ke skupinám. Ve výchozím nastavení má auto_rejoin_groups klient povolenou možnost.

Měli byste ale vědět o auto_rejoin_groupsomezeních.

• Klient se může znovu připojit pouze ke skupinám, ke kterým byl původně připojen kódem klienta , nikoli kódem na straně serveru.
• Operace opětovného připojení ke skupině můžou selhat z různých důvodů, například klient nemá oprávnění připojit se ke skupinám. V takových případech je potřeba přidat zpětná volání pro zpracování tohoto selhání.

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

Operace a opakování

Ve výchozím nastavení má operace, například client.join_group(), client.leave_group()client.send_to_group()client.send_event() tři opakování. Můžete nakonfigurovat pomocí argumentů klíčového slova. Pokud došlo k selhání všech opakovaných pokusů, vyvolá se chyba. Opakování můžete pokračovat předáním stejných ack_id opakování jako v předchozích opakováních, aby služba Web PubSub mohl operaci odstraněním duplicit.

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

Řešení problémů

Povolit protokoly

Následující proměnnou prostředí můžete nastavit tak, aby při používání této knihovny získala protokoly ladění.

export AZURE_LOG_LEVEL=verbose

Podrobnější pokyny k povolení protokolů najdete v dokumentaci k @azure/protokolovacímu balíčku.

Živé trasování

Pomocí nástroje Živé trasování z webu Azure Portal můžete kontrolovat provoz živých zpráv prostřednictvím prostředku Web PubSub.