Edit

Azure Web PubSub service client library for Python

  • Article

Azure Web PubSub Service is an Azure-managed service that helps developers easily build web applications with real-time features and publish-subscribe pattern. Any scenario that requires real-time publish-subscribe messaging between server and clients or among clients can use Azure Web PubSub service. Traditional real-time features that often require polling from server or submitting HTTP requests can also use Azure Web PubSub service.

You can use this library in your app server side to manage the WebSocket client connections, as shown in following diagram:

The overflow diagram shows the overflow of using the service client library.

Use this library to:

  • Send messages to hubs and groups.
  • Send messages to particular users and connections.
  • Organize users and connections into groups.
  • Close connections.
  • Grant, revoke, and check permissions for an existing connection.

Prerequisites

Important

Azure SDK Python packages support for Python 2.7 is ending 01 January 2022. For more information, see Azure SDK Python packages support.

Install the package

Use this command to install the package:

python -m pip install azure-messaging-webpubsubservice

Create and authenticate a WebPubSubServiceClient

You can authenticate the WebPubSubServiceClient using a connection string:

>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient

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

Or use the service endpoint and the access key:

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

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

Or use Microsoft Entra ID:

  1. pip install azure-identity.

  2. Enable Microsoft Entra authorization on your Webpubsub resource.

  3. Update code to use DefaultAzureCredential.

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

Examples

Broadcast messages in JSON format

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

The WebSocket client receives JSON serialized text: {"from": "user1", "data": "Hello world"}.

Broadcast messages in plain-text format

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

The WebSocket client receives text: Hello world.

Broadcast messages in binary format

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

The WebSocket client receives binary text: b'Hello world'.

Logging

This SDK uses Python standard logging library. You can configure logging to print debugging information to the stdout or anywhere you want.

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)

Similarly, logging_enable can enable detailed logging for a single call, even when it isn't enabled for the WebPubSubServiceClient:

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

HTTP request and response details are printed to stdout with this logging configuration.

Next steps

For more samples, see Azure Web PubSub service client library for Python Samples.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For more information, see Contributor License Agreement.

When you submit a pull request, a CLA-bot automatically determines whether you need to provide a CLA and decorate the PR appropriately, for example, "label", "comment". Follow the instructions provided by the bot. You only need to do this action once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see Code of Conduct FAQ or contact Open Source Conduct Team with questions or comments.