Biblioteca de cliente do Azure Web PubSub para Python

O SDK do lado do cliente visa acelerar o fluxo de trabalho do desenvolvedor; Mais especificamente,

• simplifica o gerenciamento de conexões de clientes
• simplifica o envio de mensagens entre clientes
• Tentativas automáticas após quedas não intencionais da conexão do cliente
• entrega mensagens de forma confiável em número e em ordem após a recuperação de quedas de conexão

Como mostrado no diagrama, seus clientes estabelecem conexões WebSocket com seu recurso Web PubSub.

Como Começar

Pré-requisitos

• Python 3.8+
• Uma assinatura do Azure
• Um recurso Web PubSub

1. Instale o pacote azure-messaging-webpubsubclient

pip install azure-messaging-webpubsubclient

2. Conecte-se com seu recurso Web PubSub

Um cliente usa a Client Access URL para se conectar e autenticar com o serviço, que segue um padrão de wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. Um cliente pode ter algumas maneiras de obter o Client Access URL. Para este início rápido, você pode copiar e colar um do portal do Azure mostrado.

Como mostrado no diagrama, o cliente tem as permissões para enviar mensagens e ingressar em um grupo específico chamado 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. Junte-se a grupos

Um cliente só pode receber mensagens de grupos aos quais aderiu e você precisa adicionar um retorno de chamada para especificar a lógica ao receber mensagens.

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 mensagens para um 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.

Exemplos

Adicionar retornos de chamada para connectede stoppeddisconnected eventos

1. Quando um cliente é conectado com êxito ao recurso Web PubSub, o evento connected é acionado.

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

2. Quando um cliente é desconectado e não consegue recuperar a conexão, o evento disconnected é acionado.

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

3. O stopped evento é acionado quando o cliente é desconectado e o cliente para de tentar se reconectar. Isso geralmente acontece depois que o client.stop() é chamado, ou auto_reconnect está desativado ou um limite especificado para tentar se reconectar foi atingido. Se quiser reiniciar o cliente, você pode chamar client.start() no evento interrompido.

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

Um cliente consome mensagens do servidor de aplicativos ou de grupos ingressados

Um cliente pode adicionar retornos de chamada para consumir mensagens do seu servidor de aplicativos ou grupos. Observe que, para group-message o evento, o cliente só pode receber mensagens de grupo que ele tenha participado.

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

Lidar com falha de reingresso

Quando um cliente é desconectado e não consegue se recuperar, todos os contextos de grupo são limpos no recurso Web PubSub. Isso significa que, quando o cliente se reconecta, ele precisa voltar a participar de grupos. Por padrão, o cliente tem auto_rejoin_groups opção habilitada.

No entanto, você deve estar ciente das limitações do auto_rejoin_groups.

• O cliente só pode voltar a juntar-se a grupos aos quais foi originalmente associado pelo código do cliente, não pelo código do lado do servidor.
• As operações de "reingressar no grupo" podem falhar devido a vários motivos, por exemplo, o cliente não tem permissão para participar dos grupos. Nesses casos, você precisa adicionar um retorno de chamada para lidar com essa falha.

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

Operação e repetição

Por padrão, a operação como client.join_group(), client.leave_group(), client.send_to_group(), client.send_event() tem três tentativas. Você pode configurar através dos argumentos de palavra-chave. Se todas as novas tentativas tiverem falhado, um erro será lançado. Você pode continuar tentando novamente passando na mesma ack_id que as tentativas anteriores para que o serviço Web PubSub possa desduplicar a operação.

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

Solução de problemas

Ativar logs

Você pode definir a seguinte variável de ambiente para obter os logs de depuração ao usar essa biblioteca.

export AZURE_LOG_LEVEL=verbose

Para obter instruções mais detalhadas sobre como habilitar logs, você pode consultar os documentos do pacote @azure/logger.

Rastreio em tempo real

Use a ferramenta Live Trace do portal do Azure para inspecionar o tráfego de mensagens ao vivo por meio de seu recurso Web PubSub.