Azure Web PubSub-tjänstklientbibliotek för Python – version 1.0.1

Artikel
04/05/2023

Azure Web PubSub Service är en Azure-hanterad tjänst som hjälper utvecklare att enkelt skapa webbprogram med realtidsfunktioner och mönster för publicering och prenumeration. Alla scenarion som kräver meddelanden i realtid om publicering och prenumeration mellan server och klienter eller mellan klienter kan använda Azure Web PubSub-tjänsten. Traditionella realtidsfunktioner som ofta kräver avsökning från servern eller skicka HTTP-begäranden kan också använda Azure Web PubSub-tjänsten.

Du kan använda det här biblioteket på appserversidan för att hantera WebSocket-klientanslutningarna, som du ser i diagrammet nedan:

Overflow

Använd det här biblioteket för att:

Skicka meddelanden till hubbar och grupper.
Skicka meddelanden till vissa användare och anslutningar.
Organisera användare och anslutningar i grupper.
Stäng anslutningar
Bevilja, återkalla och kontrollera behörigheter för en befintlig anslutning

Källkod | Paket (Pypi) | API-referensdokumentation | Produktdokumentation

Friskrivning

Stöd för Azure SDK Python-paket för Python 2.7 har upphört den 1 januari 2022. Mer information och frågor finns i https://github.com/Azure/azure-sdk-for-python/issues/20691

Komma igång

Förutsättningar

Python 3.6 eller senare krävs för att använda det här paketet.
Du behöver en Azure-prenumeration och en Azure WebPubSub-tjänstinstans för att använda det här paketet.
En befintlig Azure Web PubSub-tjänstinstans.

1. Installera paketet

python -m pip install azure-messaging-webpubsubservice

2. Skapa och autentisera en WebPubSubServiceClient

Du kan autentisera med hjälp av anslutningssträngenWebPubSubServiceClient:

>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient

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

Eller använda tjänstslutpunkten och åtkomstnyckeln:

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

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

Eller använda Azure Active Directory:

pip install azure-identity
Följ dokumentet för att aktivera AAD-autentisering på din Webpubsub-resurs

Uppdatera kod för att använda DefaultAzureCredential

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

Viktiga begrepp

Anslutning

En anslutning, även kallad klient- eller klientanslutning, representerar en enskild WebSocket-anslutning som är ansluten till Web PubSub-tjänsten. När anslutningen är klar tilldelas en unik anslutnings-ID till den här anslutningen av Web PubSub-tjänsten.

Hubb

En hubb är ett logiskt begrepp för en uppsättning klientanslutningar. Vanligtvis använder du en hubb för ett syfte, till exempel en chatthubb eller en meddelandehubb. När en klientanslutning skapas ansluter den till en hubb, och under dess livslängd tillhör den hubben. Olika program kan dela en Azure Web PubSub-tjänst med hjälp av olika hubbnamn.

Group

En grupp är en delmängd av anslutningarna till hubben. Du kan lägga till en klientanslutning till en grupp eller ta bort klientanslutningen från gruppen när du vill. När en klient till exempel ansluter till ett chattrum, eller när en klient lämnar chattrummet, kan det här chattrummet betraktas som en grupp. En klient kan ansluta till flera grupper och en grupp kan innehålla flera klienter.

Användare

Anslutningar till Web PubSub kan tillhöra en användare. En användare kan ha flera anslutningar, till exempel när en enskild användare är ansluten över flera enheter eller flera webbläsarflikar.

Meddelande

När klienten är ansluten kan den skicka meddelanden till det överordnade programmet eller ta emot meddelanden från det överordnade programmet via WebSocket-anslutningen.

Exempel

Sända meddelanden i 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'
    })

WebSocket-klienten får JSON-serialiserad text: {"from": "user1", "data": "Hello world"}.

Sända meddelanden i oformaterad textformat

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

WebSocket-klienten får text: Hello world.

Sända meddelanden i binärt format

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

WebSocket-klienten får binär text: b'Hello world'.

Felsökning

Loggning

Den här SDK:t använder Pythons standardloggningsbibliotek. Du kan konfigurera loggning av felsökningsinformation till stdout eller var du vill.

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 På samma sätt kan du aktivera detaljerad loggning för ett enda anrop, även om det inte är aktiverat för WebPubSubServiceClient:

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

Http-begäran och svarsinformation skrivs ut till stdout med den här loggningskonfigurationen.

Nästa steg

Kontrollera fler exempel här.

Bidra

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns på https://cla.microsoft.com.

När du skickar en pull-förfrågan avgör en CLA-robot automatiskt om du måste tillhandahålla ett licensavtal för bidrag med lämplig PR (t.ex. etikett eller kommentar). Följ bara robotens anvisningar. Du behöver bara göra detta en gång för alla repor som använder vårt licensavtal för bidrag.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Du hittar mer information i Vanliga frågor om uppförandekod eller kontakta opencode@microsoft.com för ytterligare frågor eller kommentarer.

Dela via