Libreria client PubSub di Azure per Python

L'SDK lato client mira a velocizzare il flusso di lavoro dello sviluppatore; più in particolare,

• semplifica la gestione delle connessioni client
• semplifica l'invio di messaggi tra i client
• tentativi automatici dopo l'eliminazione imprevista della connessione client
• recapita in modo affidabile i messaggi in numero e in ordine dopo il ripristino dall'eliminazione della connessione

Come illustrato nel diagramma, i client stabiliscono connessioni WebSocket con la risorsa Web PubSub.

Come iniziare

Prerequisiti

• Python 3.8+
• Una sottoscrizione di Azure
• Una risorsa PubSub Web

1. Installare il pacchetto azure-messaging-webpubsubclient

pip install azure-messaging-webpubsubclient

2. Connettersi con la risorsa PubSub Web

Un client usa un Client Access URL oggetto per connettersi ed eseguire l'autenticazione con il servizio, che segue un modello di wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Un client può avere alcuni modi per ottenere .Client Access URL Per questa guida introduttiva, è possibile copiare e incollare uno dal portale di Azure visualizzato.

Come illustrato nel diagramma, il client dispone delle autorizzazioni per l'invio di messaggi a e l'aggiunta a un gruppo specifico denominato 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. Partecipare ai gruppi

Un client può ricevere messaggi solo dai gruppi aggiunti ed è necessario aggiungere un callback per specificare la logica durante la ricezione di messaggi.

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. Inviare messaggi a un gruppo

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

Esempi

Aggiungere callback per connectedgli eventi e stoppeddisconnected

1. Quando un client è connesso correttamente alla risorsa Web PubSub, viene attivato l'evento connected.

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

2. Quando un client viene disconnesso e non riesce a recuperare la connessione, viene attivato l'evento disconnected.

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

3. L'evento stopped viene attivato quando il client viene disconnesso e il client smette di tentare di riconnettersi. Ciò si verifica in genere dopo la chiamata del client.stop() oppure auto_reconnect è disabilitato o viene raggiunto un limite specificato per tentare di riconnettersi. Se si desidera riavviare il client, è possibile chiamare client.start() nell'evento arrestato.

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

Un client utilizza messaggi dal server applicazioni o dai gruppi aggiunti

Un client può aggiungere callback per utilizzare messaggi dal server applicazioni o dai gruppi. Si noti che per group-message l'evento il client può ricevere solo messaggi di gruppo aggiunti.

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

Gestire l'errore di ricongiuzione

Quando un client viene disconnesso e non riesce a eseguire il ripristino, tutti i contesti di gruppo vengono puliti nella risorsa Web PubSub. Ciò significa che quando il client si riconnette, deve riconnettersi ai gruppi. Per impostazione predefinita, il client ha auto_rejoin_groups opzione abilitata.

Tuttavia, è necessario essere consapevoli delle limitazioni di auto_rejoin_groups.

• Il client può unire nuovamente i gruppi aggiunti originariamente dal codice client non dal codice lato server.
• Le operazioni di "ricongiurzione del gruppo" potrebbero non riuscire a causa di vari motivi, ad esempio il client non dispone dell'autorizzazione per l'aggiunta ai gruppi. In questi casi, è necessario aggiungere un callback per gestire questo errore.

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

Operazione e ripetizione dei tentativi

Per impostazione predefinita, l'operazione come client.join_group(), client.leave_group(), client.send_to_group(), client.send_event() ha tre tentativi. È possibile configurare tramite gli argomenti chiave-parola. Se tutti i tentativi non sono riusciti, viene generato un errore. È possibile continuare a ripetere i tentativi passando la stessa ack_id dei tentativi precedenti in modo che il servizio Web PubSub possa deduplicare l'operazione.

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

Risoluzione dei problemi

Abilitare i log

È possibile impostare la variabile di ambiente seguente per ottenere i log di debug quando si usa questa libreria.

export AZURE_LOG_LEVEL=verbose

Per istruzioni più dettagliate su come abilitare i log, è possibile esaminare la documentazione del pacchetto @azure/logger.

Traccia in tempo reale

Usare lo strumento Live Trace da portale di Azure per esaminare il traffico dei messaggi live attraverso la risorsa Web PubSub.