Biblioteca de clientes do Azure Web PubSub para Python

Observação

Os detalhes sobre os termos usados aqui estão descritos na seção conceitos chave.

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

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

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

Começando

Pré-requisitos

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

1. Instalar o pacote azure-messaging-webpubsubclient

pip install azure-messaging-webpubsubclient

2. Conecte-se ao recurso do Web PubSub

Um cliente usa um 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 no portal do Azure mostrado.

Conforme 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. Unir grupos

Um cliente só pode receber mensagens de grupos que ele ingressou 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 connected, disconnected e stopped eventos

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

   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 falha ao recuperar a conexão, o evento disconnected é disparado.

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

3. O evento stopped é 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á desabilitado ou um limite especificado para tentar se reconectar foi atingido. Se você quiser reiniciar o cliente, poderá chamar client.start() no evento parado.

   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 grupos ingressados

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

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

---

Manipular falha de retardo

Quando um cliente é desconectado e falha na recuperação, todos os contextos de grupo são limpos no recurso do Web PubSub. Isso significa que, quando o cliente se reconecta, ele precisa se juntar novamente aos grupos. Por padrão, o cliente tem auto_rejoin_groups opção habilitada.

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

• O cliente só pode reencontrar grupos ingressados originalmente pelo código do cliente , não pelo código do lado do servidor.
• As operações de "grupo de retorno" podem falhar devido a vários motivos, por exemplo, o cliente não tem permissão para ingressar nos 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 por meio dos argumentos chave-palavra. Se todas as novas tentativas falharem, será gerado um erro. Você pode continuar tentando novamente passando o mesmo ack_id que as tentativas anteriores para que o serviço Web PubSub possa deduplicar a operação.

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

Resolução de problemas

Habilitar logs

Você pode definir a variável de ambiente a seguir 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 examinar os documentos do pacote @azure/agente.

Rastreamento dinâmico

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