Azure Web PubSub CloudEvents-handlers voor Express

De Azure Web PubSub-service is een door Azure beheerde service waarmee ontwikkelaars eenvoudig webtoepassingen kunnen bouwen met realtime-functies en een patroon voor publiceren/abonneren. Elk scenario waarin realtime berichtenuitwisseling voor publiceren-abonneren tussen een server en clients, of onderling tussen clients, nodig is, kan de Azure Web PubSub-service gebruiken. Traditionele realtime-functies die vaak polling vereisen van de server of het verzenden van HTTP-aanvragen, kunnen ook gebruikmaken van de Azure Web PubSub-service.

Wanneer een WebSocket-verbinding tot stand komt, transformeert de Web PubSub-service de levenscyclus van de verbinding en berichten in gebeurtenissen in CloudEvents-indeling. Deze bibliotheek biedt een snelle middleware voor het afhandelen van gebeurtenissen die de levenscyclus en berichten van de WebSocket-verbinding vertegenwoordigen, zoals wordt weergegeven in het onderstaande diagram:

Details over de hier gebruikte termen worden beschreven in de sectie Sleutelconcepten .

Broncode | Pakket (NPM) | API-referentiedocumentatie | Productdocumentatie | Voorbeelden

Aan de slag

Momenteel ondersteunde omgevingen

• LTS-versies van Node.js
• Express-versie 4.x.x of hoger

Prerequisites

• Een Azure-abonnement.
• Een bestaand Azure Web PubSub-eindpunt.

1. Installeer het @azure/web-pubsub-express pakket

npm install @azure/web-pubsub-express

2. Maak een WebPubSubEventHandler

import { WebPubSubEventHandler } from "@azure/web-pubsub-express";
import express from "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}`),
);

Belangrijke concepten

Verbinding

Een verbinding, ook wel client of clientverbinding genoemd, vertegenwoordigt een individuele WebSocket-verbinding die verbonden is met de Web PubSub-dienst. Wanneer succesvol verbonden, wordt een unieke verbindings-ID aan deze verbinding toegekend door de Web PubSub-service.

Knooppunt

Een hub is een logisch concept voor een set clientverbindingen. Meestal gebruik je één hub voor één doel, bijvoorbeeld een chathub of een notificatiehub. Wanneer een clientverbinding wordt gemaakt, maakt deze verbinding met een hub en gedurende de levensduur behoort deze tot die hub. Verschillende toepassingen kunnen één Azure Web PubSub-service delen met behulp van verschillende hubnamen.

Groep

Een groep is een subset van verbindingen met de hub. U kunt een clientverbinding toevoegen aan een groep of de clientverbinding verwijderen uit de groep, op elk gewenst moment. Wanneer een client bijvoorbeeld deelneemt aan een chatruimte of wanneer een client de chatruimte verlaat, kan deze chatruimte worden beschouwd als een groep. Een client kan lid worden van meerdere groepen en een groep kan meerdere clients bevatten.

User

Verbindingen met Web PubSub kunnen tot één gebruiker behoren. Een gebruiker kan meerdere verbindingen hebben, bijvoorbeeld wanneer één gebruiker is verbonden op meerdere apparaten of meerdere browsertabbladen.

Client-gebeurtenissen

Gebeurtenissen worden gecreëerd tijdens de levenscyclus van een clientverbinding. Bijvoorbeeld, een eenvoudige WebSocket-clientverbinding creëert een connect gebeurtenis wanneer deze probeert verbinding te maken met de service, een connected gebeurtenis wanneer deze succesvol verbinding maakt met de service, een message gebeurtenis wanneer berichten naar de service stuurt en een disconnected gebeurtenis wanneer deze de verbinding verbreekt met de service.

Gebeurtenishandler

Event handler bevat de logica om de clientgebeurtenissen af te handelen. De event handler moet vooraf geregistreerd en geconfigureerd worden in de service via het portaal of de Azure CLI. De plaats om de event handler-logica te hosten wordt over het algemeen beschouwd als de serverzijde.

Voorbeelden

De connect aanvraag verwerken en toewijzen <userId>

import { WebPubSubEventHandler } from "@azure/web-pubsub-express";
import express from "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}`),
);

Behandel het connect verzoek en weiger de verbinding als de authenticatie faalt

import { WebPubSubEventHandler } from "@azure/web-pubsub-express";
import express from "express";

const handler = new WebPubSubEventHandler("chat", {
  handleConnect: (req, res) => {
    // auth the connection and reject the connection if auth failed
    res.fail(401, "Unauthorized");
    // the following method is also a valid approach
    // res.failWith({ code: 401, detail: "Unauthorized" });
  },
  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}`),
);

Behandel het connected verzoek

import { WebPubSubEventHandler } from "@azure/web-pubsub-express";
import express from "express";

const handler = new WebPubSubEventHandler("chat", {
  onConnected: (connectedRequest) => {
    // Your onConnected logic goes here
  },
  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}`),
);

Behandel het onGroupJoined verzoek

import { WebPubSubEventHandler } from "@azure/web-pubsub-express";
import express from "express";

const handler = new WebPubSubEventHandler("chat", {
  onGroupJoined: (groupJoinedRequest) => {
    console.log(
      `Connection ${groupJoinedRequest.context.connectionId} joined group ${groupJoinedRequest.group}`,
    );
  },
  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}`),
);

Behandel het onGroupLeft verzoek

import { WebPubSubEventHandler } from "@azure/web-pubsub-express";
import express from "express";

const handler = new WebPubSubEventHandler("chat", {
  onGroupLeft: (groupLeftRequest) => {
    console.log(
      `Connection ${groupLeftRequest.context.connectionId} left group ${groupLeftRequest.group}`,
    );
  },
  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}`),
);

Behandel het onDisconnected verzoek

import { WebPubSubEventHandler } from "@azure/web-pubsub-express";
import express from "express";

const handler = new WebPubSubEventHandler("chat", {
  onDisconnected: (disconnectedRequest) => {
    // Your onDisconnected logic goes here
  },
  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}`),
);

Behandel het connect verzoek voor mqtt en wijs <userId> toe en <mqtt> eigenschappen

import { WebPubSubEventHandler, MqttConnectRequest } from "@azure/web-pubsub-express";
import express from "express";

const handler = new WebPubSubEventHandler("chat", {
  handleConnect: (req, res) => {
    if (req.context.clientProtocol === "mqtt") {
      // return mqtt response when request is of MQTT kind
      // get connect request as mqtt request and print it
      const mqttRequest = req as MqttConnectRequest;
      console.log(mqttRequest);

      // auth the connection and return mqtt response
      res.success({
        userId: "user1",
        mqtt: { userProperties: [{ name: "a", value: "b" }] },
      });
    } else {
      res.success({
        userId: "user1",
      });
    }
  },
  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}`),
);

Behandel het connect verzoek om mqtt en weiger de verbinding als de authenticatie mislukte

import { WebPubSubEventHandler, MqttConnectRequest } from "@azure/web-pubsub-express";
import express from "express";

const handler = new WebPubSubEventHandler("chat", {
  handleConnect: (req, res) => {
    // auth the connection and reject the connection if auth failed
    if (req.context.clientProtocol === "mqtt") {
      // return mqtt error response when request is of MQTT kind
      // get connect request as mqtt request and print it
      const mqttRequest = req as MqttConnectRequest;
      console.log(mqttRequest);

      // auth the connection and return mqtt failure response
      res.fail(401, "Not Authorized");

      // Or use below method for more fine-grained control over the MQTT return code
      // res.failWith({ mqtt: { code: MqttV500ConnectReasonCode.NotAuthorized } });
    } else res.success();
  },
  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}`),
);

Behandel het onDisconnected for mqtt-verzoek

import { WebPubSubEventHandler, MqttDisconnectedRequest } from "@azure/web-pubsub-express";
import express from "express";

const handler = new WebPubSubEventHandler("chat", {
  onDisconnected: (disconnectedRequest) => {
    if (disconnectedRequest.context.clientProtocol === "mqtt") {
      // get disconnect request as mqtt request and print it
      const mqttRequest = disconnectedRequest as MqttDisconnectedRequest;
      console.log(mqttRequest.mqtt);
      // Your onDisconnected logic goes here
    } else {
      console.log(disconnectedRequest);
      // Your onDisconnected logic goes here
    }
  },
  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}`),
);

Alleen opgegeven eindpunten toestaan

import { WebPubSubEventHandler } from "@azure/web-pubsub-express";
import express from "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}`),
);

Stel aangepaste event handler-pad in

import { WebPubSubEventHandler } from "@azure/web-pubsub-express";
import express from "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}`),
);

Verbindingsstatus instellen en lezen

import { WebPubSubEventHandler } from "@azure/web-pubsub-express";
import express from "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) {
    const 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}`),
);

Probleemoplossingsproces

Logboeken inschakelen

Het inschakelen van logboekregistratie kan helpen nuttige informatie over fouten te ontdekken. Als u een logboek met HTTP-aanvragen en -antwoorden wilt zien, stelt u de omgevingsvariabele AZURE_LOG_LEVEL in op info.

export AZURE_LOG_LEVEL=verbose

Alternatief kan logging tijdens runtime worden ingeschakeld door setLogLevel aan te roepen in de @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Voor meer gedetailleerde instructies over het inschakelen van logboeken, kunt u de @azure/logger pakketdocumentenbekijken.

Live Trace

Gebruik Live Trace vanuit de Web PubSub-serviceportal om het liveverkeer weer te geven.

Volgende stappen 

Bekijk alsjeblieft de directory samples voor gedetailleerde voorbeelden van hoe je deze bibliotheek kunt gebruiken.

Contributing

Als je wilt bijdragen aan deze bibliotheek, lees dan de bijdragende gids om meer te weten te komen over hoe je de code bouwt en test.

Verwante projecten

• Microsoft Azure SDK voor Javascript