Azure Web PubSub-serviceclientbibliotheek voor Python - versie 1.0.1

Artikel
04/05/2023

Azure Web PubSub Service is een door Azure beheerde service waarmee ontwikkelaars eenvoudig webtoepassingen kunnen bouwen met realtime-functies en een patroon voor publiceren/abonneren. Elk scenario waarvoor realtime publiceren-abonneren tussen server en clients of tussen clients is vereist, kan de Azure Web PubSub-service gebruiken. Traditionele realtime-functies die vaak polling van de server vereisen of HTTP-aanvragen indienen, kunnen ook gebruikmaken van de Azure Web PubSub-service.

U kunt deze bibliotheek in de app-server gebruiken om de WebSocket-clientverbindingen te beheren, zoals wordt weergegeven in het onderstaande diagram:

Overloop

Gebruik deze bibliotheek voor het volgende:

Berichten verzenden naar hubs en groepen.
Berichten verzenden naar bepaalde gebruikers en verbindingen.
Gebruikers en verbindingen in groepen indelen.
Verbindingen sluiten
Machtigingen verlenen, intrekken en controleren voor een bestaande verbinding

Broncode | Pakket (Pypi) | API-referentiedocumentatie | Productdocumentatie

Disclaimer

Ondersteuning voor Azure SDK Python-pakketten voor Python 2.7 is beëindigd op 1 januari 2022. Voor meer informatie en vragen raadpleegt u https://github.com/Azure/azure-sdk-for-python/issues/20691

Aan de slag

Vereisten

Python 3.6 of hoger is vereist voor het gebruik van dit pakket.
U hebt een Azure-abonnement en een Azure WebPubSub-service-exemplaar nodig om dit pakket te kunnen gebruiken.
Een bestaand exemplaar van de Azure Web PubSub-service.

1. Het pakket installeren

python -m pip install azure-messaging-webpubsubservice

2. Een WebPubSubServiceClient maken en verifiëren

U kunt de WebPubSubServiceClient verifiëren met behulp van connection string:

>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient

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

Of gebruik het service-eindpunt en de toegangssleutel:

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

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

Of gebruik Azure Active Directory:

pip installeren azure-identity
Volg het document om AAD-verificatie in te schakelen voor uw Webpubsub-resource

Code bijwerken voor gebruik van DefaultAzureCredential

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

Belangrijkste concepten

Verbinding

Een verbinding, ook wel een client- of clientverbinding genoemd, vertegenwoordigt een afzonderlijke WebSocket-verbinding die is verbonden met de Web PubSub-service. Wanneer de verbinding is geslaagd, wordt een unieke verbindings-id toegewezen aan deze verbinding door de Web PubSub-service.

Hub

Een hub is een logisch concept voor een set clientverbindingen. Meestal gebruikt u één hub voor één doel, bijvoorbeeld een chathub of een Notification Hub. Wanneer een clientverbinding wordt gemaakt, maakt deze verbinding met een hub en tijdens de levensduur behoort deze tot die hub. Verschillende toepassingen kunnen één Azure Web PubSub-service delen met behulp van verschillende hubnamen.

Groep

Een groep is een subset van verbindingen met de hub. U kunt op elk gewenst moment een clientverbinding toevoegen aan een groep of de clientverbinding uit de groep verwijderen. Wanneer een client bijvoorbeeld deelneemt aan een chatruimte of wanneer een client de chatruimte verlaat, kan deze chatruimte worden beschouwd als een groep. Een client kan lid worden van meerdere groepen en een groep kan meerdere clients bevatten.

Gebruiker

Verbindingen met Web PubSub kunnen tot één gebruiker behoren. Een gebruiker kan meerdere verbindingen hebben, bijvoorbeeld wanneer één gebruiker is verbonden op meerdere apparaten of meerdere browsertabbladen.

Bericht

Wanneer de client is verbonden, kan deze berichten verzenden naar de upstream-toepassing of berichten ontvangen van de upstream-toepassing via de WebSocket-verbinding.

Voorbeelden

Berichten uitzenden in JSON-indeling

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

De WebSocket-client ontvangt geserialiseerde JSON-tekst: {"from": "user1", "data": "Hello world"}.

Berichten uitzenden in tekst zonder opmaak

>>> 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')

De WebSocket-client ontvangt de volgende tekst: Hello world.

Berichten uitzenden in binaire indeling

>>> 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')

De WebSocket-client ontvangt binaire tekst: b'Hello world'.

Problemen oplossen

Logboekregistratie

Deze SDK maakt gebruik van de python-standaardbibliotheek voor logboekregistratie. U kunt configureren dat de foutopsporingsgegevens in logboekregistratie worden afgedrukt naar de stdout of waar u maar wilt.

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)

logging_enable Op dezelfde manier kan gedetailleerde logboekregistratie voor één aanroep worden ingeschakeld, zelfs wanneer deze niet is ingeschakeld voor de WebPubSubServiceClient:

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

Http-aanvraag- en antwoordgegevens worden afgedrukt naar stdout met deze logboekconfiguratie.

Volgende stappen

Bekijk hier meer voorbeelden.

Bijdragen

Wij verwelkomen bijdragen en suggesties voor dit project. Voor de meeste bijdragen moet u instemmen met een licentieovereenkomst voor bijdragers (CLA: Contributor License Agreement) waarin u verklaart dat u gerechtigd bent ons het recht te geven uw bijdrage te gebruiken, en dat u dit ook doet. Ga naar https://cla.microsoft.com voor meer informatie.

Wanneer u een pull-aanvraag indient, wordt met een CLA-bot automatisch bepaald of u een CLA moet verschaffen en wordt de pull-aanvraag dienovereenkomstig opgemaakt (bijvoorbeeld met een label of commentaar). Volg gewoon de instructies van de bot. U hoeft dit maar eenmaal te doen voor alle repo's waar gebruik wordt gemaakt van onze CLA.

Op dit project is de Microsoft Open Source Code of Conduct (Microsoft Open Source-gedragscode) van toepassing. Raadpleeg de Veelgestelde vragen over de gedragscode voor meer informatie of neem contact op met opencode@microsoft.com als u meer vragen of opmerkingen hebt.

Delen via