Condividi tramite

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ò unirsi o abbandonare 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.

Ping

Formato:

{
    "type": "ping",
}

Il client può inviare un ping messaggio al servizio per consentire al servizio Web PubSub di rilevare la durata del client.

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.
  • pong - La risposta a un ping messaggio.

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 async await 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.

Risposta pong

Il servizio Web PubSub invia un pong messaggio al client quando riceve un ping messaggio dal client.

Formato:

{
    "type": "pong",
}

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 compilare un'applicazione personalizzata:

Esercitazione: Pubblicare e sottoscrivere messaggi in Azure Web PubSub

Esercitazione: Creare una chatroom semplice con Azure Web PubSub

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

Esercitazione: Compilare una chat serverless con Funzioni di Azure e Web PubSub

Esercitazione: Configurare un listener di eventi

Riprodurre con demo live

Esplorare altri esempi di Azure Web PubSub