Libreria client del servizio Web PubSub di Azure per Python - versione 1.0.1

Articolo
04/05/2023

Il servizio Web PubSub di Azure è un servizio gestito da Azure che consente agli sviluppatori di creare facilmente applicazioni Web con funzionalità in tempo reale e modello di pubblicazione-sottoscrizione. Qualsiasi scenario che richiede la messaggistica di pubblicazione-sottoscrizione in tempo reale tra server e client o tra client può usare il servizio PubSub Web di Azure. Le funzionalità tradizionali in tempo reale che spesso richiedono il polling dal server o l'invio di richieste HTTP possono usare anche il servizio PubSub Web di Azure.

È possibile usare questa libreria sul lato server dell'app per gestire le connessioni client WebSocket, come illustrato nel diagramma seguente:

Overflow

Usare questa libreria per:

Inviare messaggi a hub e gruppi.
Inviare messaggi a utenti e connessioni specifici.
Organizzare utenti e connessioni in gruppi.
Chiudere le connessioni
Concedere, revocare e controllare le autorizzazioni per una connessione esistente

Codice | sorgente Pacchetto (Pypi) | Documentazione | di riferimento sulle API Documentazione del prodotto

Dichiarazione di non responsabilità

Il supporto dei pacchetti Python di Azure SDK per Python 2.7 è terminato il 01 gennaio 2022. Per altre informazioni e domande, fare riferimento a https://github.com/Azure/azure-sdk-for-python/issues/20691

Introduzione

Prerequisiti

Python 3.6 o versione successiva è necessario per usare questo pacchetto.
Per usare questo pacchetto è necessaria una sottoscrizione di Azure e un'istanza del servizio WebPubSub di Azure .
Istanza del servizio Web PubSub di Azure esistente.

1. Installare il pacchetto

python -m pip install azure-messaging-webpubsubservice

2. Creare ed autenticare un WebPubSubServiceClient

È possibile autenticare usando la WebPubSubServiceClientstringa di connessione:

>>> from azure.messaging.webpubsubservice import WebPubSubServiceClient

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

Oppure usando l'endpoint del servizio e la chiave di accesso:

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

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

In alternativa, usare Azure Active Directory:

pip install azure-identity
Seguire il documento per abilitare l'autenticazione AAD nella risorsa Webpubsub

Aggiornare il codice per usare DefaultAzureCredential

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

Concetti chiave

Connessione

Una connessione, nota anche come client o connessione client, rappresenta una singola connessione WebSocket connessa al servizio Web PubSub. Una volta stabilita la connessione, un ID di connessione univoco viene assegnato a questa connessione dal servizio Web PubSub.

Hub

Un hub è un concetto logico per un set di connessioni client. In genere si usa un hub per uno scopo, ad esempio un hub di chat o un hub di notifica. Quando viene creata una connessione client, si connette a un hub e, durante la sua durata, appartiene a tale hub. Diverse applicazioni possono condividere un servizio PubSub Web di Azure usando nomi di hub diversi.

Gruppo

Un gruppo è un subset di connessioni all'hub. È possibile aggiungere una connessione client a un gruppo o rimuovere la connessione client dal gruppo in qualsiasi momento. Ad esempio, quando un client partecipa a una chat room o quando un client lascia la chat room, questa chat room può essere considerata un gruppo. Un client può partecipare a più gruppi e un gruppo può contenere più client.

Utente

Le connessioni a Web PubSub possono appartenere a un utente. Un utente potrebbe avere più connessioni, ad esempio quando un singolo utente è connesso tra più dispositivi o più schede del browser.

Message

Quando il client è connesso, può inviare messaggi all'applicazione upstream o ricevere messaggi dall'applicazione upstream tramite la connessione WebSocket.

Esempio

Trasmettere messaggi in formato 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'
    })

Il client WebSocket riceverà testo serializzato JSON: {"from": "user1", "data": "Hello world"}.

Trasmettere messaggi in formato testo normale

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

Il client WebSocket riceverà testo: Hello world.

Trasmettere messaggi in formato binario

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

Il client WebSocket riceverà testo binario: b'Hello world'.

Risoluzione dei problemi

Registrazione

Questo SDK usa la libreria di registrazione standard python. È possibile configurare la registrazione per stampare le informazioni di debug nel stdout o in qualsiasi punto desiderato.

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)

Analogamente, logging_enable può abilitare la registrazione dettagliata per una singola chiamata, anche quando non è abilitata per WebPubSubServiceClient:

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

I dettagli di richiesta e risposta HTTP vengono stampati in stdout con questa configurazione di registrazione.

Passaggi successivi

Vedere altri esempi qui.

Contributo

In questo progetto sono benvenuti i contributi e i suggerimenti. Per la maggior parte dei contenuti è necessario sottoscrivere un contratto di licenza di collaborazione (CLA, Contributor License Agreement) che stabilisce che l'utente ha il diritto di concedere, e di fatto concede a Microsoft i diritti d'uso del suo contributo. Per informazioni dettagliate, vedere https://cla.microsoft.com.

Quando si invia una richiesta pull, un bot CLA determina automaticamente se è necessario specificare un contratto CLA e completare la richiesta pull in modo appropriato (ad esempio con un'etichetta e un commento). Seguire le istruzioni specificate dal bot. È sufficiente eseguire questa operazione una sola volta per tutti i repository che usano il contratto CLA Microsoft.

Questo progetto ha adottato il Codice di comportamento di Microsoft per l'open source. Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento) oppure contattare opencode@microsoft.com per eventuali altre domande o commenti.

Condividi tramite