Sottoprotocolo Web PubSub Reliable JSON WebSocket di Azure

Il sottoprotocolo JSON WebSocket, json.reliable.webpubsub.azure.v1, consente lo scambio estremamente affidabile di messaggi di pubblicazione/sottoscrizione direttamente tra i client tramite il servizio senza un round trip al server upstream.

Questo documento descrive il sottoprotocolo json.reliable.webpubsub.azure.v1.

Quando le connessioni client WebSocket vengono interrotte a causa di problemi di rete intermittenti, i messaggi possono andare persi. In un sistema pub/secondario i server di pubblicazione vengono separati dai sottoscrittori e potrebbero non rilevare la connessione o la perdita di messaggi di un sottoscrittore.

Per risolvere i problemi di rete intermittenti e mantenere un recapito affidabile dei messaggi, è possibile usare il sottoprotocolo WebPubSub json.reliable.webpubsub.azure.v1 di Azure per creare un client WebSocket Reliable PubSocket.

Un client Reliable PubSub WebSocket può:

• recuperare una connessione da problemi di rete intermittenti.
• recuperare dalla perdita di messaggi.
• partecipare a un gruppo usando le richieste di join.
• lasciare un gruppo usando le richieste di uscita.
• pubblicare i messaggi direttamente in un gruppo usando le richieste di pubblicazione.
• indirizzare i messaggi direttamente ai gestori eventi upstream usando le richieste di eventi.

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

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

Vedere Come creare client affidabili per implementare la riconnessione e l'affidabilità dei messaggi per i client del server di pubblicazione e dei sottoscrittori.

Quando il client usa questo sottoprotocolo, i frame di dati in uscita e in ingresso 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:

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.

Sequenza Ack

Formato:

{
    "type": "sequenceAck",
    "sequenceId": "<sequenceId>",
}

Il client Reliable PubSocket WebSocket deve inviare un messaggio sequence ack dopo che riceve un messaggio dal servizio. Per altre informazioni, vedere Come creare client affidabili

• sequenceId è un numero uint64 incrementale del messaggio ricevuto.

Risposte

I messaggi ricevuti dal client possono essere diversi tipi: ack, message, systeme pong. I messaggi con tipo message hanno sequenceId la proprietà . Il client deve inviare un oggetto Sequence Ack al servizio dopo che riceve un messaggio.

Risposta Ack

Quando la richiesta contiene ackId, il servizio restituirà una risposta ack per questa richiesta. L'implementazione client deve gestire questo meccanismo ack, inclusa l'attesa della risposta ack usando un'operazione asyncawait e avere un gestore di timeout quando la risposta ack non viene ricevuta durante 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. Solo quando success il false client legge da error.

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. Messaggio di risposta da un gruppo:

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

2. Messaggio di risposta dal server:

   {
       "sequenceId": 1,
       "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 il messaggio in JSON:

  {
      "sequenceId": 1,
      "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 il messaggio in JSON:

  {
      "sequenceId": 1,
      "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 la stringa "Hello World" JSON di cui è stato eseguito il wrapping in ".

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 il messaggio in JSON:

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

Risposta di sistema

Il servizio Web PubSub può restituire risposte correlate al sistema al client.

Risposta pong

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

Formato:

{
    "type": "pong",
}

Connesso

Risposta alla richiesta di connessione client:

{
    "type": "system",
    "event": "connected",
    "userId": "user1",
    "connectionId": "abcdefghijklmnop",
    "reconnectionToken": "<token>"
}

connectionId e reconnectionToken vengono usati per la riconnessione. Effettuare la richiesta di connessione con l'URI per la riconnessione:

wss://<service-endpoint>/client/hubs/<hub>?awps_connection_id=<connectionId>&awps_reconnection_token=<reconnectionToken>

Per altre informazioni, vedere Ripristino connessione

Disconnesso

Risposta quando il server chiude la connessione o quando il servizio rifiuta la connessione client:

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

Passaggi successivi

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