Клиентская библиотека службы Azure Web PubSub для Python — версия 1.0.1

Статья
04/05/2023

Служба Azure Web PubSub — это управляемая Azure служба, которая помогает разработчикам легко создавать веб-приложения с функциями реального времени и шаблоном публикации и подписки. Любой сценарий, требующий обмена сообщениями между сервером и клиентами или клиентами в режиме реального времени, может использовать службу Azure Web PubSub. Традиционные функции в режиме реального времени, которые часто требуют опроса с сервера или отправки HTTP-запросов, также могут использовать службу Azure Web PubSub.

Эту библиотеку можно использовать на стороне сервера приложений для управления клиентскими подключениями WebSocket, как показано на схеме ниже.

Переполнения

Используйте эту библиотеку для выполнения указанных ниже способов.

отправка сообщений в концентраторы и группы;
отправка сообщений определенным пользователям и подключениям;
Группировка пользователей и подключений.
Закрытие подключений.
Предоставление, отмена и проверка разрешений для существующего подключения.

Исходный код | Пакет (Pypi) | Справочная документация по | API Документация по продукту

Заявление об отказе

Поддержка пакетов Python для Пакета Sdk Azure для Python 2.7 закончилась 1 января 2022 г. Дополнительные сведения и вопросы см. на https://github.com/Azure/azure-sdk-for-python/issues/20691

Начало работы

Предварительные требования

Для использования этого пакета требуется Python 3.6 или более поздней версии.
Для использования этого пакета вам потребуется подписка Azure и экземпляр службы Azure WebPubSub .
Существующий экземпляр службы Azure Web PubSub.

1. Установка пакета

python -m pip install azure-messaging-webpubsubservice

2. Создайте класс WebPubSubServiceClient и проверьте его подлинность

Вы можете проверить подлинность с WebPubSubServiceClient помощью строки подключения:

>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient

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

Или с помощью конечной точки службы и ключа доступа:

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

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

Или с помощью Azure Active Directory:

Установка pip azure-identity
Следуйте указаниям в документе, чтобы включить проверку подлинности AAD в ресурсе Webpubsub.

Обновление кода для использования DefaultAzureCredential

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

Основные понятия

Подключение

Подключение, также известное как клиентское или клиентское подключение, представляет собой отдельное подключение WebSocket, подключенное к службе Web PubSub. После успешного подключения служба Web PubSub назначает этому соединению уникальный идентификатор соединения.

Концентратор

Концентратор — это логическая концепция для набора клиентских подключений. Обычно используется один центр для одной цели, например центр чатов или центр уведомлений. При создании клиентского подключения оно подключается к концентратору и во время его существования принадлежит к нему. Разные приложения могут совместно использовать одну службу Azure Web PubSub с использованием разных имен центров.

Группа

Группа — это подмножество подключений к концентратору. Клиентское соединение можно добавлять к группе или удалять из нее в любое время. Например, если клиент присоединяется к комнате чата или покидает ее, такую комнату можно рассматривать как группу. Клиент может присоединиться к множеству групп, а группа может содержать множество клиентов.

Пользователь

Подключения к Web PubSub могут принадлежать одному пользователю. Пользователь может иметь множество подключений, например, если один пользователь подключен через несколько устройств или на нескольких вкладках браузера.

Сообщение

При подключении клиент может отправлять сообщения вышестоящему приложению или получать сообщения от вышестоящего приложения через подключение WebSocket.

Примеры

Широковещательные сообщения в формате 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'
    })

Клиент WebSocket получит сериализованный текст JSON: {"from": "user1", "data": "Hello world"}.

Широковещательные сообщения в формате обычного текста

>>> 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 получит текст: Hello world.

Широковещательные сообщения в двоичном формате

>>> 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 получит двоичный текст: b'Hello world'.

Устранение неполадок

Ведение журнала

Этот пакет SDK использует стандартную библиотеку ведения журнала Python. Вы можете настроить ведение журнала, вывод сведений об отладке в stdout или в любом месте.

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 образом можно включить подробное ведение журнала для одного вызова, даже если он не включен для WebPubSubServiceClient:

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

Сведения о HTTP-запросе и ответе выводятся на стандартный вывод с этой конфигурацией ведения журнала.

Дальнейшие действия

Дополнительные примеры см. здесь.

Участие

На этом проекте приветствуются публикации и предложения. Для участия в большинстве процессов по разработке документации необходимо принять лицензионное соглашение участника (CLA), в котором указывается, что вы предоставляете нам права на использование ваших публикаций. Для получения подробных сведений посетите веб-страницу https://cla.microsoft.com.

При отправке запроса на включение внесенных изменений CLA-бот автоматически определит необходимость предоставления соглашения CLA и соответствующего оформления запроса на включение внесенных изменений (например, добавление метки, комментария). Просто следуйте инструкциям бота. Будет достаточно выполнить их один раз для всех репозиториев, поддерживающих соглашение CLA.

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения: Вопросы и ответы по правилам поведения. С любыми другими вопросами или комментариями обращайтесь по адресу opencode@microsoft.com.

Поделиться через