Protocolli client WebSocket per Web PubSub di Azure

I client si connettono a PubSub Web di Azure usando il protocollo WebSocket standard.

Endpoint di servizio

Il servizio Web PubSub fornisce due tipi di endpoint a cui i client possono connettersi:

• /client/hubs/{hub}
• /client/?hub={hub}

{hub} è un parametro obbligatorio che funge da isolamento per varie applicazioni. È possibile impostarlo nel percorso o nella query.

Autorizzazione

I client si connettono al servizio con un token JSON Web (JWT). Il token può trovarsi nella stringa di query, come /client/?hub={hub}&access_token={token}o nell'intestazione Authorization , come Authorization: Bearer {token}.

Ecco un flusso di lavoro di autorizzazione generale:

1. Il client negozia con il server delle applicazioni. Il server applicazioni contiene il middleware di autorizzazione, che gestisce la richiesta client e firma un token JWT per consentire al client di connettersi al servizio.
2. Il server applicazioni restituisce il token JWT e l'URL del servizio al client.
3. Il client tenta di connettersi al servizio Web PubSub usando l'URL e il token JWT restituito dal server applicazioni.

Attestazioni supportate

È anche possibile configurare le proprietà per la connessione client durante la generazione del token di accesso specificando attestazioni speciali all'interno del token JWT:

È anche possibile aggiungere attestazioni personalizzate nel token di accesso e questi valori vengono mantenuti come proprietà claims nel collegare il corpo della richiesta a monte.

Gli SDK server forniscono API per generare il token di accesso per i client.

Il client WebSocket semplice

Un semplice client WebSocket, come indicato dalla denominazione, è una semplice connessione WebSocket. Può anche avere un sottoprotocolo personalizzato.

Ad esempio, in JavaScript è possibile creare un semplice client WebSocket usando il codice seguente:

// simple WebSocket client1
var client1 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1');

// simple WebSocket client2 with some custom subprotocol
var client2 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'custom.subprotocol')

Il client WebSocket semplice ha due modalità: sendEvent e sendToGroup. La modalità viene determinata una volta stabilita la connessione e non può essere modificata in un secondo momento.

sendEvent è la modalità predefinita per il client WebSocket semplice. In sendEvent modalità, ogni frame WebSocket inviato dal client viene considerato come un message evento. Gli utenti possono configurare gestori di eventi o listener di eventi per gestire questi message eventi.

// Every data frame is considered as a `message` event
var client3 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1');

// Or explicitly set the mode
var client4 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1?webpubsub_mode=sendEvent');

In sendToGroup modalità, ogni frame WebSocket inviato dal client viene considerato come un messaggio da pubblicare in un gruppo specifico. group è un parametro di query obbligatorio in questa modalità ed è consentito solo un singolo valore. La connessione deve inoltre disporre delle autorizzazioni corrispondenti per inviare messaggi al gruppo di destinazione. Entrambi i ruoli webpubsub.sendToGroup.<group> e webpubsub.sendToGroup sono adatti.

Ad esempio, in JavaScript è possibile creare un semplice client WebSocket in sendToGroup modalità con group=group1 usando il codice seguente:

var client5 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1?webpubsub_mode=sendToGroup&group=group1');

Client WebSocket PubSub

Un client WebSocket PubSub è il client WebSocket che utilizza i sottoprotocolli definiti dal servizio Web PubSub di Azure.

• json.webpubsub.azure.v1
• protobuf.webpubsub.azure.v1

Con il sottoprotocolo supportato dal servizio, il clientWebSocket PubSocket può pubblicare direttamente i messaggi ai gruppi quando hanno le autorizzazioni.

Sottoprotocolo json.webpubsub.azure.v1

Controllare qui il sottoprotocolo JSON in dettaglio.

Creare un client PubSub WebSocket

var pubsubClient = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'json.webpubsub.azure.v1');

Aggiungere direttamente un gruppo dal client

let ackId = 0;
pubsubClient.send(
    JSON.stringify({
        type: 'joinGroup',
        group: 'group1',
        ackId: ++ackId
    }));

Inviare messaggi a un gruppo direttamente dal client

let ackId = 0;
pubsubClient.send(
    JSON.stringify({
        type: 'sendToGroup',
        group: 'group1',
        ackId: ++ackId,
        dataType: "json",
        data: {
            "hello": "world"
        }
    }));

Sottoprotocolo protobuf.webpubsub.azure.v1

I buffer di protocollo (protobuf) sono un protocollo indipendente dal linguaggio, indipendente dalla piattaforma e basato su binario che semplifica l'invio di dati binari. Protobuf offre strumenti per generare client per molti linguaggi, ad esempio Java, Python, Objective-C, C# e C++. Altre informazioni su protobuf.

In JavaScript, ad esempio, è possibile creare un client WebSocket PubSub con un sottoprotocolo protobuf usando il codice seguente:

// PubSub WebSocket client
var pubsub = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'protobuf.webpubsub.azure.v1');

Per informazioni dettagliate sul sottoprotocolo protobuf, vedere qui.

Risposta di AckId e Ack

Il client PubSub WebSocket supporta la proprietà ackId per i messaggi joinGroup, leaveGroup, sendToGroup e event. Quando si utilizza ackId, è possibile ricevere un messaggio di risposta di conferma quando la richiesta viene elaborata. È possibile scegliere di omettere ackId negli scenari fire-and-forget. Nell'articolo vengono descritte le differenze di comportamento tra specificare ackId o meno.

Comportamento quando non è specificato alcun ackId valore

Se ackId non viene specificato, è di tipo "fire-and-forget". Anche se si verificano errori durante la brokering dei messaggi, non è possibile ricevere notifiche.

Comportamento nel caso in cui ackId sia specificato

Pubblicazione Idempotente

ackId è un numero uint64 e deve essere univoco all'interno di un client con lo stesso ID di connessione. Il servizio Web PubSub registra i ackId e i messaggi con lo stesso ackId sono considerati lo stesso messaggio. Il servizio rifiuta di negoziare più volte lo stesso messaggio, utile per riprovare a evitare messaggi duplicati. Ad esempio, se un client invia un messaggio con ackId=5 e non riceve una risposta ack con ackId=5, il client ritenta e invia di nuovo lo stesso messaggio. In alcuni casi, il messaggio è già stato trasmesso e la risposta ack va persa per qualche motivo. Il servizio rifiuta il tentativo di risposta e fornisce un ack con motivo Duplicate.

Risposta ack

Il servizio Web PubSub invia risposta di conferma per ogni richiesta con ackId.

Formato:

{
    "type": "ack",
    "ackId": 1, // The ack id for the request to ack
    "success": false, // true or false
    "error": {
        "name": "Forbidden|InternalServerError|Duplicate",
        "message": "<error_detail>"
    }
}

• Il ackId associa la richiesta.

• success è un valore bool e indica se la richiesta è stata elaborata correttamente dal servizio. Se è false, i clienti devono controllare error.

• error esiste solo quando success è false e i client devono avere logica diversa per name. Si supponga che ci sia più tipo di name in futuro.

  • Forbidden: il client non dispone dell'autorizzazione per la richiesta. Il client deve essere aggiunto ai ruoli pertinenti.
  • InternalServerError: si è verificato un errore interno nel servizio. È necessario riprovare.
  • Duplicate: il messaggio con lo stesso ackId è già stato elaborato dal servizio.

Autorizzazioni

Come probabilmente si è notato nella descrizione del client PubSub WebSocket precedente, un client può pubblicare in altri client solo quando è autorizzato a farlo. Le autorizzazioni di un client possono essere concesse quando è connesso o durante la durata della connessione.

L'autorizzazione di un client può essere concessa in diversi modi:

1. Assegnare il ruolo al client durante la generazione del token di accesso

Il client può connettersi al servizio usando un token JWT. Il payload del token può contenere informazioni come il role del client. Quando si firma il token JWT al client, è possibile concedere le autorizzazioni al client assegnando ruoli specifici al client.

Ad esempio, si firma un token JWT con l'autorizzazione per inviare messaggi a group1 e group2:

let token = await serviceClient.getClientAccessToken({
    roles: [ "webpubsub.sendToGroup.group1", "webpubsub.sendToGroup.group2" ]
});

2. Assegnare il ruolo al client con il connect gestore di eventi

I ruoli dei client possono essere impostati anche quando il connect gestore eventi è registrato e il gestore eventi upstream può restituire il roles del client al servizio Web PubSub durante la gestione degli connect eventi.

Ad esempio, in JavaScript, è possibile configurare l'evento handleConnect per farlo:

let handler = new WebPubSubEventHandler("hub1", {
  handleConnect: (req, res) => {
    // auth the connection and set the userId of the connection
    res.success({
      roles: [ "webpubsub.sendToGroup.group1", "webpubsub.sendToGroup.group2" ]
    });
  },
});

3. Assegnare il ruolo al client tramite API REST o SDK del server durante il runtime

let service = new WebPubSubServiceClient("<your_connection_string>", "test-hub");
await service.grantPermission("<connection_id>", "joinLeaveGroup", { targetName: "group1" });

Passaggi successivi

Usare queste risorse per iniziare a compilare un'applicazione personalizzata: