Condividi tramite

Estensione CloudEvents per il listener di eventi PubSub di Azure con il protocollo AMQP

  • Articolo

Il servizio Web PubSub di Azure descrive gli eventi client come CloudEvents. CloudEvents è una specifica per descrivere i dati degli eventi in formati comuni per garantire l'interoperabilità tra servizi, piattaforme e sistemi.

I listener di eventi del servizio sono in ascolto degli eventi client. Hub eventi è attualmente l'unico endpoint del listener di eventi supportato, il cui protocollo primario è AMQP (Advanced Message Queueing Protocol). Il servizio Web PubSub usa l'associazione del protocollo AMQP CloudEvents per eseguire il mapping di CloudEvents ai messaggi AMQP.

I dati inviati dal servizio al server sono sempre in formato CloudEvents binary .

Estensione dell'attributo Web PubSub CloudEvents

Questa estensione definisce gli attributi usati da Web PubSub per ogni evento prodotto.

La tabella seguente contiene attributi di mapping alla sezione delle proprietà standard di un messaggio AMQP.

Nome Descrizione Esempio
content-type Tipo MIME RFC-2046 per il corpo del messaggio application/json
message-id Definisce in modo univoco un messaggio in un servizio Web PubSub, nel formato "{connection-id}/{un numero intero generato dal servizio}" 0bd83792-2a0c-48d3-9fbd-df63aa2ed9db/1

La tabella seguente contiene tutti gli attributi CloudEvents mappati alla sezione delle proprietà dell'applicazione di un messaggio AMQP. Ogni nome di attributo è preceduto da cloudEvents:.

Nome Descrizione Esempio
specversion La versione delle specifiche degli eventi cloud è sempre 1.0 1.0
source Indica l'hub e l'ID di connessione da cui proviene l'evento, nel formato "/hubs/{hub}/client/{connectionId}" /hubs/chat/client/0bd83792-2a0c-48d3-9fbd-df63aa2ed9db
id Intero generato dal servizio, univoco negli eventi dalla stessa connessione client 1
awpsversion Gli eventi cloud versione della specifica PubSub di Azure sono sempre 1.0 1.0
hub Nome dell'hub da cui proviene l'evento chat
eventname Il nome dell'evento connected
type Tipo di evento azure.webpubsub.sys.connect
connectionid ID della connessione client 0bd83792-2a0c-48d3-9fbd-df63aa2ed9db
time Ora in cui il servizio invia l'evento, nel formato "aa-MM-ggTHH:mm:ssZ" 2021-01-01T00:00:00Z
userid* ID dell'utente user1
subprotocol* Nome sottoprotocolo json.webpubsub.azure.v1
connectionstate* Definisce lo stato per la connessione. È possibile reimpostare il valore nell'intestazione della risposta dei gestori eventi. Per altre informazioni sullo stato della connessione, vedere Attributi Web PubSub CloudEvents. anystring

Il valore "*" che segue il nome dell'attributo indica che l'attributo è presente solo quando il valore non è null o vuoto.

evento

Questa sezione mostra il corpo del messaggio AMQP con i valori dell'attributo che dipendono da un tipo di evento client specifico. I valori degli attributi che non dipendono da un tipo di evento client vengono omessi.

Evento di sistema connected

  • content-type: application/json
  • cloudEvents:type: azure.webpubsub.sys.connected
  • cloudEvents:eventname: connected

Il corpo del messaggio è sempre JSON vuoto.

{}

Evento di sistema disconnected

  • content-type: application/json
  • cloudEvents:type: azure.webpubsub.sys.disconnected
  • cloudEvents:eventname: disconnected

Il corpo del messaggio contiene il motivo per cui il client è disconnesso.

{"reason":"{Reason}"}

Eventi message utente per i client WebSocket semplici

  • content-type: application/octet-stream per frame binario; text/plain per cornice di testo;
  • cloudEvents:type: azure.webpubsub.user.message

Il corpo del messaggio è ciò che il client invia.

Evento personalizzato dell'utente {custom_event} per i client WebSocket PubSocket

  • content-type: application/octet-stream per frame binario; application/json per frame JSON; text/plain per cornice di testo; application/x-protobuf per cornice Protobuf;
  • cloudEvents:type: azure.webpubsub.user.<event_name>

I casi seguenti illustrano come inviare eventi con tipi di contenuto di dati diversi e i corpi dei messaggi AMQP ricevuti.

Caso 1: inviare un evento con dati di testo:

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

Corpo del messaggio AMQP ricevuto:

text data

Caso 2: inviare un evento con dati JSON:

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

Corpo del messaggio AMQP ricevuto:

{
    "hello": "world"
}

Caso 3: inviare un evento con dati binari:

{
    "type": "event",
    "event": "<event_name>",
    "dataType": "binary",
    "data": "aGVsbG8gd29ybGQ=" // base64 encoded binary
}

Corpo del messaggio AMQP ricevuto:

<binary data>