Estensione CloudEvents per il gestore eventi PubSub di Azure con protocollo HTTP

Il servizio Web PubSub recapita gli eventi client al webhook upstream usando l'associazione del protocollo HTTP CloudEvents.

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

• Convalida webhook
• Estensione dell'attributo Web PubSub CloudEvents
• Eventi
  • Eventi di blocco
    • Evento di sistema connect
    • Eventi degli utenti
  • Sbloccare gli eventi
    • Evento di sistema connected
    • Evento di sistema disconnected

Convalida del webhook

La convalida del webhook segue CloudEvents. La richiesta contiene WebHook-Request-Origin: xxx.webpubsub.azure.com sempre nell'intestazione.

Se e solo se la destinazione di recapito consente il recapito degli eventi, deve rispondere alla richiesta includendo WebHook-Allowed-Origin l'intestazione, ad esempio:

WebHook-Allowed-Origin: *

Oppure:

WebHook-Allowed-Origin: xxx.webpubsub.azure.com

Per il momento, WebHook-Request-Rate e WebHook-Request-Callback non sono supportati.

Estensione dell'attributo Web PubSub CloudEvents

È stato anche notato che la specifica HTTP sta ora seguendo un modello simile non suggerendo più che le intestazioni HTTP di estensione siano precedute da X-.

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

Attributi

Nome	Tipo	Descrizione	Esempio
userId	string	L'utente ha autenticato la connessione
hub	string	L'hub a cui appartiene la connessione
connectionId	string	ConnectionId è univoco per la connessione client
eventName	string	Nome dell'evento senza prefisso
subprotocol	string	Sottoprotocolo usato dal client se presente
connectionState	string	Definisce lo stato per la connessione. È possibile usare la stessa intestazione di risposta per reimpostare il valore dello stato. Non sono consentite più connectionState intestazioni. Codificare in base64 il valore stringa se contiene caratteri complessi all'interno, ad esempio per base64(jsonString) passare un oggetto complesso usando questo attributo.
signature	string	Firma per il webhook upstream da convalidare se la richiesta in ingresso proviene dall'origine prevista. Il servizio calcola il valore usando sia la chiave di accesso primaria che la HMAC chiave di accesso secondaria come chiave: Hex_encoded(HMAC_SHA256(accessKey, connectionId)). L'upstream deve verificare se la richiesta è valida prima di elaborarla.

evento

Esistono due tipi di eventi. Uno è il blocco degli eventi che il servizio attende che la risposta dell'evento continui. Uno è sbloccare gli eventi che il servizio non attende la risposta di tale evento prima di elaborare il messaggio successivo.

• Eventi di blocco
  • Evento di sistema connect
  • Eventi degli utenti
• Sbloccare gli eventi
  • Evento di sistema connected
  • Evento di sistema disconnected

Evento di sistema connect

• ce-type: azure.webpubsub.sys.connect
• Content-Type: application/json

Formato richiesta:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.sys.connect
ce-source: /hubs/{hub}/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}
ce-eventName: connect

{
    "claims": {},
    "query": {},
    "headers": {},
    "subprotocols": [],
    "clientCertificates": [
        {
            "thumbprint": "ABC"
        }
    ]
}

Formato risposta riuscita:

• Intestazione: se questa intestazione ce-connectionStateesiste, lo stato della connessione verrà aggiornato al valore dell'intestazione. Solo gli eventi di blocco possono aggiornare lo stato della connessione. L'esempio seguente usa la stringa JSON con codifica Base64 per archiviare lo stato complesso per la connessione.

• Codice di stato:

  • 204: operazione riuscita, senza contenuto.
  • 200: esito positivo, il contenuto DEVE essere un formato JSON, con le proprietà seguenti consentite:

    • subprotocols

      L'evento connect inoltra le informazioni di sottoprotocolo e autenticazione a Upstream dal client. Il servizio Web PubSub usa il codice di stato per determinare se la richiesta verrà aggiornata al protocollo WebSocket.

      Se la richiesta contiene la subprotocols proprietà , il server deve restituire un sottoprotocolo supportato. Se il server non vuole usare alcun sottoprotocolo, non deve inviare la subprotocol proprietà in risposta. L'invio di un'intestazione vuota non è valido.

    • userId: {auth-ed user ID}

      Poiché il servizio consente connessioni anonime, è connect responsabilità dell'evento indicare al servizio l'ID utente della connessione client. Il servizio legge l'ID utente dal payload userId della risposta, se presente. La connessione viene eliminata se l'ID utente non può essere letto dalle attestazioni della richiesta né dal connect payload della risposta dell'evento.

    • groups: {groups to join}

      La proprietà consente all'utente di aggiungere questa connessione a uno o più gruppi. In questo modo, non è necessario avere un'altra chiamata per aggiungere questa connessione a un gruppo.

    • roles: {roles the client has}

      La proprietà consente al webhook upstream di autorizzare il client. Esistono ruoli diversi per concedere le autorizzazioni iniziali per i client WebSocket PubSub. I dettagli sulle autorizzazioni sono descritti in Autorizzazioni client.

HTTP/1.1 200 OK
ce-connectionState: eyJrZXkiOiJhIn0=

{
    "groups": [],
    "userId": "",
    "roles": [],
    "subprotocol": ""
}

Formato della risposta di errore:

• 4xx: errore, la risposta da Upstream verrà restituita come risposta per la richiesta client.

HTTP/1.1 401 Unauthorized

Evento di sistema connected

Il servizio chiama upstream quando il client completa l'handshake WebSocket ed è connesso correttamente.

• ce-type: azure.webpubsub.sys.connected
• Content-Type: application/json
• ce-connectionState: eyJrZXkiOiJhIn0=

Il corpo della richiesta è JSON vuoto.

Formato richiesta:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.sys.connected
ce-source: /hubs/{hub}/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}
ce-eventName: connected
ce-subprotocol: abc
ce-connectionState: eyJrZXkiOiJhIn0=

{}

Formato risposta:

2xx: risposta riuscita.

connected è un evento asincrono, quando il codice di stato della risposta non riesce, il servizio registra un errore.

HTTP/1.1 200 OK

Evento di sistema disconnected

disconnectedl'evento viene sempre attivato quando la richiesta client viene completata se l'evento connect restituisce 2xx il codice di stato.

• ce-type: azure.webpubsub.sys.disconnected
• Content-Type: application/json

Formato richiesta:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.sys.disconnected
ce-source: /hubs/{hub}/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}
ce-eventName: disconnected
ce-subprotocol: abc
ce-connectionState: eyJrZXkiOiJhIn0=

{
    "reason": "{Reason}"
}

• reason

  reason Descrive il motivo per cui il client si disconnette.

Formato risposta:

2xx: risposta riuscita.

disconnected è un evento asincrono, quando il codice di stato della risposta non riesce, il servizio registra un errore.

HTTP/1.1 200 OK

Evento message utente per i client WebSocket semplici

Il servizio richiama il gestore eventi upstream per ogni frame di messaggio WebSocket.

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

UserPayload è ciò che il client invia.

Formato richiesta:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/octet-stream | text/plain | application/json
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.message
ce-source: /hubs/{hub}/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}
ce-eventName: message
ce-connectionState: eyJrZXkiOiJhIn0=

UserPayload

Formato risposta riuscita

• Codice di stato
  • 204: operazione riuscita, senza contenuto.
  • 200: esito positivo, il formato dell'oggetto UserResponsePayload dipende dall'oggetto Content-Type della risposta.
• Content-Type: application/octet-stream per frame binario; text/plain per cornice di testo;
• Intestazione Content-Type: application/octet-stream per frame binario; text/plain per cornice di testo;
• Intestazione: se questa intestazione ce-connectionStateesiste, lo stato della connessione verrà aggiornato al valore dell'intestazione. Solo gli eventi di blocco possono aggiornare lo stato della connessione. L'esempio seguente usa la stringa JSON con codifica Base64 per archiviare lo stato complesso per la connessione.

Content-Type Quando è application/octet-stream, il servizio invia UserResponsePayload al client tramite binary frame WebSocket. Content-Type Quando è text/plain, il servizio invia UserResponsePayload al client tramite text frame WebSocket.

HTTP/1.1 200 OK
Content-Type: application/octet-stream (for binary frame) or text/plain (for text frame)
Content-Length: nnnn
ce-connectionState: eyJrZXkiOiJhIn0=

UserResponsePayload

Formato della risposta di errore

Quando il codice di stato non riesce, viene considerato come risposta di errore. La connessione viene eliminata se il codice di stato della message risposta non riesce.

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

Il servizio chiama il webhook del gestore eventi per ogni messaggio di evento personalizzato valido.

Caso 1: inviare un evento con dati di testo:

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

Cosa riceve il gestore eventi upstream come indicato di seguito, per la Content-Type richiesta text/plain HTTP CloudEvents dataType=text

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>
ce-subprotocol: json.webpubsub.azure.v1
ce-connectionState: eyJrZXkiOiJhIn0=

text data

Caso 2: inviare un evento con dati JSON:

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

Cosa riceve il gestore eventi upstream come indicato di seguito, per la Content-Type richiesta application/json HTTP CloudEvents dataType=json

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>
ce-subprotocol: json.webpubsub.azure.v1
ce-connectionState: eyJrZXkiOiJhIn0=

{
    "hello": "world"
}

Caso 3: inviare un evento con dati binari:

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

Cosa riceve il gestore eventi upstream come indicato di seguito, per la Content-Type richiesta application/octet-stream HTTP CloudEvents dataType=binary

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>
ce-subprotocol: json.webpubsub.azure.v1

<binary data>

Formato risposta riuscita

HTTP/1.1 200 OK
Content-Type: application/octet-stream | text/plain | application/json
Content-Length: nnnn

UserResponsePayload

• Codice di stato
  • 204: operazione riuscita, senza contenuto.
  • 200: esito positivo, i dati inviati al client WebSocket PubSub dipendono da Content-Type;
• Intestazione: se questa intestazione ce-connectionStateesiste, lo stato della connessione verrà aggiornato al valore dell'intestazione. Solo gli eventi di blocco possono aggiornare lo stato della connessione. L'esempio seguente usa la stringa JSON con codifica Base64 per archiviare lo stato complesso per la connessione.
• Quando Header è application/octet-stream, il servizio restituisce UserResponsePayloadContent-Type al client usando dataType come binary con il payload con codifica base64. Risposta di esempio:

  {
      "type": "message",
      "from": "server",
      "dataType": "binary",
      "data" : "aGVsbG8gd29ybGQ="
  }
  

• Content-Type Quando è text/plain, il servizio invia UserResponsePayload al client usando dataType come text con la stringa di payload.
• Content-Type Quando è application/json, il servizio invia UserResponsePayload al client usandojsondataType=con data il token valore come corpo del payload della risposta.

Formato della risposta di errore

Quando il codice di stato non riesce, viene considerato come risposta di errore. La connessione viene eliminata se il codice di stato della {custom_event} risposta non riesce.

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