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.
• Trasmetti i messaggi direttamente a un gruppo usando richieste di streaming.
• 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.

Inizia a trasmettere messaggi

Per avviare un stream di gruppo, invia una sendToGroup richiesta alla stream proprietà. Una richiesta di avvio di flusso non contiene data, dataType, o ackId.

Formato:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "noEcho": true|false,
    "stream": {
        "streamId": "<stream_id>",
        "idleTimeoutMs": 300000
    }
}

• stream.streamId è l'identificatore del flusso logico. Deve essere una stringa non vuota e deve essere unica tra i flussi attivi sulla stessa connessione client. Si consiglia alle librerie client di generare un valore globalmente unico, come un GUID o un UUID.
• stream.idleTimeoutMs è facoltativo. Se specificato, deve essere maggiore di 0. Se omesso, il valore predefinito del servizio è 300000 millisecondo. Il valore è un timeout inattivo, non una durata totale del flusso di streaming. Invia dati del stream, invia un keep live, oppure termina lo stream prima che scada questo timeout, quando l'applicazione deve mantenere lo stream aperto.
• noEcho è facoltativo. Se impostato su true, i messaggi di stream non vengono richiamati alla stessa connessione. Se non è impostato, il valore predefinito è false.

Quando lo stream viene accettato, il client riceve una risposta di ack dello stream impostata expectedSequenceId a 1.

Invia dati in streaming

Per inviare dati di flusso, invia una streamData richiesta con streamId, streamSequenceId, dataType, e data.

Formato:

{
    "type": "streamData",
    "streamId": "<stream_id>",
    "streamSequenceId": 1,
    "dataType" : "json|text|binary",
    "data": {}
}

• streamId identifica un flusso attivo sulla stessa connessione client.
• streamSequenceId è un numero uint64 positivo. Il primo frammento di dati in un flusso usa 1, e ogni frammento di dato successivo per lo stesso streamId aumenta esattamente 1di .
• dataType può essere impostato su json, text, o binary, con le stesse regole di codifica dei dati di pubblicazione dei messaggi.

Per mantenere un flusso attivo senza fornire dati agli abbonati, invia una streamData richiesta con solo type e streamId.

{
    "type": "streamData",
    "streamId": "<stream_id>"
}

Fine dei messaggi in streaming

Per terminare una diretta, invia una streamEnd richiesta.

Formato:

{
    "type": "streamEnd",
    "streamId": "<stream_id>"
}

Per concludere uno stream con un errore definito dall'applicazione, includere la proprietà opzionale error .

{
    "type": "streamEnd",
    "streamId": "<stream_id>",
    "error": {
        "message": "<error_detail>",
        "userErrorCode": "<application_error_code>"
    }
}

• error.message è un messaggio di errore opzionale leggibile dagli umani.
• error.userErrorCode è un codice di errore opzionale definito dall'applicazione.

Quando lo stream è chiuso, l'editore riceve una risposta di stream closed.

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 di diversi tipi: ack, message, system, pong, streamAck, streamNack, e streamClosed. 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 al messaggio in streaming

Quando un messaggio appartiene a un stream, il messaggio di gruppo contiene una stream proprietà. Il reliable sequenceId remains connection-scoped ed è diverso da stream.streamSequenceId.

{
    "sequenceId": 1,
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType": "json|text|binary",
    "data": {},
    "fromUserId": "abc",
    "stream": {
        "streamId": "<stream_id>",
        "streamSequenceId": 1,
        "endOfStream": true,
        "error": {
            "name": "IdleTimeout|InternalServerError|Forbidden|Cancelled|UserError",
            "message": "<error_detail>",
            "userErrorCode": "<application_error_code>"
        }
    }
}

• stream.streamId è l'identificatore logico del flusso.
• stream.streamSequenceId è il numero di sequenza del messaggio nel flusso.
• stream.endOfStream è facoltativo. Quando impostato su true, il messaggio è il messaggio terminale del flusso.
• stream.error è opzionale ed è presente solo quando il flusso termina con un errore. userErrorCode è presente solo per UserError.

Risposta al flusso

Il servizio invia una streamAck risposta per confermare i dati di flusso accettati e per segnalare il prossimo ID della sequenza di flusso che si aspetta.

Formato:

{
    "type": "streamAck",
    "streamId": "<stream_id>",
    "expectedSequenceId": 2
}

Risposta al nack del corso d'acqua

Il servizio invia una streamNack risposta per un errore di flusso ritentabile.

Formato:

{
    "type": "streamNack",
    "streamId": "<stream_id>",
    "expectedSequenceId": 2,
    "name": "InvalidSequenceId|TransientError",
    "message": "<error_detail>"
}

Risposta chiusa del flusso

Il servizio invia una streamClosed risposta quando lo stream lato publisher viene chiuso.

Formato:

{
    "type": "streamClosed",
    "streamId": "<stream_id>",
    "error": {
        "name": "StreamNotFound|Forbidden|BadRequest|InternalServerError|IdleTimeout",
        "message": "<error_detail>"
    }
}

La error proprietà viene omessa quando il flusso è chiuso normalmente.

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: