你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 Express 的 Azure Web PubSub CloudEvents 处理程序

项目
07/03/2023

Azure Web PubSub 服务是一项 Azure 托管服务，可帮助开发者轻松构建具有实时功能和发布-订阅模式的 Web 应用程序。任何需要在服务器和客户端或客户端之间进行实时发布-订阅消息传送的方案都可以使用 Azure Web PubSub 服务。通常需要从服务器轮询或提交 HTTP 请求的传统实时功能也可以使用 Azure Web PubSub 服务。

在建立 WebSocket 连接时，Web PubSub 服务将连接生命周期和消息转换为 CloudEvents 格式的事件。此库提供一个快速中间件来处理表示 WebSocket 连接的生命周期和消息的事件，如下图所示：

cloudevents

有关此处使用的术语的详细信息，请参阅主要概念部分。

源代码 | 包 (NPM) | API 参考文档 | 产品文档 | 示例

入门

目前支持的环境

LTS 版本的 Node.js
Express 4.x.x 或更高版本

先决条件

一个 Azure 订阅。
一个现有的 Azure Web PubSub 终结点。

1. 安装 `@azure/web-pubsub-express` 包

npm install @azure/web-pubsub-express

2. 创建 `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}`)
);

关键概念

连接

连接（也称为客户端或客户端连接）表示连接到 Web PubSub 服务的单个 WebSocket 连接。成功连接后，Web PubSub 服务会向此连接分配唯一的连接 ID。

集线器

中心是客户端连接集的逻辑概念。通常将一个中心用于一种用途，例如聊天中心或通知中心。创建客户端连接后，它会连接到某个中心，并且在其生存期内属于该中心。不同的应用程序可以使用不同的中心名称共享一个 Azure Web PubSub 服务。

组

组是与中心的连接的子集。可以随时向组添加客户端连接或者从组中删除客户端连接。例如，当某个客户端加入聊天室，或某个客户端离开聊天室，此类聊天室可以看成是一个组。一个客户端可以加入多个组，一个组可以包含多个客户端。

用户

与 Web PubSub 的连接可以属于一个用户。用户可能具有多个连接，例如当单个用户跨多个设备或多个浏览器选项卡进行连接时。

客户端事件

在客户端连接生命周期内会创建事件。例如，某个简单的 WebSocket 客户端连接在尝试连接到服务时会创建 connect 事件，在成功连接到服务时会创建 connected 事件，在向服务发送消息时会创建 message 事件，在从服务断开连接时会创建 disconnected 事件。

事件处理程序

事件处理程序包含用于处理客户端事件的逻辑。需要提前通过门户或 Azure CLI 在服务中注册和配置事件处理程序。用于托管事件处理程序逻辑的位置通常被视为服务器端。

示例

处理 `connect` 请求并分配 `<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}`)
);

仅允许指定的终结点

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

设置自定义事件处理程序路径

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

设置并读取连接状态

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

疑难解答

启用日志

使用此库时，可设置以下环境变量来获取调试日志。

从 SignalR 客户端库获取调试日志

export AZURE_LOG_LEVEL=verbose

有关如何启用日志的更详细说明，请查看 @azure/logger 包文档。

实时跟踪

在 Web PubSub 服务门户中使用“实时跟踪”可查看实时流量。

后续步骤

请查看示例目录，获取有关如何使用此库的详细示例。

贡献

若要为此库做出贡献，请阅读贡献指南，详细了解如何生成和测试代码。

Microsoft Azure SDK for Javascript

通过