Azure Web PubSub CloudEvents-hanterare för Express

Azure Web PubSub-tjänsten är en Azure-hanterad tjänst som hjälper utvecklare att enkelt skapa webbprogram med realtidsfunktioner och publiceringsprenumerationsmönster. Alla scenarion som kräver publiceringsprenumerationsmeddelanden i realtid mellan server och klienter eller mellan klienter kan använda Azure Web PubSub-tjänsten. Traditionella realtidsfunktioner som ofta kräver avsökning från servern eller skicka HTTP-begäranden kan också använda Azure Web PubSub-tjänsten.

När en WebSocket-anslutning ansluter omvandlar Web PubSub-tjänsten anslutningslivscykeln och meddelanden till händelser i CloudEvents-format. Det här biblioteket innehåller ett expressmellanprogram för att hantera händelser som representerar WebSocket-anslutningens livscykel och meddelanden, enligt diagrammet nedan:

CloudEvents

Detaljer om de termer som används här beskrivs i avsnittet Nyckelbegrepp .

Källkod | Paket (NPM) | API-referensdokumentation | Produktdokumentation | Exempel

Komma igång

Miljöer som stöds för närvarande

Förutsättningar

1. Installera @azure/web-pubsub-express paketet

npm install @azure/web-pubsub-express

2. Skapa en 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}`),
);

Viktiga begrepp

Anslutning

En anslutning, även kallad klient eller klientanslutning, representerar en individuell WebSocket-anslutning ansluten till Web PubSub-tjänsten. När anslutningen lyckas tilldelas denna anslutning ett unikt anslutnings-ID av Web PubSub-tjänsten.

Hub

En hubb är ett logiskt begrepp för en uppsättning klientanslutningar. Vanligtvis använder man en hubb för ett syfte, till exempel en chatthubb eller en notifikationshubb. När en klientanslutning skapas ansluter den till en hubb och under dess livslängd tillhör den hubben. Olika program kan dela en Azure Web PubSub-tjänst med hjälp av olika hubbnamn.

Grupp

En grupp är en delmängd av anslutningar till hubben. Du kan lägga till en klientanslutning till en grupp eller ta bort klientanslutningen från gruppen när du vill. När en klient till exempel ansluter till ett chattrum eller när en klient lämnar chattrummet kan det här chattrummet betraktas som en grupp. En klient kan ansluta till flera grupper och en grupp kan innehålla flera klienter.

User

Anslutningar till Web PubSub kan tillhöra en användare. En användare kan ha flera anslutningar, till exempel när en enskild användare är ansluten över flera enheter eller flera webbläsarflikar.

Klienthändelser

Händelser skapas under en klientanslutnings livscykel. Till exempel skapar en enkel WebSocket-klientanslutning en connect händelse när den försöker ansluta till tjänsten, en connected händelse när den lyckades ansluta till tjänsten, en message händelse när den skickar meddelanden till tjänsten och en disconnected händelse när den kopplar bort från tjänsten.

Händelsehanterare

Event handler innehåller logiken för att hantera klienthändelserna. Event handler måste registreras och konfigureras i tjänsten via portalen eller Azure CLI i förväg. Platsen för att hosta händelsehandläggarlogiken anses generellt vara serversidan.

Exempel

connect Hantera begäran och tilldela<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}`),
);

Hantera connect förfrågan och avvisa anslutningen om autentiseringen misslyckades

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

Hantera connected förfrågan

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

Hantera onGroupJoined förfrågan

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

Hantera onGroupLeft förfrågan

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

Hantera onDisconnected förfrågan

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

Hantera connect förfrågan om mqtt och tilldela <userId> och <mqtt> egenskaper

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

Hantera connect förfrågan om mqtt och avvisa anslutningen om autentiseringen misslyckades

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

Hantera onDisconnected förfrågan om mqtt

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

Tillåt endast angivna slutpunkter

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

Ange sökväg för anpassad händelsehanterare

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

Ange och läsa anslutningstillstånd

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

Troubleshooting

Aktivera loggar

Aktivering av loggning kan hjälpa dig att hitta användbar information om fel. Om du vill se en logg med HTTP-begäranden och svar anger du AZURE_LOG_LEVEL miljövariabeln till info.

export AZURE_LOG_LEVEL=verbose

Du kan också aktivera loggning vid körning genom att anropa setLogLevel i @azure/logger:

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

setLogLevel("info");

Mer detaljerade anvisningar om hur du aktiverar loggar finns i dokument för @azure/logger-paket.

Livespårning

Använd Live Trace från webbportalen för PubSub-tjänsten för att visa livetrafiken.

Nästa steg

Ta gärna en titt på katalogen samples för detaljerade exempel på hur man använder detta bibliotek.

Contributing

Om du vill bidra till detta bibliotek, läs gärna guiden bidrag för att lära dig mer om hur man bygger och testar koden.

  • Last updated on