Biblioteka klienta usługi Azure Web PubSub dla języka Python — wersja 1.0.1
Azure Web PubSub Service to usługa zarządzana przez platformę Azure, która ułatwia deweloperom łatwe tworzenie aplikacji internetowych za pomocą funkcji w czasie rzeczywistym i wzorca publikowania i subskrybowania. Każdy scenariusz, który wymaga komunikatów publikowania i subskrybowania w czasie rzeczywistym między serwerem a klientami lub między klientami, może korzystać z usługi Azure Web PubSub. Tradycyjne funkcje czasu rzeczywistego, które często wymagają sondowania z serwera lub przesyłania żądań HTTP, mogą również używać usługi Azure Web PubSub.
Możesz użyć tej biblioteki po stronie serwera aplikacji do zarządzania połączeniami klientów protokołu WebSocket, jak pokazano na poniższym diagramie:
Użyj tej biblioteki, aby:
- Wysyłanie komunikatów do centrów i grup.
- Wysyłaj komunikaty do określonych użytkowników i połączeń.
- Organizowanie użytkowników i połączeń w grupy.
- Zamykanie połączeń
- Udzielanie, odwoływanie i sprawdzanie uprawnień dla istniejącego połączenia
Kod | źródłowy Pakiet (Pypi) | Dokumentacja referencyjna interfejsu | API Dokumentacja produktu
Zrzeczenie odpowiedzialności
Obsługa pakietów języka Python dla zestawu Azure SDK dla języka Python 2.7 zakończyła się 1 stycznia 2022 r. Aby uzyskać więcej informacji i pytań, zapoznaj się z artykułem https://github.com/Azure/azure-sdk-for-python/issues/20691
Wprowadzenie
Wymagania wstępne
- Do korzystania z tego pakietu jest wymagany język Python 3.6 lub nowszy.
- Do korzystania z tego pakietu potrzebna jest subskrypcja platformy Azure i wystąpienie usługi Azure WebPubSub .
- Istniejące wystąpienie usługi Azure Web PubSub.
1. Zainstaluj pakiet
python -m pip install azure-messaging-webpubsubservice
2. Tworzenie i uwierzytelnianie elementu WebPubSubServiceClient
Możesz uwierzytelnić się WebPubSubServiceClient przy użyciu parametrów połączenia:
>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient
>>> service = WebPubSubServiceClient.from_connection_string(connection_string='<connection_string>', hub='hub')
Możesz też użyć punktu końcowego usługi i klucza dostępu:
>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient
>>> from azure.core.credentials import AzureKeyCredential
>>> service = WebPubSubServiceClient(endpoint='<endpoint>', hub='hub', credential=AzureKeyCredential("<access_key>"))
Lub przy użyciu usługi Azure Active Directory:
Postępuj zgodnie z dokumentem, aby włączyć uwierzytelnianie usługi AAD w zasobie Webpubsub
Aktualizowanie kodu w celu użycia elementu DefaultAzureCredential
>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient >>> from azure.identity import DefaultAzureCredential >>> service = WebPubSubServiceClient(endpoint='<endpoint>', hub='hub', credential=DefaultAzureCredential())
Kluczowe pojęcia
Połączenie
Połączenie, znane również jako klient lub połączenie klienta, reprezentuje pojedyncze połączenie Protokołu WebSocket połączone z usługą Web PubSub. Po pomyślnym nawiązaniu połączenia unikatowy identyfikator połączenia jest przypisywany do tego połączenia przez usługę Web PubSub.
Koncentrator
Koncentrator jest logicznym pojęciem dla zestawu połączeń klienckich. Zwykle używasz jednego centrum do jednego celu, na przykład centrum czatów lub centrum powiadomień. Po utworzeniu połączenia klienta łączy się z koncentratorem i w okresie jego istnienia należy do tego centrum. Różne aplikacje mogą udostępniać jedną usługę Azure Web PubSub przy użyciu różnych nazw centrów.
Group (Grupa)
Grupa jest podzbiorem połączeń z koncentratorem. Możesz dodać połączenie klienta do grupy lub usunąć połączenie klienta z grupy w dowolnym momencie. Na przykład gdy klient dołącza do pokoju rozmów lub gdy klient opuszcza pokój rozmów, ten pokój rozmów może być uważany za grupę. Klient może dołączyć do wielu grup, a grupa może zawierać wielu klientów.
Użytkownik
Połączenia z usługą Web PubSub mogą należeć do jednego użytkownika. Użytkownik może mieć wiele połączeń, na przykład gdy jeden użytkownik jest połączony na wielu urządzeniach lub na wielu kartach przeglądarki.
Komunikat
Po nawiązaniu połączenia klient może wysyłać komunikaty do aplikacji nadrzędnej lub odbierać komunikaty z aplikacji nadrzędnej za pośrednictwem połączenia protokołu WebSocket.
Przykłady
Emisja komunikatów w formacie 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 protokołu WebSocket otrzyma tekst serializowany w formacie JSON: {"from": "user1", "data": "Hello world"}.
Rozgłaszaj wiadomości w formacie zwykłego tekstu
>>> 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 protokołu WebSocket otrzyma tekst: Hello world.
Emisja komunikatów w formacie binarnym
>>> 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 protokołu WebSocket otrzyma tekst binarny: b'Hello world'.
Rozwiązywanie problemów
Rejestrowanie
Ten zestaw SDK używa standardowej biblioteki rejestrowania języka Python. Możesz skonfigurować rejestrowanie wyświetlać informacje debugowania do stdout lub w dowolnym miejscu.
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 Podobnie można włączyć szczegółowe rejestrowanie dla pojedynczego wywołania, nawet jeśli nie jest włączone dla elementu WebPubSubServiceClient:
result = service.send_to_all(..., logging_enable=True)
Szczegóły żądania HTTP i odpowiedzi są drukowane w pliku stdout z tą konfiguracją rejestrowania.
Następne kroki
Sprawdź więcej przykładów tutaj.
Współtworzenie
W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź stronę https://cla.microsoft.com.
Po przesłaniu żądania ściągnięcia robot CLA automatycznie określi, czy musisz przekazać umowę CLA, i doda odpowiednie informacje do tego żądania (na przykład etykietę czy komentarz). Po prostu postępuj zgodnie z instrukcjami robota. Wystarczy zrobić to raz dla wszystkich repozytoriów, w przypadku których jest używana nasza umowa CLA.
W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz artykuł Code of Conduct FAQ (Często zadawane pytania dotyczące kodeksu postępowania). Jeśli będziesz mieć jeszcze jakieś pytania lub komentarze, wyślij wiadomość e-mail na adres opencode@microsoft.com.
Azure SDK for Python