Biblioteka klienta usługi Azure Web PubSub dla języka Python

Uwaga

Szczegółowe informacje na temat terminów używanych w tym miejscu opisano w artykule dotyczącym kluczowych pojęć.

Zestaw SDK po stronie klienta ma na celu przyspieszenie przepływu pracy dewelopera; w szczególności,

• upraszcza zarządzanie połączeniami klientów
• upraszcza wysyłanie komunikatów między klientami
• automatyczne ponawianie próby po niezamierzonych spadkach połączenia klienta
• niezawodne dostarczanie komunikatów o numerze i w kolejności po odzyskaniu po spadku połączenia

Jak pokazano na diagramie, klienci ustanawiają połączenia protokołu WebSocket z zasobem Web PubSub.

Wprowadzenie

Wymagania wstępne

• Python 3.8+
• Subskrypcja platformy Azure
• Zasób Web PubSub

1. Instalowanie pakietu azure-messaging-webpubsubclient

pip install azure-messaging-webpubsubclient

2. Nawiązywanie połączenia z zasobem Web PubSub

Klient używa obiektu Client Access URL do nawiązywania połączenia i uwierzytelniania za pomocą usługi, która jest zgodna ze wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>wzorcem . Klient może mieć kilka sposobów uzyskania .Client Access URL W tym przewodniku Szybki start możesz skopiować i wkleić go z wyświetlonej witryny Azure Portal.

Jak pokazano na diagramie, klient ma uprawnienia do wysyłania komunikatów do określonej grupy o nazwie 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. Dołącz do grup

Klient może odbierać komunikaty tylko z grup, które zostały przyłączone i należy dodać wywołanie zwrotne, aby określić logikę podczas odbierania komunikatów.

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. Wysyłanie komunikatów do grupy

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

Przykłady

Dodawanie wywołań zwrotnych dla zdarzeń connecteddisconnected i stopped

1. Po pomyślnym połączeniu klienta z zasobem Web PubSub zostanie wyzwolone zdarzenie connected.

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

2. Gdy klient zostanie odłączony i nie może odzyskać połączenia, zostanie wyzwolone zdarzenie disconnected.

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

3. Zdarzenie stopped jest wyzwalane po rozłączeniu klienta, a klient przestaje próbować ponownie nawiązać połączenie. Dzieje się tak zwykle po wywołaniu client.stop() lub auto_reconnect jest wyłączony lub osiągnięto określony limit próby ponownego nawiązania połączenia. Jeśli chcesz ponownie uruchomić klienta, możesz wywołać client.start() w zatrzymanych zdarzeniach.

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

Klient korzysta z komunikatów z serwera aplikacji lub grup przyłączonych

Klient może dodać wywołania zwrotne w celu korzystania z komunikatów z serwera aplikacji lub grup. Uwaga: w przypadku group-message zdarzenia klient może odbierać tylko komunikaty grupowe, które zostały dołączone.

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

---

Niepowodzenie ponownego dołączania

Gdy klient jest odłączony i nie można go odzyskać, wszystkie konteksty grupy są czyszczone w zasobie Web PubSub. Oznacza to, że po ponownym nawiązaniu połączenia klient musi ponownie połączyć się z grupami. Domyślnie klient ma włączoną opcję auto_rejoin_groups.

Należy jednak pamiętać o ograniczeniach auto_rejoin_groups.

• Klient może ponownie dołączyć tylko grupy, które są pierwotnie przyłączone przez kod klienta , a nie przez kod po stronie serwera.
• Operacje ponownego dołączania grupy mogą zakończyć się niepowodzeniem z różnych powodów, na przykład klient nie ma uprawnień do dołączania do grup. W takich przypadkach należy dodać wywołanie zwrotne w celu obsługi tego błędu.

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

Operacja i ponów próbę

Domyślnie operacja, taka jak client.join_group(), client.leave_group(), client.send_to_group(), client.send_event() ma trzy ponawiania prób. Można skonfigurować za pomocą argumentów słowa kluczowego. Jeśli wszystkie ponowne próby nie powiodły się, zostanie zgłoszony błąd. Ponów próbę można zachować, przekazując te same ack_id co poprzednie ponawianie prób, aby usługa Web PubSub mogła deduplikować operację.

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

Rozwiązywanie problemów

Włącz dzienniki

Możesz ustawić następującą zmienną środowiskową, aby pobrać dzienniki debugowania podczas korzystania z tej biblioteki.

export AZURE_LOG_LEVEL=verbose

Aby uzyskać bardziej szczegółowe instrukcje dotyczące włączania dzienników, zapoznaj się z dokumentami dotyczącymi pakietów @azure/rejestratora.

Śledzenie na żywo

Użyj narzędzia Live Trace z witryny Azure Portal, aby sprawdzić ruch komunikatów na żywo za pośrednictwem zasobu Web PubSub.