Azure Web PubSub-Clientbibliothek für Python

Das clientseitige SDK soll den Entwicklungsworkflow insbesondere durch Folgendes beschleunigen:

• vereinfacht die Verwaltung von Clientverbindungen
• vereinfacht das Senden von Nachrichten zwischen Clients
• automatische Wiederholungen nach unbeabsichtigten Abbrüchen der Clientverbindung
• Zuverlässige Übermittlung aller Nachrichten in der richtigen Reihenfolge bei der Wiederherstellung nach Verbindungsabbrüchen

Wie in der Abbildung dargestellt, richten Ihre Clients WebSocket-Verbindungen mit Ihrer Web PubSub-Ressource ein.

Erste Schritte

Voraussetzungen

• Ab Python 3.8
• Ein Azure-Abonnement
• Eine Web PubSub-Ressource

1. Installieren des azure-messaging-webpubsubclient-Pakets

pip install azure-messaging-webpubsubclient

2. Herstellen einer Verbindung mit Ihrer Web PubSub-Ressource

Ein Client verwendet eine Client Access URL Verbindung und Authentifizierung mit dem Dienst, die auf ein Muster folgt wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Ein Client kann einige Möglichkeiten haben, die Client Access URL. Für diesen Schnellstart können Sie eins aus dem angezeigten Azure-Portal kopieren und einfügen.

Wie in der Abbildung gezeigt, verfügt der Client über die Berechtigungen zum Senden von Nachrichten an eine Gruppe namens group1 und zum Beitreten zu dieser.

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. Gruppen beitreten

Ein Client kann nur Nachrichten von Gruppen empfangen, denen er beigetreten ist, und Sie müssen einen Rückruf hinzufügen, um die Logik beim Empfangen von Nachrichten anzugeben.

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. Senden von Nachrichten an eine Gruppe

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

Beispiele

Hinzufügen von Rückrufen für connectedUnd-Ereignisse disconnectedstopped

1. Wenn ein Client erfolgreich mit Ihrer Web PubSub-Ressource verbunden ist, wird das connected-Ereignis ausgelöst.

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

2. Wenn ein Client getrennt wird und die Verbindung nicht wiederhergestellt werden kann, wird das disconnected-Ereignis ausgelöst.

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

3. Das stopped-Ereignis wird ausgelöst, wenn die Clientverbindung getrennt wird und der Client nicht mehr versucht, die Verbindung wiederherzustellen. Dies geschieht in der Regel, nachdem die client.stop() aufgerufen wurde, oder auto_reconnect deaktiviert ist oder ein festgelegter Grenzwert für den Versuch, die Verbindung wiederherzustellen, erreicht wurde. Wenn Sie den Client neu starten möchten, können Sie client.start() im angehaltenen Ereignis aufrufen.

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

Ein Client nutzt Nachrichten vom Anwendungsserver oder verknüpften Gruppen.

Ein Client kann Rückrufe hinzufügen, um Nachrichten von Ihrem Anwendungsserver oder -gruppen zu nutzen. Beachten Sie, dass der Client nurgroup-message Gruppennachrichten empfangen kann, denen er beigetreten ist.

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

Behandeln eines Erneutverknüpfungsfehlers

Wenn eine Clientverbindung getrennt wird und nicht wiederhergestellt werden kann, werden alle Gruppenkontexte in Ihrer Web PubSub-Ressource bereinigt. Dies bedeutet, dass der Client erneut eine Verbindung herstellen muss, um Gruppen erneut anzuordnen. Standardmäßig ist der Client auto_rejoin_groups Option aktiviert.

Beachten Sie jedoch die Einschränkungen auto_rejoin_groups.

• Der Client kann nur Gruppen erneut beitreten, die ursprünglich vom Clientcode verbunden sind , nicht vom serverseitigen Code.
• Vorgänge "Erneut beitreten" können aufgrund verschiedener Gründe fehlschlagen, z. B. verfügt der Client nicht über die Berechtigung zum Beitreten zu den Gruppen. In solchen Fällen müssen Sie einen Rückruf hinzufügen, um diesen Fehler zu behandeln.

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

Vorgang und Wiederholen

Standardmäßig weist der Vorgang wie client.join_group(), client.leave_group(), client.send_to_group(), client.send_event() drei Wiederholungen auf. Sie können die Schlüsselwortargumente konfigurieren. Wenn alle Wiederholungen fehlerhaft waren, wird ein Fehler ausgelöst. Sie können den Vorgang weiterhin wiederholen, indem Sie dieselbe ack_id wie vorherige Wiederholungen übergeben, damit der Web PubSub-Dienst den Vorgang deduplizieren kann.

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

Problembehandlung

Aktivieren von Protokollen

Sie können die folgende Umgebungsvariable festlegen, um die Debugprotokolle abzurufen, wenn Sie diese Bibliothek verwenden.

export AZURE_LOG_LEVEL=verbose

Ausführlichere Anweisungen zum Aktivieren von Protokollen finden Sie in den @azure/Logger-Paketdokumenten.

Live-Ablaufverfolgung

Verwenden Sie im Azure-Portal das Tool Live-Ablaufverfolgung, um den Nachrichtendatenverkehr über Ihre Web PubSub-Ressource live zu überprüfen.