Azure Web PubSub-clientbibliotheek voor Python

De SDK aan de clientzijde wil de werkstroom van ontwikkelaars versnellen; meer specifiek,

• vereenvoudigt het beheren van clientverbindingen
• vereenvoudigt het verzenden van berichten tussen clients
• automatisch opnieuw proberen na onbedoelde uitval van clientverbinding
• betrouwbare levering van berichten in getal en in volgorde na het herstellen van verbinding druppels

Zoals in het diagram wordt weergegeven, maken uw clients WebSocket-verbindingen met uw Web PubSub-resource.

Aan de slag

Vereiste voorwaarden

• Python 3.8+
• Een Azure-abonnement
• Een Web PubSub-resource

1. Het azure-messaging-webpubsubclient-pakket installeren

pip install azure-messaging-webpubsubclient

2. Verbinding maken met uw Web PubSub-resource

Een client gebruikt een Client Access URL om verbinding te maken en te verifiëren met de service, die een patroon van wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>volgt. Een client kan een aantal manieren hebben om de Client Access URL. Voor deze quickstart kunt u er een kopiëren en plakken vanuit azure Portal die wordt weergegeven.

Zoals wordt weergegeven in het diagram, heeft de client de machtigingen om berichten te verzenden naar en lid te worden van een specifieke groep met de naam 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. Deelnemen aan groepen

Een client kan alleen berichten ontvangen van groepen die eraan zijn toegevoegd en u moet een callback toevoegen om de logica op te geven bij het ontvangen van berichten.

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. Berichten verzenden naar een groep

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

Voorbeelden

Callbacks voor connecteden disconnectedstopped gebeurtenissen toevoegen

1. Wanneer een client is verbonden met uw Web PubSub-resource, wordt de connected gebeurtenis geactiveerd.

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

2. Wanneer een client is verbroken en de verbinding niet kan worden hersteld, wordt de disconnected gebeurtenis geactiveerd.

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

3. De stopped gebeurtenis wordt geactiveerd wanneer de verbinding met de client is verbroken en de client stopt met opnieuw verbinding maken. Dit gebeurt meestal nadat de client.stop() is aangeroepen, of auto_reconnect is uitgeschakeld of een opgegeven limiet voor het opnieuw verbinden is bereikt. Als u de client opnieuw wilt starten, kunt u client.start() aanroepen in de gestopte gebeurtenis.

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

Een client gebruikt berichten van de toepassingsserver of gekoppelde groepen

Een client kan callbacks toevoegen om berichten van uw toepassingsserver of -groepen te gebruiken. Opmerking: voor group-message het geval de client alleen groepsberichten kan ontvangen waaraan de client is toegevoegd.

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

Fout bij opnieuw deelnemen afhandelen

Wanneer de verbinding met een client is verbroken en niet kan worden hersteld, worden alle groepscontexten opgeschoond in uw Web PubSub-resource. Dit betekent dat wanneer de client opnieuw verbinding maakt, de client opnieuw moet deelnemen aan groepen. De client heeft standaard auto_rejoin_groups optie ingeschakeld.

U moet echter rekening houden met de beperkingen van auto_rejoin_groups.

• De client kan alleen opnieuw deelnemen aan groepen die oorspronkelijk zijn gekoppeld door de clientcode , niet door de code aan de serverzijde.
• 'opnieuw deelnemen aan groep' bewerkingen kunnen mislukken vanwege verschillende redenen, bijvoorbeeld omdat de client niet gemachtigd is om lid te worden van de groepen. In dergelijke gevallen moet u een callback toevoegen om deze fout af te handelen.

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

Bewerking en nieuwe poging

De bewerking zoals client.join_group(), client.leave_group(), client.send_to_group(), client.send_event() heeft standaard drie nieuwe pogingen. U kunt de sleutelwoordargumenten configureren. Als alle nieuwe pogingen zijn mislukt, wordt er een fout gegenereerd. U kunt het opnieuw proberen door dezelfde ack_id door te geven als eerdere nieuwe pogingen, zodat de Web PubSub-service de bewerking kan ontdubbelen.

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

Problemen oplossen

Logboeken inschakelen

U kunt de volgende omgevingsvariabele instellen om de logboeken voor foutopsporing op te halen bij het gebruik van deze bibliotheek.

export AZURE_LOG_LEVEL=verbose

Voor meer gedetailleerde instructies over het inschakelen van logboeken, kunt u de @azure/logger pakketdocumentenbekijken.

Live Trace

Gebruik het hulpprogramma Live Trace vanuit de Azure-portal om live berichtenverkeer te inspecteren via uw Web PubSub-resource.