Klientská knihovna služby Azure Web PubSub pro Python – verze 1.0.1

Článek
04/05/2023

Azure Web PubSub Service je spravovaná služba Azure, která vývojářům pomáhá snadno vytvářet webové aplikace s funkcemi v reálném čase a modelem publikování a odběru. Každý scénář, který vyžaduje zasílání zpráv o publikování a odběru v reálném čase mezi serverem a klienty nebo mezi klienty, může použít službu Azure Web PubSub. Tradiční funkce v reálném čase, které často vyžadují dotazování ze serveru nebo odesílání požadavků HTTP, můžou také používat službu Azure Web PubSub.

Tuto knihovnu můžete použít na straně aplikačního serveru ke správě připojení klientů WebSocket, jak je znázorněno na následujícím diagramu:

Přetečení

Pomocí této knihovny můžete:

Odesílání zpráv do center a skupin
Odesílání zpráv konkrétním uživatelům a připojením
Uspořádejte uživatele a připojení do skupin.
Zavření připojení
Udělení, odvolání a kontrola oprávnění pro existující připojení

Zdrojový kód | Balíček (Pypi) | Referenční dokumentace k | rozhraní API Dokumentace k produktu

Právní omezení

Podpora balíčků Azure SDK Python pro Python 2.7 skončila 1. ledna 2022. Další informace a dotazy najdete na https://github.com/Azure/azure-sdk-for-python/issues/20691

Začínáme

Požadavky

K použití tohoto balíčku se vyžaduje Python 3.6 nebo novější.
K použití tohoto balíčku potřebujete předplatné Azure a instanci služby Azure WebPubSub .
Existující instance služby Azure Web PubSub

1. Nainstalujte balíček.

python -m pip install azure-messaging-webpubsubservice

2. Vytvoření a ověření WebPubSubServiceClient

Můžete ověřit pomocí připojovacíhoWebPubSubServiceClient řetězce:

>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient

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

Nebo pomocí koncového bodu služby a přístupového klíče:

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

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

Nebo pomocí Azure Active Directory:

pip install azure-identity
Postupujte podle dokumentu a povolte ověřování AAD u prostředku Webpubsub.

Aktualizace kódu tak, aby používal DefaultAzureCredential

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

Klíčové koncepty

Připojení

Připojení, označované také jako klient nebo připojení klienta, představuje individuální připojení WebSocket připojené ke službě Web PubSub. Po úspěšném připojení přiřadí služba Web PubSub tomuto připojení jedinečné ID připojení.

Rozbočovač

Centrum je logický koncept pro sadu klientských připojení. Obvykle používáte jedno centrum pro jeden účel, například centrum chatu nebo centrum oznámení. Když se vytvoří připojení klienta, připojí se k centru a během své životnosti patří do tohoto centra. Různé aplikace můžou sdílet jednu službu Azure Web PubSub pomocí různých názvů rozbočovačů.

Group (Skupina)

Skupina je podmnožinou připojení k centru. Kdykoli budete chtít, můžete přidat připojení klienta ke skupině nebo ho ze skupiny odebrat. Například když se klient připojí k chatovací místnosti nebo když klient opustí chatovací místnost, lze tuto chatovací místnost považovat za skupinu. Klient se může připojit k více skupinám a skupina může obsahovat více klientů.

Uživatel

Připojení k Web PubSub můžou patřit jednomu uživateli. Uživatel může mít více připojení, například když je jeden uživatel připojený z více zařízení nebo více karet prohlížeče.

Zpráva

Když je klient připojený, může odesílat zprávy do nadřazené aplikace nebo přijímat zprávy z nadřazené aplikace prostřednictvím připojení WebSocket.

Příklady

Vysílání zpráv ve formátu 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'
    })

Klient WebSocket obdrží serializovaný text JSON: {"from": "user1", "data": "Hello world"}.

Vysílání zpráv ve formátu prostého textu

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

Klient WebSocket obdrží text: Hello world.

Vysílání zpráv v binárním formátu

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

Klient WebSocket obdrží binární text: b'Hello world'.

Poradce při potížích

protokolování

Tato sada SDK používá standardní knihovnu protokolování Pythonu. Můžete nakonfigurovat protokolování tisku informací o ladění pro stdout nebo kdekoli chcete.

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)

Podobně logging_enable může povolit podrobné protokolování pro jedno volání, i když není povolené pro WebPubSubServiceClient:

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

Podrobnosti o požadavku HTTP a odpovědi se vytisknou do stdout s touto konfigurací protokolování.

Další kroky

Další ukázky najdete tady.

Přispívání

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete tady: https://cla.microsoft.com

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pro všechna úložiště používající naši smlouvu CLA to stačí udělat jenom jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování. V případě jakýchkoli dotazů nebo připomínek kontaktujte opencode@microsoft.com.

Sdílet prostřednictvím