Condividi tramite

Gestori di Azure Web PubSub CloudEvents per Express

  • Articolo

Il servizio Web PubSub di Azure è un servizio gestito da Azure che consente agli sviluppatori di creare facilmente applicazioni Web con funzionalità in tempo reale e modello di sottoscrizione di pubblicazione. Qualsiasi scenario che richiede la messaggistica di pubblicazione in tempo reale tra server e client o tra i client può usare il servizio PubSub Web di Azure. Le funzionalità tradizionali in tempo reale che spesso richiedono il polling dal server o l'invio di richieste HTTP possono anche usare il servizio Web PubSub di Azure.

Quando una connessione WebSocket si connette, il servizio PubSub Web trasforma il ciclo di vita della connessione e i messaggi in eventi nel formato CloudEvents. Questa libreria fornisce un middleware express per gestire gli eventi che rappresentano il ciclo di vita e i messaggi della connessione WebSocket, come illustrato nel diagramma seguente:

cloudevents

I dettagli sui termini usati qui sono descritti nella sezione Concetti chiave .

Codice | sorgentePacchetto (NPM) | Documentazione di | riferimento sulle APIDocumentazione | del prodottoCampioni

Introduzione

Ambienti attualmente supportati

Prerequisiti

1. Installare il @azure/web-pubsub-express pacchetto

npm install @azure/web-pubsub-express

2. Creare un oggetto WebPubSubEventHandler

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat");

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(`Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`)
);

Concetti chiave

Connessione

Una connessione, nota anche come client o connessione client, rappresenta una singola connessione WebSocket connessa al servizio Web PubSub. Quando si è connessi correttamente, viene assegnato un ID di connessione univoco a questa connessione dal servizio Web PubSub.

Hub

Un hub è un concetto logico per un set di connessioni client. In genere si usa un hub per uno scopo, ad esempio un hub chat o un hub di notifica. Quando viene creata una connessione client, si connette a un hub e durante la sua durata appartiene a tale hub. Diverse applicazioni possono condividere un servizio Web PubSub di Azure usando nomi di hub diversi.

Gruppo

Un gruppo è un subset di connessioni all'hub. È possibile aggiungere una connessione client a un gruppo o rimuovere la connessione client dal gruppo, in qualsiasi momento. Ad esempio, quando un client partecipa a una chat room o quando un client lascia la chat room, questa chat room può essere considerata un gruppo. Un client può partecipare a più gruppi e un gruppo può contenere più client.

Utente

Le connessioni a Web PubSub possono appartenere a un utente. Un utente potrebbe avere più connessioni, ad esempio quando un singolo utente è connesso tra più dispositivi o più schede del browser.

Eventi client

Gli eventi vengono creati durante il ciclo di vita di una connessione client. Ad esempio, una semplice connessione client WebSocket crea un connect evento quando tenta di connettersi al servizio, un evento quando è stato connesso correttamente al servizio, connected un message evento quando invia messaggi al servizio e un disconnected evento quando disconnette dal servizio.

Gestore evento

Il gestore eventi contiene la logica per gestire gli eventi client. Il gestore eventi deve essere registrato e configurato nel servizio tramite il portale o l'interfaccia della riga di comando di Azure in anticipo. Il posto in cui ospitare la logica del gestore eventi viene in genere considerato come lato server.

Esempi

Gestire la connect richiesta e assegnare <userId>

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat", {
  handleConnect: (req, res) => {
    // auth the connection and set the userId of the connection
    res.success({
      userId: "<userId>"
    });
  },
  allowedEndpoints: ["https://<yourAllowedService>.webpubsub.azure.com"]
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(`Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`)
);

Consenti solo gli endpoint specificati

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat", {
  allowedEndpoints: [
    "https://<yourAllowedService1>.webpubsub.azure.com",
    "https://<yourAllowedService2>.webpubsub.azure.com"
  ]
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(`Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`)
);

Impostare il percorso del gestore eventi personalizzato

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat", {
  path: "customPath1"
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  // Azure WebPubSub Upstream ready at http://localhost:3000/customPath1
  console.log(`Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`)
);

Impostare e leggere lo stato di connessione

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");

const handler = new WebPubSubEventHandler("chat", {
  handleConnect(req, res) {
    // You can set the state for the connection, it lasts throughout the lifetime of the connection
    res.setState("calledTime", 1);
    res.success();
  },
  handleUserEvent(req, res) {
    var calledTime = req.context.states.calledTime++;
    console.log(calledTime);
    // You can also set the state here
    res.setState("calledTime", calledTime);
    res.success();
  }
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(`Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`)
);

Risoluzione dei problemi

Abilitare i log

È possibile impostare la variabile di ambiente seguente per ottenere i log di debug quando si usa questa libreria.

  • Recupero dei log di debug dalla libreria client SignalR
export AZURE_LOG_LEVEL=verbose

Per istruzioni più dettagliate su come abilitare i log, è possibile esaminare la documentazione del pacchetto @azure/logger.

Traccia dinamica

Usare Live Trace dal portale del servizio Web PubSub per visualizzare il traffico live.

Passaggi successivi

Per esempi dettagliati su come usare questa libreria, vedere la directory degli esempi .

Contributo

Per contribuire a questa libreria, leggere la guida ai contributi per altre informazioni su come compilare e testare il codice.