Protocolli client WebSocket per Web PubSub di Azure

Articolo
10/26/2023

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:

Il client negozia con il server 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.
Il server applicazioni restituisce il token JWT e l'URL del servizio al client.
Il client tenta di connettersi al servizio Web PubSub usando l'URL e il token JWT restituito dal server applicazioni.

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

Client PubSub WebSocket

Un client WebSocket PubSocket è il client WebSocket usando sottoprotocols 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 AckId e Ack

Il client WebSocket PubSocket supporta ackId la proprietà per joinGroupi messaggi , leaveGroupsendToGroup e event . Quando si usa ackId, è possibile ricevere un messaggio di risposta ack quando la richiesta viene elaborata. È possibile scegliere di omettere ackId 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, è fire-and-forget. Anche se si verificano errori durante la brokering dei messaggi, non è possibile ricevere notifiche.

Comportamento quando `ackId` specificato

Pubblicazione Idempotente

ackId è un numero uint64 e deve essere univoco all'interno di un client con lo stesso ID connessione. Il servizio Web PubSub registra i ackId messaggi e con lo stesso ackId messaggio verrà considerato come 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à negoziato e la risposta ack viene persa per qualche motivo, il servizio rifiuterà il tentativo e risponderà a una risposta ack con Duplicate motivo.

Risposta Ack

Il servizio Web PubSub invia una risposta ack 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>"
    }
}

Associa ackId la richiesta.
success è un valore bool e indica se la richiesta è stata elaborata correttamente dal servizio. Se è false, i client 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 sono connesse o durante la durata della connessione.

Ruolo	Autorizzazione
Non specificato	Il client può inviare richieste di eventi.
`webpubsub.joinLeaveGroup`	Il client può partecipare o lasciare qualsiasi gruppo.
`webpubsub.sendToGroup`	Il client può pubblicare messaggi in qualsiasi gruppo.
`webpubsub.joinLeaveGroup.<group>`	Il client può partecipare o lasciare il gruppo `<group>`.
`webpubsub.sendToGroup.<group>`	Il client può pubblicare messaggi nel gruppo `<group>`.

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