Azure Web PubSub CloudEvents kezelők az Express keretrendszerhez

Az Azure Web PubSub szolgáltatás egy Azure által felügyelt szolgáltatás, amellyel a fejlesztők egyszerűen készíthetnek webalkalmazásokat valós idejű funkciókkal és közzétételi feliratkozási mintával. Az Azure Web PubSub szolgáltatást minden olyan forgatókönyv használhatja, amely valós idejű közzétételi-előfizetési üzenetküldést igényel a kiszolgáló és az ügyfelek között, vagy az ügyfelek között. A hagyományos valós idejű funkciók, amelyek gyakran igényelnek lekérdezést a kiszolgálóról vagy HTTP-kérések elküldése, az Azure Web PubSub szolgáltatást is használhatják.

Amikor egy WebSocket-kapcsolat csatlakozik, a Web PubSub szolgáltatás a kapcsolat életciklusát és az üzeneteket CloudEvents formátumú eseményekké alakítja át. Ez a kódtár egy expressz köztes szoftvert biztosít a WebSocket-kapcsolat életciklusát és üzeneteit képviselő események kezelésére az alábbi ábrán látható módon:

felhőesemények

A itt használt kifejezésekről részletesen a Kulcsfogalmak szekcióban találhatók.

Forráskód | Csomag (NPM) | API-referenciadokumentáció | Termékdokumentáció | Minták

Kezdő lépések

Jelenleg támogatott környezetek

Prerequisites

1. A csomag telepítése @azure/web-pubsub-express

npm install @azure/web-pubsub-express

2. Hozzon létre egy 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}`),
);

főbb fogalmak

Kapcsolat

A kapcsolat, más néven kliens vagy kliens kapcsolat, egy egyéni WebSocket kapcsolatot jelent, amely a Web PubSub szolgáltatáshoz csatlakozik. Ha sikeresen csatlakozik, a Web PubSub szolgáltatás egyedi kapcsolatazonosítót rendel ehhez a kapcsolathoz.

Központ

A központ egy logikai fogalom az ügyfélkapcsolatok halmazához. Általában egyetlen hubot használsz egy célra, például egy chat hub vagy egy értesítési hub. Amikor létrejön egy ügyfélkapcsolat, az egy központhoz csatlakozik, és annak élettartama alatt az adott központhoz tartozik. A különböző alkalmazások különböző központnevek használatával oszthatnak meg egy Azure Web PubSub szolgáltatást.

Csoport

A csoport a központhoz való kapcsolatok egy részhalmaza. Hozzáadhat egy ügyfélkapcsolatot egy csoporthoz, vagy bármikor eltávolíthatja az ügyfélkapcsolatot a csoportból. Ha például egy ügyfél csatlakozik egy csevegőszobához, vagy amikor egy ügyfél elhagyja a csevegőszobát, ez a csevegőszoba csoportnak tekinthető. Egy ügyfél több csoporthoz is csatlakozhat, egy csoport pedig több ügyfelet is tartalmazhat.

User

A Web PubSub-kapcsolatok egy felhasználóhoz tartozhatnak. Egy felhasználó több kapcsolattal is rendelkezhet, például ha egy felhasználó több eszközön vagy több böngészőlapon csatlakozik.

Ügyfélesemények

Az események egy klienskapcsolat életciklusa során keletkeznek. Például egy egyszerű WebSocket klienskapcsolat eseményt connect hoz létre, amikor megpróbál csatlakozni a szolgáltatáshoz, egy connected eseményt, amikor sikeresen csatlakozott a szolgáltatáshoz, egy message eseményt, amikor üzeneteket küld a szolgáltatásnak, és disconnected egy eseményt, amikor a szolgáltatás megszakad a kapcsolatot.

Eseménykezelő

Az eseménykezelő tartalmazza a kliens események kezelésére szolgáló logikát. Az eseménykezelőt előzetesen regisztrálni és konfigurálni kell a szolgáltatásban a portálon vagy az Azure CLI-n keresztül. Az eseménykezelő logika helyét általában szerveroldalnak tekintik.

Példák

connect A kérés kezelése és hozzárendelése<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}`),
);

Kezeld a connect kérést, és ha hitelesítés meghiúsul, utasítsd el a kapcsolatot

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

Kezeld a kérést connected

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

Kezeld a kérést onGroupJoined

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

Kezeld a kérést onGroupLeft

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

Kezeld a kérést onDisconnected

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

Kezeld az connect mqtt kérését, és assignáld <userId> meg a tulajdonságokat <mqtt>

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

Kezeld az connect mqtt kérést, és ha hitelesítés nem sikerült, utasítsd el a kapcsolatot

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

Kezeld az onDisconnected for mqtt kérést

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

Csak a megadott végpontok engedélyezése

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

Egyéni eseménykezelő elérési útjának beállítása

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

Kapcsolatállapot beállítása és olvasása

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

Hibaelhárítás

Naplók engedélyezése

A naplózás engedélyezése segíthet a hibákról szóló hasznos információk feltárásában. A HTTP-kérések és válaszok naplójának megtekintéséhez állítsa a környezeti változót a AZURE_LOG_LEVEL következőre info: .

export AZURE_LOG_LEVEL=verbose

Alternatívaként a naplózás futásidőben is engedélyezhető a setLogLevel hívásával a @azure/logger.

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

setLogLevel("info");

A naplók engedélyezésére vonatkozó részletesebb útmutatásért tekintse meg a @azure/logger csomag dokumentációit.

Élő nyomkövetés

Az élő forgalom megtekintéséhez használja a Web PubSub szolgáltatásportál élő nyomkövetését .

Következő lépések

Kérjük, nézze meg a samples könyvtárat részletes példákért a könyvtár használatához.

Közreműködés

Ha szeretnél hozzájárulni ehhez a könyvtárhoz, kérjük, olvasd el a hozzájárulás útmutatót hogy többet megtudj arról, hogyan lehet elkészíteni és tesztelni a kódot.

  • Last updated on