Biblioteca cliente de Azure Web PubSub para Python

Nota:

Los detalles sobre los términos usados aquí se describen en el artículo Conceptos clave.

El SDK del lado cliente tiene como objetivo acelerar el flujo de trabajo del desarrollador; más concretamente,

• simplifica la administración de conexiones de cliente
• simplifica el envío de mensajes entre clientes
• reintentos automáticamente después de caídas no deseadas de la conexión de cliente
• entrega mensajes de forma confiable en número y en orden después de recuperarse de caídas de conexión

Como se muestra en el diagrama, los clientes establecen conexiones de WebSocket con el recurso de Web PubSub.

Cómo empezar

Prerrequisitos

• Python 3.8 y versiones posteriores
• Una suscripción de Azure
• Un recurso de Web PubSub

1. Instalar el paquete de azure-messaging-webpubsubclient

pip install azure-messaging-webpubsubclient

2. Conexión con el recurso de Web PubSub

Un cliente usa Client Access URL para conectarse y autenticarse con el servicio, que sigue un patrón de wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Un cliente puede tener varias maneras de obtener .Client Access URL Para este inicio rápido, puede copiar y pegar uno de Azure Portal que se muestra.

Como se muestra en el diagrama, el cliente tiene los permisos para enviar mensajes a un grupo específico denominado 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. Unirse a grupos

Un cliente solo puede recibir mensajes de grupos que se ha unido y debe agregar una devolución de llamada para especificar la lógica al recibir mensajes.

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. Enviar mensajes a un grupo

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

Ejemplos

Adición de devoluciones de llamada para connectedeventos , disconnected y stopped

1. Cuando un cliente se conecta correctamente al recurso de Web PubSub, se desencadena el evento connected.

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

2. Cuando un cliente está desconectado y no puede recuperar la conexión, se desencadena el evento disconnected.

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

3. El evento stopped se desencadena cuando el cliente está desconectado y el cliente deja de intentar volver a conectarse. Esto suele ocurrir después de llamar al client.stop(), o auto_reconnect está deshabilitado o se ha alcanzado un límite especificado para intentar volver a conectarse. Si desea reiniciar el cliente, puede llamar a client.start() en el evento detenido.

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

Un cliente consume mensajes del servidor de aplicaciones o grupos unidos.

Un cliente puede agregar devoluciones de llamada para consumir mensajes del servidor de aplicaciones o grupos. Tenga en cuenta que, para group-message el evento, el cliente solo puede recibir mensajes de grupo que se ha unido.

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

---

Control del error de reincorpación

Cuando un cliente está desconectado y no se puede recuperar, todos los contextos de grupo se limpian en el recurso de Web PubSub. Esto significa que cuando el cliente se vuelve a conectar, debe volver a unirse a grupos. De forma predeterminada, el cliente tiene auto_rejoin_groups opción habilitada.

Sin embargo, debe tener en cuenta las limitaciones de auto_rejoin_groups.

• El cliente solo puede volver a unir grupos a los que originalmente se une el código de cliente no mediante el código del lado servidor.
• Es posible que se produzca un error en las operaciones de "volver a unirse" debido a varios motivos, por ejemplo, el cliente no tiene permiso para unirse a los grupos. En tales casos, debe agregar una devolución de llamada para controlar este error.

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

Operación y reintento

De forma predeterminada, la operación, como client.join_group(), client.leave_group(), client.send_to_group(), client.send_event() tiene tres reintentos. Puede configurar a través de los argumentos de palabra clave. Si se han producido errores en todos los reintentos, se produce un error. Puede seguir intentando si pasa el mismo ack_id que los reintentos anteriores para que el servicio Web PubSub pueda desduplicar la operación.

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

Solución de problemas

Habilitación de registros

Puede establecer la siguiente variable de entorno para obtener los registros de depuración al usar esta biblioteca.

export AZURE_LOG_LEVEL=verbose

Para obtener instrucciones más detalladas sobre cómo habilitar los registros, puede consultar los documentos del paquete de @azure/registrador.

Seguimiento dinámico

Use la herramienta Live Trace de Azure Portal para inspeccionar el tráfico de mensajes en directo por medio del recurso de Web PubSub.