Azure Web PubSub-Dienstclientbibliothek für Python – Version 1.0.1

Artikel
04/05/2023

Azure Web PubSub Service ist ein von Azure verwalteter Dienst, der Entwicklern hilft, Webanwendungen mit Echtzeitfunktionen und Publish-Subscribe-Muster zu erstellen. Der Azure Web PubSub-Dienst kann in allen Szenarien verwendet werden, für die Veröffentlichen-Abonnieren-Messaging in Echtzeit zwischen Server und Clients oder zwischen Clients erforderlich ist. Herkömmliche Echtzeitfeatures, die häufig das Abrufen vom Server oder das Übermitteln von HTTP-Anforderungen erfordern, können ebenfalls den Azure Web PubSub-Dienst verwenden.

Sie können diese Bibliothek auf der App-Serverseite verwenden, um die WebSocket-Clientverbindungen zu verwalten, wie in der folgenden Abbildung dargestellt:

Überlauf

Sie können diese Bibliothek für Folgendes verwenden:

Das Versenden von Nachrichten an Hubs und Gruppen.
Das Versenden von Nachrichten an bestimmte Benutzer und Verbindungen.
Das Organisieren von Benutzern und Verbindungen in Gruppen.
Das Schließen von Verbindungen
Das Erteilen, Widerrufen und Prüfen von Berechtigungen für eine vorhandene Verbindung

Quellcode | Paket (Pypi) | API-Referenzdokumentation | Produktdokumentation

Haftungsausschluss

Die Unterstützung von Python-Paketen für Das Azure SDK für Python 2.7 wurde am 01. Januar 2022 eingestellt. Weitere Informationen und Antworten finden Sie unter https://github.com/Azure/azure-sdk-for-python/issues/20691.

Erste Schritte

Voraussetzungen

Für die Verwendung dieses Pakets ist Python 3.6 oder höher erforderlich.
Sie benötigen ein Azure-Abonnement und eine Azure WebPubSub-Service-Instanz, um dieses Paket zu nutzen.
Eine vorhandene Azure Web PubSub-Dienstinstanz.

1. Installieren Sie das Paket

python -m pip install azure-messaging-webpubsubservice

2. Erstellen und Authentifizieren Sie einen WebPubSubServiceClient

Sie können die WebPubSubServiceClient mittels Verbindungszeichenfolge authentifizieren:

>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient

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

Oder Sie verwenden den Endpunkt des Dienstes und den Zugangsschlüssel:

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

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

Oder Sie verwenden Azure Active Directory:

pip install azure-identity
Folgen Sie dem Dokument, um die AAD-Authentifizierung für Ihre Webpubsub-Ressource zu aktivieren

Code aktualisieren, um DefaultAzureCredential zu verwenden

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

Wichtige Begriffe

Verbindung

Eine Verbindung (auch Client oder Clientverbindung genannt) stellt eine einzelne WebSocket-Verbindung mit dem Web PubSub-Dienst dar. Wenn die Verbindung erfolgreich hergestellt wurde, wird ihr vom Web PubSub-Dienst eine eindeutige Verbindungs-ID zugewiesen.

Hub

Ein Hub ist ein logisches Konzept für eine Gruppe von Clientverbindungen. In der Regel wird jeweils ein einzelner Hub für einen einzelnen Zweck verwendet – beispielsweise ein Chathub oder ein Benachrichtigungshub. Eine Clientverbindung wird mit einem Hub hergestellt und gehört während ihrer Lebensdauer zu diesem Hub. Von verschiedenen Anwendungen können unterschiedliche Hubnamen verwendet werden, um gemeinsam einen einzelnen Azure Web PubSub-Dienst zu nutzen.

Group

Eine Gruppe ist eine Teilmenge der Verbindungen mit dem Hub. Sie können einer Gruppe eine Clientverbindung hinzufügen und sie jederzeit wieder aus der Gruppe entfernen. Beispiel: Wenn ein Client einem Chatroom beitritt oder wenn ein Client den Chatroom verlässt, kann dieser Chatroom als Gruppe betrachtet werden. Ein Client kann mehreren Gruppen beitreten, und eine Gruppe kann mehrere Clients enthalten.

Benutzer

Verbindungen mit Web PubSub können zu einem einzelnen Benutzer gehören. Ein Benutzer kann über mehrere Verbindungen verfügen, etwa, wenn ein einzelner Benutzer über mehrere Geräte oder mehrere Browsertabs verbunden ist.

`Message`

Wenn der Client verbunden ist, kann er Nachrichten an die Upstreamanwendung senden oder Nachrichten von der Upstreamanwendung über die WebSocket-Verbindung empfangen.

Beispiele

Senden von Nachrichten im JSON-Format

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

Der WebSocket-Client empfängt JSON serialisierten Text: {"from": "user1", "data": "Hello world"}.

Senden von Nachrichten im Klartextformat

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

Der WebSocket-Client empfängt Text: Hello world.

Senden von Nachrichten im Binärformat

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

Der WebSocket-Client empfängt binären Text: b'Hello world'.

Problembehandlung

Protokollierung

Dieses SDK verwendet die Python-Standardprotokollierungsbibliothek. Sie können die Protokollierung so konfigurieren, dass Debugging-Informationen auf stdout oder an einem beliebigen Ort ausgegeben werden.

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)

In ähnlicher Weise kann logging_enable die detaillierte Protokollierung für einen einzelnen Aufruf aktivieren, auch wenn sie für den WebPubSubServiceClient nicht aktiviert ist:

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

HTTP-Anforderungs- und Antwortdetails werden bei dieser Protokollierungskonfiguration in stdout gedruckt.

Nächste Schritte

Prüfen Sie mehr Beispiele hier.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Ausführliche Informationen finden Sie unter https://cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den FAQ zum Verhaltenskodex, oder wenden Sie sich mit weiteren Fragen oder Kommentaren an opencode@microsoft.com.

Freigeben über