適用於 Express 的 Azure Web PubSub CloudEvents 處理常式
Azure Web PubSub 服務是一項 Azure 受控服務，可協助開發人員輕鬆建置具有即時功能和發佈/訂閱模式的 Web 應用程式。 任何需要在伺服器與用戶端之間或用戶端之間即時發佈訂閱傳訊的案例，都可以使用 Azure Web PubSub 服務。 通常需要從伺服器輪詢或提交 HTTP 要求的傳統即時功能，也可以使用 Azure Web PubSub 服務。
WebSocket 連線連接成功時，Web PubSub 服務會將連線生命週期和訊息轉換成 CloudEvents 格式的事件。 此程式庫提供 Express 中介軟體，可處理代表 WebSocket 連線生命週期和訊息的事件，如下圖所示：
此處所使用詞彙的詳細資料，請參閱 重要概念一 節。
原始程式碼 | 套件 (NPM) | API 參考文件 | 產品文件 | 範例
開始使用
目前支援的環境
- Node.js 的 LTS 版本
- 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}`)
);
重要概念
Connection
「連線」也稱為用戶端或用戶端連線，代表連線到 Web PubSub 服務的個別 WebSocket 連線。 成功連線時，Web PubSub 服務會指派唯一的連線識別碼給此連線。
集線器
中樞是一組用戶端連線的邏輯概念。 您通常會針對一個用途使用一個中樞，例如「聊天」中樞或「通知」中樞。 建立用戶端連線時，它會連線到中樞，並在其存留期間屬於該中樞。 不同的應用程式可以使用不同的中樞名稱，共用一個 Azure Web PubSub 服務。
群組
群組是中樞連線的子集。 您可以隨時在群組中新增用戶端連線，或從群組中移除用戶端連線。 例如，當用戶端加入聊天室時，或當用戶端離開聊天室時，便可將此聊天室視為群組。 用戶端可以加入多個群組，而群組可以包含多個用戶端。
User
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 服務入口網站使用即時追蹤來檢視即時流量。
下一步
如需如何使用此程式庫的詳細範例，請參閱 範例 目錄。
參與
如果您希望向此程式庫投稿，請參閱投稿指南，深入瞭解如何組建與測試程式碼。
