Udostępnij za pośrednictwem


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:

Przepełnienie

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

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:

  1. instalacja narzędzia pipazure-identity

  2. Postępuj zgodnie z dokumentem, aby włączyć uwierzytelnianie usługi AAD w zasobie Webpubsub

  3. 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.