Biblioteca de clientes do serviço Azure Web PubSub para Python – versão 1.0.1

Artigo
04/05/2023

O serviço Azure Web PubSub é um serviço gerenciado do Azure que ajuda os desenvolvedores a criar aplicativos Web facilmente com recursos em tempo real e padrão de publicação/assinatura. Qualquer cenário que exija mensagens de publicação/assinatura em tempo real entre o servidor e os clientes ou entre clientes pode usar o serviço Azure Web PubSub. Os recursos tradicionais em tempo real que geralmente exigem a sondagem do servidor ou o envio de solicitações HTTP também podem usar o serviço Azure Web PubSub.

Você pode usar essa biblioteca no lado do servidor de aplicativos para gerenciar as conexões de cliente WebSocket, conforme mostrado no diagrama abaixo:

Estouro

Use essa biblioteca para:

Enviar mensagens para hubs e grupos.
Enviar mensagens para usuários e conexões específicos.
Organizar usuários e conexões em grupos.
Fechar conexões
Conceder, revogar e verificar permissões para uma conexão existente

Código-fonte | Pacote (Pypi) | Documentação de referência de API | Documentação do produto

Aviso de isenção de responsabilidade

O suporte a pacotes python do SDK do Azure para Python 2.7 terminou em 01 de janeiro de 2022. Para obter mais informações e tirar dúvidas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691

Introdução

Pré-requisitos

É necessário Python 3.6 ou posterior para usar esse pacote.
Você precisará de uma assinatura do Azure e de uma instância de serviço do Azure Web PubSub para usar esse pacote.
Uma instância de serviço do Azure Web PubSub existente.

1. Instalar o pacote

python -m pip install azure-messaging-webpubsubservice

2. Criar e autenticar um WebPubSubServiceClient

Você pode autenticar WebPubSubServiceClient usando a cadeia de conexão:

>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient

>>> service = WebPubSubServiceClient.from_connection_string(connection_string='<connection_string>', hub='hub')

Ou usando o ponto de extremidade de serviço e a chave de acesso:

>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient
>>> from azure.core.credentials import AzureKeyCredential

>>> service = WebPubSubServiceClient(endpoint='<endpoint>', hub='hub', credential=AzureKeyCredential("<access_key>"))

Ou usando o Azure Active Directory:

instalação pip azure-identity
Siga o documento para habilitar autenticação AAD no recurso Webpubsub

Atualizar o código para usar DefaultAzureCredential

>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient
>>> from azure.identity import DefaultAzureCredential
>>> service = WebPubSubServiceClient(endpoint='<endpoint>', hub='hub', credential=DefaultAzureCredential())

Principais conceitos

Conexão

Uma conexão, também conhecida como cliente ou conexão cliente, representa uma conexão do WebSocket individual ao serviço Web PubSub. Quando conectado com sucesso, uma ID de conexão exclusiva é atribuída a essa conexão pelo serviço Web PubSub.

Hub

Um hub é um conceito lógico para um conjunto de conexões de cliente. Normalmente, você usa um hub para cada finalidade específica, por exemplo, o hub de chat ou o hub de notificações. Quando uma conexão de cliente é criada, ela se conecta a um hub e, durante seu tempo de vida, pertence a esse hub. Aplicativos diferentes podem compartilhar o mesmo serviço Azure Web PubSub usando nomes de hub diferentes.

Grupo

Um grupo é um subconjunto de conexões com o hub. Você pode adicionar uma conexão de cliente a um grupo ou removê-la do grupo sempre que desejar. Por exemplo, quando um cliente entra em uma sala de chat ou quando um cliente sai da sala de chat, essa sala de chat pode ser considerada um grupo. Um cliente pode ingressar em vários grupos e um grupo pode conter vários clientes.

Usuário

As conexões com o Web PubSub podem pertencer a um usuário. Um usuário pode ter várias conexões, por exemplo, quando apenas um usuário está conectado a vários dispositivos ou a várias guias do navegador.

Mensagem

Quando o cliente está conectado, ele pode enviar mensagens ao aplicativo upstream ou receber mensagens do aplicativo upstream por meio da conexão do WebSocket.

Exemplos

Transmitir mensagens no formato JSON

>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient

>>> service = WebPubSubServiceClient.from_connection_string('<connection_string>', hub='hub1')
>>> service.send_to_all(message = {
        'from': 'user1',
        'data': 'Hello world'
    })

O cliente WebSocket receberá um texto serializado JSON: {"from": "user1", "data": "Hello world"}.

Transmitir mensagens em formato de texto sem formatação

>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient
>>> service = WebPubSubServiceClient.from_connection_string('<connection_string>', hub='hub1')
>>> service.send_to_all(message = 'Hello world', content_type='text/plain')

O cliente WebSocket receberá um texto: Hello world.

Transmitir mensagens em formato binário

>>> import io
>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient
>>> service = WebPubSubServiceClient.from_connection_string('<connection_string>', hub='hub')
>>> service.send_to_all(message=io.StringIO('Hello World'), content_type='application/octet-stream')

O cliente WebSocket receberá um texto binário: b'Hello world'.

Solução de problemas

Log

Esse SDK usa a biblioteca de log padrão do Python. Você pode configurar o log para imprimir informações de depuração no stdout ou em qualquer lugar que você quiser.

import sys
import logging
from azure.identity import DefaultAzureCredential
>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

endpoint = "<endpoint>"
credential = DefaultAzureCredential()

# This WebPubSubServiceClient will log detailed information about its HTTP sessions, at DEBUG level
service = WebPubSubServiceClient(endpoint=endpoint, hub='hub', credential=credential, logging_enable=True)

Da mesma forma, logging_enable pode habilitar o log detalhado para uma chamada individual, mesmo quando ela não está habilitada para o WebPubSubServiceClient:

result = service.send_to_all(..., logging_enable=True)

Os detalhes de solicitação e resposta HTTP são impressos em stdout com essa configuração de log.

Próximas etapas

Verifique mais exemplos aqui.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para saber mais, confira as Perguntas frequentes sobre o Código de Conduta ou contate o opencode@microsoft.com caso tenha outras dúvidas ou comentários.

Compartilhar via