Share via

Sottoprotocolo JSON WebSocket supportato da Web PubSub di Azure

  • Articolo

Il sottoprotocolo JSON WebSocket, json.webpubsub.azure.v1, consente lo scambio di messaggi di pubblicazione/sottoscrizione tra i client tramite il servizio senza un round trip al server upstream. Una connessione WebSocket che usa il json.webpubsub.azure.v1 sottoprotocolo viene chiamata client WebSocket PubSub.

Panoramica

Una semplice connessione WebSocket attiva un message evento quando invia messaggi e si basa sul lato server per elaborare i messaggi ed eseguire altre operazioni.

Con il json.webpubsub.azure.v1 sottoprotocolo è possibile creare client PubSub WebSocket che possono:

  • partecipare a un gruppo usando le richieste di join.
  • pubblicare i messaggi direttamente in un gruppo usando le richieste di pubblicazione.
  • instradare i messaggi a gestori eventi upstream diversi usando le richieste di eventi.

Ad esempio, è possibile creare un client WebSocket PubSocket con il codice JavaScript seguente:

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

Questo documento descrive le richieste e le risposte del sottoprotocolo json.webpubsub.azure.v1 . Sia i frame di dati in ingresso che in uscita devono contenere payload JSON.

Autorizzazioni

Un client WebSocket PubSocket può pubblicare solo in altri client quando è autorizzato. L'oggetto roles assegnato al client determina le autorizzazioni concesse al client:

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

Il server può concedere o revocare in modo dinamico le autorizzazioni client tramite API REST o SDK del server.

Richieste

Partecipare ai gruppi

Formato:

{
    "type": "joinGroup",
    "group": "<group_name>",
    "ackId" : 1
}
  • ackId è l'identità di ogni richiesta e deve essere univoca. Il servizio invia un messaggio di risposta ack per notificare il risultato del processo della richiesta. Per informazioni dettagliate, vedere AckId e Risposta Ack

Lasciare i gruppi

Formato:

{
    "type": "leaveGroup",
    "group": "<group_name>",
    "ackId" : 1
}
  • ackId è l'identità di ogni richiesta e deve essere univoca. Il servizio invia un messaggio di risposta ack per notificare il risultato del processo della richiesta. Per informazioni dettagliate, vedere AckId e Risposta Ack

Pubblicare messaggi

Formato:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "ackId" : 1,
    "noEcho": true|false,
    "dataType" : "json|text|binary",
    "data": {}, // data can be string or valid json token depending on the dataType 
}
  • ackId è l'identità di ogni richiesta e deve essere univoca. Il servizio invia un messaggio di risposta ack per notificare il risultato del processo della richiesta. Per informazioni dettagliate, vedere AckId e Risposta Ack
  • noEcho è facoltativo. Se impostato su true, questo messaggio non viene restituito alla stessa connessione. Se non è impostato, il valore predefinito è false.
  • dataType può essere impostato su json, texto binary:
    • json: data può essere qualsiasi tipo supportato da JSON e verrà pubblicato come quello che è; Se dataType non viene specificato, per impostazione predefinita è json.
    • text: data deve essere in formato stringa e i dati stringa verranno pubblicati;
    • binary: data deve essere in formato base64 e i dati binari verranno pubblicati;

Caso 1: pubblicare dati di testo:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "text",
    "data": "text data",
    "ackId": 1
}
  • I client subprotocol in <group_name> ricevono:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "text",
    "data" : "text data"
}
  • I semplici client WebSocket in <group_name> ricevono la stringa text data.

Caso 2: pubblicare dati JSON:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "json",
    "data": {
        "hello": "world"
    }
}
  • I client subprotocol in <group_name> ricevono:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "json",
    "data" : {
        "hello": "world"
    }
}
  • I semplici client WebSocket in <group_name> ricevono la stringa {"hello": "world"}serializzata .

Caso 3: pubblicare dati binari:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "binary",
    "data": "<base64_binary>",
    "ackId": 1
}
  • I client subprotocol in <group_name> ricevono:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "binary",
    "data" : "<base64_binary>", 
}
  • I semplici client WebSocket in <group_name> ricevono i dati binari nel frame binario.

Inviare eventi personalizzati

Formato:

{
    "type": "event",
    "event": "<event_name>",
    "ackId": 1,
    "dataType" : "json|text|binary",
    "data": {}, // data can be string or valid json token depending on the dataType 
}
  • ackId è l'identità di ogni richiesta e deve essere univoca. Il servizio invia un messaggio di risposta ack per notificare il risultato del processo della richiesta. Per informazioni dettagliate, vedere AckId e Risposta Ack

dataType può essere uno di text, binaryo json:

  • json: i dati possono essere supportati da qualsiasi tipo json e verranno pubblicati come sono; Il valore predefinito è json.
  • text: i dati sono in formato stringa e i dati stringa verranno pubblicati;
  • binary: i dati sono in formato base64 e i dati binari verranno pubblicati;

Caso 1: inviare un evento con dati di testo:

{
    "type": "event",
    "event": "<event_name>",
    "ackId": 1,
    "dataType" : "text",
    "data": "text data", 
}

Il gestore eventi upstream riceve dati simili a:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: text/plain
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>

text data

Per Content-Type la richiesta HTTP CloudEvents è text/plain quando dataType è text.

Caso 2: inviare un evento con dati JSON:

{
    "type": "event",
    "event": "<event_name>",
    "ackId": 1,
    "dataType" : "json",
    "data": {
        "hello": "world"
    }, 
}

Il gestore eventi upstream riceve dati simili a:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>

{
    "hello": "world"
}

L'oggetto Content-Type per la richiesta HTTP CloudEvents è application/json quando dataType è json

Caso 3: inviare un evento con dati binari:

{
    "type": "event",
    "event": "<event_name>",
    "ackId": 1,
    "dataType" : "binary",
    "data": "base64_binary", 
}

Il gestore eventi upstream riceve dati simili a:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/octet-stream
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>

binary

Per Content-Type la richiesta HTTP CloudEvents è application/octet-stream quando dataType è binary. Il frame WebSocket può essere text formattato per frame di testo o file binari con codifica UTF8 per binary i fotogrammi di messaggio.

Il servizio Web PubSub rifiuta il client se il messaggio non corrisponde al formato descritto.

Risposte

I tipi di messaggio ricevuti dal client possono essere:

  • ack: risposta a una richiesta contenente un oggetto ackId.
  • message: messaggi provenienti dal gruppo o dal server.
  • system: messaggi dal servizio Web PubSub.

Risposta Ack

Quando la richiesta client contiene ackId, il servizio restituirà una risposta ack per la richiesta. Il client deve gestire il meccanismo ack, attendendo la risposta ack con un'operazione asyncawait e usando un'operazione di timeout quando la risposta ack non viene ricevuta in un determinato periodo.

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

L'implementazione del client DEVE sempre controllare se success è true o false prima, quindi leggere solo l'errore quando success è false.

Risposta al messaggio

I client possono ricevere messaggi pubblicati da un gruppo che il client ha aggiunto o dal server, che opera in un ruolo di gestione del server, invia messaggi a client o utenti specifici.

  1. Quando il messaggio proviene da un gruppo

    {
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType": "json|text|binary",
    "data" : {} // The data format is based on the dataType
    "fromUserId": "abc"
}

  2. Quando il messaggio proviene dal server.

    {
    "type": "message",
    "from": "server",
    "dataType": "json|text|binary",
    "data" : {} // The data format is based on the dataType
}

Caso 1: Invio di dati Hello World alla connessione tramite l'API REST con Content-Type=text/plain

  • Un semplice client WebSocket riceve un frame WebSocket di testo con dati: Hello World;

  • Un client PubSub WebSocket riceve:

    {
    "type": "message",
    "from": "server",
    "dataType" : "text",
    "data": "Hello World", 
}

Caso 2: Invio di dati { "Hello" : "World"} alla connessione tramite l'API REST con Content-Type=application/json

  • Un semplice client WebSocket riceve un frame WebSocket di testo con dati stringati: { "Hello" : "World"}.

  • Un client PubSub WebSocket riceve:

    {
    "type": "message",
    "from": "server",
    "dataType" : "json",
    "data": {
        "Hello": "World"
    }
}

Se l'API REST invia una stringa Hello World usando application/json il tipo di contenuto, il client WebSocket semplice riceve una stringa JSON, di cui viene "Hello World" eseguito il wrapping con virgolette doppie (").

Caso 3: Invio di dati binari alla connessione tramite l'API REST con Content-Type=application/octet-stream

  • Un semplice client WebSocket riceve un frame WebSocket binario con i dati binari.

  • Un client PubSub WebSocket riceve:

    {
    "type": "message",
    "from": "server",
    "dataType" : "binary",
    "data": "<base64_binary>"
}

Risposta di sistema

Il servizio Web PubSub invia messaggi correlati al sistema ai client.

Connesso

Messaggio inviato al client quando il client si connette correttamente:

{
    "type": "system",
    "event": "connected",
    "userId": "user1",
    "connectionId": "abcdefghijklmnop",
}

Disconnesso

Messaggio inviato al client quando il server chiude la connessione o quando il servizio rifiuta il client.

{
    "type": "system",
    "event": "disconnected",
    "message": "reason"
}

Passaggi successivi

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

Esercitazione: Pubblicare e sottoscrivere messaggi in Pubblicazione Web di Azure

Esercitazione: Creare una chatroom semplice con PubSub Web di Azure

Esercitazione: Usare un sottoprotocolo supportato dal servizio per lo streaming client

Esercitazione: Creare chat serverless con Funzioni di Azure e Web PubSub

Esercitazione: Configurare un listener di eventi

Riprodurre con demo live

Esplorare altri esempi di PubSub Web di Azure