Package: azure-messaging-webpubsubclient
Azure Web PubSub client library for PythonAzure Web PubSubis a cloud service that helps developers easily build real-time features in web applications with publish-subscribe patterns at scale.Any scenario that requires real-time messaging between server and clients or among clients following publish-subscribe patterns can benefit from using Web PubSub. Developers no longer need to poll the server by sending repeated HTTP requests at intervals, which is wasteful and hard-to-scale.As shown in the diagram below, your clients establish WebSocket connections with your Web PubSub resource. This client library:simplifies managing client connectionssimplifies sending messages among clientsautomatically retries after unintended drops of client connectionreliably deliveries messages in number and in order after recovering from connection dropsDetails about the terms used here are described inkey conceptssection.This library is hosted onpypi.Getting startedCurrently supported environmentsPython 3.7+PrerequisitesAnAzure subscription.AWeb PubSub resource1. Install theazure-messaging-webpubsubclientpackagepipinstallazure-messaging-webpubsubclient2. Connect with your Web PubSub resourceA client uses a Client Access URL to connect and authenticate with the service, which follows a pattern ofwss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. A client can have a few ways to obtain the Client Access URL. For this quick start, you can copy and paste one from Azure Portal shown below.As shown in the diagram above, the client has the permissions to send messages to and join a specific group named "group1".fromazure.messaging.webpubsubclientimportWebPubSubClientclient=WebPubSubClient("<<client-access-url>>")withclient:# The client can join/leave groups, send/receive messages to and from those groups all in real-time...3. Join groupsNote that a client can only receive messages from groups that it has joined and you need to add a callback to specify the logic when receiving messages.# ...continues the code snippet from above# Registers a listener for the event 'group-message' early before joining a group to not miss messagesgroup_name="group1";client.subscribe("group-message",lambdae:print(f"Received message:{e.data}"));# A client needs to join the group it wishes to receive messages fromclient.join_group(groupName);4. Send messages to a group# ...continues the code snippet from above# Send a message to a joined groupclient.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.ExamplesAdd callbacks for connected, disconnected and stopped eventsWhen a client is successfully connected to your Web PubSub resource, theconnectedevent is triggered.client.subscribe("connected",lambdae:print(f"Connection{e.connection_id}is connected"))When a client is disconnected and fails to recover the connection, thedisconnectedevent is triggered.client.subscribe("disconnected",lambdae:print(f"Connection disconnected:{e.message}"))Thestoppedevent will be triggered when the client is disconnectedandthe client stops trying to reconnect. This usually happens after theclient.close()is called, orauto_reconnectis disabled or a specified limit to trying to reconnect has reached. If you want to restart the client, you can callclient.open()in the stopped event.client.subscribe("stopped",lambda:print("Client has stopped"))A client consumes messages from the application server or joined groupsA client can add callbacks to consume messages from your application server or groups. Please note, forgroup-messageevent the client canonlyreceive group messages that it has joined.# Registers a listener for the "server-message". The callback will be invoked when your application server sends message to the connectionID, to or broadcast to all connections.client.subscribe("server-message",lambdae:print(f"Received message{e.data}"))# Registers a listener for the "group-message". The callback will be invoked when the client receives a message from the groups it has joined.client.subscribe("group-message",lambdae:print(f"Received message from{e.group}:{e.data}"))Handle rejoin failureWhen a client is disconnected and fails to recover, all group contexts will be cleaned up in your Web PubSub resource. This means when the client reconnects, it needs to rejoin groups. By default, the client hasauto_rejoin_groupsoption enabled.However, you should be aware ofauto_rejoin_groups's limitations.The client can only rejoin groups that it's originally joined by the client codenotby the server side code."rejoin group" operations may fail due to various reasons, e.g. the client doesn't have permission to join the groups. In such cases, you need to add a callback to handle this failure.# 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" eventclient.subscribe("rejoin-group-failed",lambdae:print(f"Rejoin group{e.group}failed:{e.error}"))Operation and retryBy default, the operation such asclient.join_group(),client.leave_group(),client.send_to_group(),client.send_event()has three retries. You can configure through the key-word arguments. If all retries have failed, an error will be thrown. You can keep retrying by passing in the sameack_idas previous retries so that the Web PubSub service can deduplicate the operation.try:client.join_group(group_name)exceptSendMessageErrorase:client.join_group(group_name,ack_id=e.ack_id)Specify subprotocolYou can change the subprotocol to be used by the client. By default, the client usesjson.reliable.webpubsub.azure.v1. You can choose to usejson.reliable.webpubsub.azure.v1orjson.webpubsub.azure.v1.fromazure.messaging.webpubsubclient.modelsimportWebPubSubProtocolType# Change to use json.webpubsub.azure.v1constclient=newWebPubSubClient("<client-access-url>",protocol_type=WebPubSubProtocolType.JSON);fromazure.messaging.webpubsubclient.modelsimportWebPubSubProtocolType# Change to use json.reliable.webpubsub.azure.v1constclient=newWebPubSubClient("<client-access-url>",protocol_type=WebPubSubProtocolType.JSON_RELIABLE);Key conceptsConnectionA connection, also known as a client or a client connection, represents an individual WebSocket connection connected to the Web PubSub. When successfully connected, a unique connection ID is assigned to this connection by the Web PubSub. EachWebPubSubClientcreates its own exclusive connection.RecoveryIf a client using reliable protocols disconnects, a new WebSocket tries to establish using the connection ID of the lost connection. If the new WebSocket connection is successfully connected, the connection is recovered. Throughout the time a client is disconnected, the service retains the client's context as well as all messages that the client was subscribed to, and when the client recovers, the service will send these messages to the client. If the service returns WebSocket error code1008or the recovery attempt lasts more than 30 seconds, the recovery fails.ReconnectReconnection happens when the client connection drops and fails to recover. Reconnection starts a new connection and the new connection has a new connection ID. Unlike recovery, the service treats the reconnected client as a new client connection. The client connection needs to rejoin groups. By default, the client library rejoins groups after reconnection.HubA hub is a logical concept for a set of client connections. Usually, you use one hub for one purpose, for example, a chat hub, or a notification hub. When a client connection is created, it connects to a hub, and during its lifetime, it belongs to that hub. Different applications can share one Web PubSub by using different hub names.GroupA group is a subset of connections to the hub. You can add a client connection to a group, or remove the client connection from the group, anytime you want. For example, when a client joins a chat room, or when a client leaves the chat room, this chat room can be considered to be a group. A client can join multiple groups, and a group can contain multiple clients.UserConnections to Web PubSub can belong to one user. A user might have multiple connections, for example when a single user is connected across multiple devices or multiple browser tabs.Client LifetimeEach of the Web PubSub clients is safe to cache and be used as a singleton for the lifetime of the application. The registered event callbacks share the same lifetime with the client. This means you can add or remove callbacks at any time and the registration status will not change after reconnection or the client being stopped.TroubleshootingThis library uses the standardlogginglibrary for logging. If you want detailedDEBUGlevel logging, including payload of request, you can setlogging_enable=Truein client or per-operationNext stepsYou can also findmore samples here.Additional resourcesLearn more about client permission, seepermissionsProduct documentationContributingIf you'd like to contribute to this library, please read thecontributing guideto learn more about how to build and test the code.