Gestionnaires Azure Web Pubsub CloudEvents pour Express

  • Article

Le service Azure Web PubSub est un service géré Azure qui aide les développeurs à créer facilement des applications web avec des fonctionnalités en temps réel et un modèle publication-abonnement. Tout scénario qui nécessite une messagerie de type publication-abonnement en temps réel entre un serveur et des clients ou entre des clients peut avoir recours au service Azure Web PubSub. Les fonctionnalités en temps réel traditionnelles qui demandent souvent d’interroger un serveur ou d’envoyer des requêtes HTTP peuvent aussi utiliser le service Azure Web PubSub.

Lorsqu’une connexion WebSocket se connecte, le service Web PubSub transforme le cycle de vie de la connexion et les messages en événements au format CloudEvents. Cette bibliothèque fournit un intergiciel (middleware) express pour gérer les événements représentant le cycle de vie et les messages de la connexion WebSocket, comme indiqué dans le diagramme ci-dessous :

cloudevents

Les détails des termes utilisés ici sont décrits dans la section Concepts clés.

Code source | Package (NPM) | Documentation de référence API | Documentation de produits | Exemples

Prise en main

Environnements actuellement pris en charge

Prérequis

1. Installez le package @azure/web-pubsub-express

npm install @azure/web-pubsub-express

2. Créez un 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}`)
);

Concepts clés

Connexion

Une connexion, également appelée client ou connexion client, représente une connexion WebSocket individuelle connectée au service Web PubSub. Une fois la connexion réussie, un ID de connexion unique est affecté à cette connexion par le service Web PubSub.

Hub

Un hub est un concept logique pour un ensemble de connexions client. En règle générale, vous utilisez un hub dans un seul but, par exemple un hub de conversations ou un hub de notifications. Lorsqu’une connexion client est créée, elle se connecte à un hub et, pendant toute sa durée de vie, elle appartient à ce hub. Différentes applications peuvent partager un service Azure Web PubSub en utilisant différents noms de hubs.

Groupe

Un groupe est un sous-ensemble de connexions au hub. Vous pouvez ajouter une connexion cliente à un groupe, ou la supprimer du groupe, quand vous le souhaitez. Par exemple, quand un client rejoint une salle de conversation ou quand il la quitte, cette salle de conversation peut être considérée comme un groupe. Un client peut rejoindre plusieurs groupes, et un groupe peut contenir plusieurs clients.

Utilisateur

Les connexions à Web PubSub ne peuvent appartenir qu’à un seul utilisateur. Un utilisateur peut avoir plusieurs connexions. C’est le cas, par exemple, quand un seul utilisateur est connecté sur plusieurs appareils ou plusieurs onglets de navigateur.

Événements du client

Les événements sont créés pendant le cycle de vie d’une connexion cliente. Par exemple, une connexion cliente WebSocket simple crée un événement connect lorsqu’il tente de se connecter au service, un événement connected quand il s’est correctement connecté au service, un événement message lorsqu’il envoie des messages au service et à un événement disconnected lorsqu’il se déconnecte du service.

Gestionnaire d'événements

Le gestionnaire d’événements contient la logique permettant de gérer les événements du client. Le gestionnaire d’événements doit être inscrit et configuré dans le service via le portail ou Azure CLI au préalable. L’emplacement d’hébergement de la logique du gestionnaire d’événements est généralement considéré comme côté serveur.

Exemples

Gérer la demande connect et assigner <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}`)
);

Autoriser uniquement les points de terminaison spécifiés

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}`)
);

Définir le chemin du gestionnaire d’événements personnalisé

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}`)
);

Définir et lire l’état de la connexion

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}`)
);

Dépannage

Activer les journaux d’activité

Vous pouvez définir la variable d’environnement suivante pour afficher les journaux de débogage quand vous utilisez cette bibliothèque.

  • Obtention des journaux de débogage à partir de la bibliothèque cliente Signalr
export AZURE_LOG_LEVEL=verbose

Pour obtenir des instructions plus détaillées sur l’activation des journaux, consultez les documents relatifs au package @azure/logger.

Trace dynamique

Utilisez Live Trace du portail de service Web PubSub pour afficher le trafic.

Étapes suivantes

Consultez le répertoire d’exemples pour obtenir des exemples détaillés sur l’utilisation de cette bibliothèque.

Contribution

Si vous souhaitez contribuer à cette bibliothèque, lisez le guide de contribution pour en savoir plus sur la génération et le test du code.