Bibliothèque de client Azure Web PubSub pour Python

Le SDK côté client vise à accélérer le flux de travail des développeurs ; plus précisément,

• simplifie la gestion des connexions clientes
• simplifie l’envoi de messages entre les clients
• réessayer automatiquement après des suppressions involontaires de la connexion cliente
• remet de manière fiable les messages en nombre et dans l’ordre après la récupération à partir des suppressions de connexion

Comme le montre le diagramme, vos clients établissent des connexions WebSocket avec votre ressource Web PubSub.

Mise en route

Conditions préalables

• Python 3.8+
• Un abonnement Azure
• Une ressource Web PubSub

1. Installer le package azure-messaging-webpubsubclient

pip install azure-messaging-webpubsubclient

2. Connectez-vous à votre ressource Web PubSub

Un client utilise une connexion et une Client Access URL authentification auprès du service, qui suit un modèle de wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Un client peut avoir quelques façons d’obtenir le Client Access URL. Pour ce démarrage rapide, vous pouvez copier et coller un à partir du portail Azure affiché.

Comme indiqué dans le diagramme, le client dispose des autorisations nécessaires pour envoyer des messages et rejoindre un groupe spécifique nommé 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. Joindre des groupes

Un client peut uniquement recevoir des messages de groupes qu’il a joints et vous devez ajouter un rappel pour spécifier la logique lors de la réception de messages.

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. Envoyer des messages à un groupe

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

Exemples

Ajouter des rappels pour connectedles événements disconnected et stopped les événements

1. Lorsqu’un client est correctement connecté à votre ressource Web PubSub, l’événement connected est déclenché.

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

2. Lorsqu’un client est déconnecté et ne parvient pas à récupérer la connexion, l’événement disconnected est déclenché.

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

3. L’événement stopped est déclenché lorsque le client est déconnecté et que le client cesse de tenter de se reconnecter. Cela se produit généralement après l’appel du client.stop(), ou auto_reconnect est désactivé ou une limite spécifiée pour essayer de se reconnecter a atteint. Si vous souhaitez redémarrer le client, vous pouvez appeler client.start() dans l’événement arrêté.

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

Un client consomme des messages à partir du serveur d’applications ou des groupes joints

Un client peut ajouter des rappels pour consommer des messages à partir de votre serveur d’applications ou groupes. Notez que, pour group-message l’événement, le client ne peut recevoir que des messages de groupe qu’il a joints.

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

Gérer l’échec de jointeur

Lorsqu'un client est déconnecté et ne parvient pas à se rétablir, tous les contextes de groupe sont nettoyés dans votre ressource Web PubSub. Cela signifie que lorsque le client se reconnecte, il doit rejoindre des groupes. Par défaut, le client a auto_rejoin_groups option activée.

Toutefois, vous devez connaître les limitations de auto_rejoin_groups.

• Le client peut uniquement rejoindre des groupes qu’il est joint à l’origine par le code client et non par le code côté serveur.
• Les opérations « rejoindre un groupe » peuvent échouer en raison de diverses raisons, par exemple, le client n’a pas l’autorisation de rejoindre les groupes. Dans ce cas, vous devez ajouter un rappel pour gérer cette défaillance.

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

Opération et nouvelle tentative

Par défaut, l’opération telle que client.join_group(), client.leave_group(), client.send_to_group(), client.send_event() a trois nouvelles tentatives. Vous pouvez configurer par le biais des arguments de mot clé. Si toutes les nouvelles tentatives ont échoué, une erreur est levée. Vous pouvez continuer à réessayer en transmettant les mêmes ack_id que les nouvelles tentatives précédentes afin que le service Web PubSub puisse dédupliquer l’opération.

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

Résolution des problèmes

Activer les journaux

Vous pouvez définir la variable d’environnement suivante pour obtenir les journaux de débogage lors de l’utilisation de cette bibliothèque.

export AZURE_LOG_LEVEL=verbose

Pour obtenir des instructions plus détaillées sur l’activation des journaux, vous pouvez consulter la documentationdu package @azure/enregistreur d’événements.

Trace dynamique

Utilisez l’outil Live Trace à partir du Portail Microsoft Azure pour inspecter le trafic des messages en direct via votre ressource Web PubSub.