Клиентская библиотека Azure Web PubSub для Python

Примечание.

Сведения об терминах, используемых здесь, описаны в статье основных понятий.

Клиентский пакет SDK направлен на ускорение рабочего процесса разработчика; в частности,

• упрощение управления клиентскими подключениями
• упрощение отправки сообщений среди клиентов
• автоматически повторяется после непреднамеренного удаления подключения клиента
• надежно доставка сообщений в количестве и порядке после восстановления после удаления подключений

Как показано на схеме, клиенты устанавливают подключения WebSocket к ресурсу Web PubSub.

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

Предпосылки

• Python 3.8+
• Подписка Azure
• Ресурс Web PubSub

1. Установка пакета azure-messaging-webpubsubclient

pip install azure-messaging-webpubsubclient

2. Подключение к ресурсу Web PubSub

Клиент использует Client Access URL для подключения и проверки подлинности со службой, которая соответствует шаблону wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. У клиента может быть несколько способов получения Client Access URL. В этом кратком руководстве можно скопировать и вставить его на портале Azure.

Как показано на схеме, клиент имеет разрешения на отправку сообщений и присоединение к определенной группе с именем group1.

from azure.messaging.webpubsubclient import WebPubSubClient

client = WebPubSubClient("<client-access-url>")
with client:
    # The client can join/leave groups, send/receive messages to and from those groups all in real-time
    ...

3. Присоединение групп

Клиент может получать сообщения только из групп, присоединенных к ним, и необходимо добавить обратный вызов, чтобы указать логику при получении сообщений.

from azure.messaging.webpubsubclient.models import CallbackType

# ...continues the code snippet from above

# Registers a listener for the event 'group-message' early before joining a group to not miss messages
group_name = "group1";
client.subscribe(CallbackType.GROUP_MESSAGE, lambda e: print(f"Received message: {e.data}"));

# A client needs to join the group it wishes to receive messages from
client.join_group(groupName);

4. Отправка сообщений в группу

# ...continues the code snippet from above

# Send a message to a joined group
client.send_to_group(group_name, "hello world", "text");

# In the Console tab of your developer tools found in your browser, you should see the message printed there.

Примеры

Добавление обратных вызовов для connectedсобытий disconnected и stopped событий

1. Когда клиент успешно подключен к ресурсу Web PubSub, активируется событие connected.

   from azure.messaging.webpubsubclient.models import CallbackType
   
   client.subscribe(CallbackType.CONNECTED, lambda e: print(f"Connection {e.connection_id} is connected"))
   

2. Если клиент отключен и не удается восстановить подключение, активируется событие disconnected.

   from azure.messaging.webpubsubclient.models import CallbackType
   
   client.subscribe(CallbackType.DISCONNECTED, lambda e: print(f"Connection disconnected: {e.message}"))
   

3. Событие stopped активируется при отключении клиента, и клиент перестает пытаться повторно подключиться. Обычно это происходит после вызова client.stop() или отключения auto_reconnect или указанного ограничения на попытку повторного подключения. Если вы хотите перезапустить клиент, можно вызвать client.start() в остановленном событии.

   from azure.messaging.webpubsubclient.models import CallbackType
   
   client.subscribe(CallbackType.STOPPED, lambda : print("Client has stopped"))
   

Клиент использует сообщения с сервера приложений или присоединенных групп

Клиент может добавлять обратные вызовы для использования сообщений с сервера приложений или групп. Обратите внимание, что для group-message события клиент может получать только групповые сообщения, присоединенные к нему.

from azure.messaging.webpubsubclient.models import CallbackType

# Registers a listener for the "server-message". The callback is invoked when your application server sends message to the connectionID, to or broadcast to all connections.
client.subscribe(CallbackType.CONNECTED, lambda e: print(f"Received message {e.data}"))

# Registers a listener for the "group-message". The callback is invoked when the client receives a message from the groups it has joined.
client.subscribe(CallbackType.GROUP_MESSAGE, lambda e: print(f"Received message from {e.group}: {e.data}"))

---

Обработка сбоя повторного подключения

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

Однако следует учитывать ограничения auto_rejoin_groups.

• Клиент может повторно присоединиться только к группам, которые изначально присоединяются клиентским кодом, а не серверным кодом.
• Операции повторного объединения могут завершиться ошибкой из-за различных причин, например, у клиента нет разрешения на присоединение к группам. В таких случаях необходимо добавить обратный вызов для обработки этого сбоя.

from azure.messaging.webpubsubclient.models import CallbackType

# By default auto_rejoin_groups=True. You can disable it by setting to False.
client = WebPubSubClient("<client-access-url>", auto_rejoin_groups=True);

# Registers a listener to handle "rejoin-group-failed" event
client.subscribe(CallbackType.REJOIN_GROUP_FAILED, lambda e: print(f"Rejoin group {e.group} failed: {e.error}"))

Операция и повторная попытка

По умолчанию такая операция, как client.join_group(), client.leave_group(), client.send_to_group(), client.send_event() имеет три повторных попытки. Можно настроить с помощью аргументов key-word. Если произошел сбой всех повторных попыток, возникает ошибка. Повторите попытку, передав ту же ack_id, что и предыдущие повторные попытки, чтобы служба Web PubSub может дедупликировать операцию.

try:
    client.join_group(group_name)
except SendMessageError as e:
    client.join_group(group_name, ack_id=e.ack_id)

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

Включение журналов

Чтобы получить журналы отладки при использовании этой библиотеки, можно задать следующую переменную среды.

export AZURE_LOG_LEVEL=verbose

Дополнительные инструкции по включению журналов см. в документации по пакету @azure/loger.

Динамическая трассировка

Используйте средство динамической трассировки из портал Azure для проверки трафика сообщений через ресурс Web PubSub.