Share via

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

  • Artigo

O Azure Web PubSub Service é um serviço gerido pelo Azure que ajuda os desenvolvedores a construir facilmente aplicações web com funcionalidades em tempo real e padrões de publicação-subscrição. Qualquer cenário que exija mensagens de publicação em tempo real entre servidores e clientes ou entre clientes pode utilizar o serviço Azure Web PubSub. As funcionalidades tradicionais em tempo real que muitas vezes requerem sondagens a partir do servidor ou a submissão de pedidos HTTP também podem utilizar o serviço Azure Web PubSub.

Pode utilizar esta biblioteca no lado do servidor de aplicações para gerir as ligações do cliente WebSocket, como mostra o diagrama abaixo:

transbordar

Utilize esta biblioteca para:

  • Envie mensagens para centros e grupos.
  • Envie mensagens para determinados utilizadores e ligações.
  • Organize utilizadores e ligações em grupos.
  • Fechar ligações
  • Conceder, revogar e verificar permissões para uma ligação existente

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

Exclusão de Responsabilidade

O apoio aos pacotes Azure SDK Python para python 2.7 terminou em 01 de janeiro de 2022. Para mais informações e perguntas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691

Introdução

Pré-requisitos

1. Instalar a embalagem

python -m pip install azure-messaging-webpubsubservice

2. Criar e autenticar um WebPubSubServiceClient

Pode autenticar a WebPubSubServiceClientcadeia de ligação de utilização:

>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient

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

Ou utilizando o ponto final 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 Ative Directory:

  1. instalação pipazure-identity

  2. Siga o documento para ativar a autenticação AAD no seu recurso Webpubsub

  3. Código de atualização para utilizar DefaultAzureCredential

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

Conceitos-chave

Ligação

Uma ligação, também conhecida como cliente ou ligação ao cliente, representa uma ligação WebSocket individual ligada ao serviço Web PubSub. Quando conectado com sucesso, um ID de ligação único é atribuído a esta ligação pelo serviço Web PubSub.

Hub

Um hub é um conceito lógico para um conjunto de ligações com o cliente. Normalmente usa um hub para um propósito, por exemplo, um chat hub ou um centro de notificação. Quando uma ligação ao cliente é criada, conecta-se a um hub, e durante a sua vida, pertence a esse centro. Diferentes aplicações podem partilhar um serviço Azure Web PubSub usando diferentes nomes de hub.

Group

Um grupo é um subconjunto de ligações ao centro. Pode adicionar uma ligação ao cliente a um grupo, ou remover a ligação ao cliente do grupo, sempre que quiser. Por exemplo, quando um cliente se junta a uma sala de chat, ou quando um cliente sai da sala de chat, esta sala de chat pode ser considerada um grupo. Um cliente pode juntar-se a vários grupos, e um grupo pode conter vários clientes.

Utilizador

As ligações com o Web PubSub podem pertencer a um utilizador. Um utilizador pode ter múltiplas ligações, por exemplo quando um único utilizador está ligado em vários dispositivos ou em vários separadores de navegador.

Mensagem

Quando o cliente está ligado, pode enviar mensagens para a aplicação a montante, ou receber mensagens da aplicação a montante, através da ligação WebSocket.

Exemplos

Mensagens de transmissão em 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á texto serializado JSON: {"from": "user1", "data": "Hello world"}.

Mensagens de transmissão em formato de texto simples

>>> 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á texto: Hello world.

Mensagens de transmissão 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á texto binário: b'Hello world'.

Resolução de problemas

Registo

Este SDK utiliza a biblioteca de registo padrão Python. Pode configurar a impressão de registo de registos de depuração para o stdout ou para onde 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 permitir a iniciação de registos detalhados para uma única chamada, mesmo quando não esteja ativada para o WebPubSubServiceClient:

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

Os dados de pedido e resposta em http são impressos para stdout com este config de registo.

Passos seguintes

Verifique mais amostras aqui.

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para mais detalhes, visite https://cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Apenas terá de fazer isto uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, veja a Code of Conduct FAQ (FAQ do Código de Conduta) ou envie um e-mail para opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.