JavaScript 的 Web PubSub 客户端库
阿苏尔网络 PubSub 是一种云服务,它帮助开发者在网络应用程序中轻松地建立实时功能,并具有规模化的发布订阅模式.
任何需要服务器和客户端之间或客户端之间按照发布订阅模式实时发送消息的情景都可以从使用Web PubSub中受益. 开发者不再需要通过每隔一段时间发送重复的HTTP请求来对服务器进行投票,这是浪费和难以衡量的.
如下图所示,您的客户端与您的 Web PubSub 资源建立 WebSocket 连接 。 此客户端库 :
- 简化客户端连接管理
- 简化客户端发送信件
- 客户端连接意外下降后自动重试
- 从连接滴滴中恢复后可靠发送信息的数量和顺序
此处所用术语的详情如下: 关键概念 节.
此库托管于 国家预防机制。 。 。 .
开始
目前得到支持的环境
先决条件
- 一个 Azure 订阅
- A 类 Web PubSub 资源
1. 安装 @azure/web-pubsub-client 软件包
npm install @azure/web-pubsub-client
2. 连接您的 Web PubSub 资源
客户端使用客户端访问 URL 连接并认证服务,该服务遵循以下模式: wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>。客户端可以有几种方式获得客户端访问URL. 这个快速开始,你可以复制并粘贴一个 从Azure Portal下面显示。 (用于制作,您的客户端通常可以获得应用程序服务器上生成的客户端访问URL. 详见下文 (中文(简体) )
如上图所示,客户端有权向一个特定团体发送消息并加入该团体。 "组1" ..
import { WebPubSubClient } from "@azure/web-pubsub-client";
// Instantiates the client object
const client = new WebPubSubClient("<client-access-url>");
// Starts the client connection with your Web PubSub resource
await client.start();
3. 加入团体
注意客户端只能收到来自其加入的组的信息,您需要添加回调以指定接收消息时的逻辑.
import { WebPubSubClient } from "@azure/web-pubsub-client";
const client = new WebPubSubClient("<client-access-url>");
// Registers a listener for the event 'group-message' early before joining a group to not miss messages
client.on("group-message", (e) => {
console.log(`Received message: ${e.message.data}`);
});
// Starts the client connection with your Web PubSub resource
await client.start();
// A client needs to join the group it wishes to receive messages from it
const groupName = "group1";
await client.joinGroup(groupName);
4. 向一组发送信息
import { WebPubSubClient } from "@azure/web-pubsub-client";
const client = new WebPubSubClient("<client-access-url>");
await client.start();
const groupName = "group1";
await client.joinGroup(groupName);
// Send a message to a joined group
await client.sendToGroup(groupName, "hello world", "text");
5. 启动上游活动(审查)
import { WebPubSubClient } from "@azure/web-pubsub-client";
const client = new WebPubSubClient("<client-access-url>");
await client.start();
const result = await client.invokeEvent("processOrder", { orderId: 1 }, "json");
console.log(`Invocation result: ${JSON.stringify(result.data)}`);
invokeEvent 发送一个 invoke 请求服务,等待关联 invokeResponse,然后返回有效载荷。 您可以通过传递中止引用 { abortSignal }。 。 。 .
服务引发的援引尚未得到支持.
6. 向一组发送信息(审查)
可将一个大型或连续的有效载荷作为所订购的碎片流发送给一个组,并在接收方消耗每个入行的溪流整体.
import { WebPubSubClient } from "@azure/web-pubsub-client";
const client = new WebPubSubClient("<client-access-url>");
// Receiving side: subscribe once, then consume each inbound stream with for-await.
client.onGroupStream(
async (stream) => {
const parts: string[] = [];
try {
for await (const message of stream) {
parts.push(message.data as string);
}
console.log(`Stream ${stream.streamId} completed: ${parts.join("")}`);
} catch (err) {
console.log(
`Stream ${stream.streamId} failed: ${
(
err as {
name?: string;
}
).name
}`,
);
}
},
{ handleFromStart: true },
);
await client.start();
const groupName = "group1";
await client.joinGroup(groupName);
// Sending side: write a logical stream in ordered fragments, then end it.
const stream = await client.openGroupStream(groupName);
await stream.write("hello ", "text");
await stream.write("world", "text");
await stream.end();
onGroupStream 返回订阅 close() 为不注册 听者。 每个回电都收到一个 GroupStream 这对它的碎片是有效的. openGroupStream 返回 a GroupStreamWriter 用于 write 碎片, end 流成功,或 abort 它有一个错误.
实例
添加连接、 断开和停止事件的回调
- 当客户端成功连接到您的 Web PubSub 资源时
connected触发事件.
client.on("connected", (e) => {
console.log(`Connection ${e.connectionId} is connected.`);
});
- 当一个客户端断开并无法恢复连接时
disconnected触发事件.
client.on("disconnected", (e) => {
console.log(`Connection disconnected: ${e.message}`);
});
- 这个
stopped当客户端断开时将触发事件 财务报告和审定财务报表 客户端停止尝试重新连接。 这通常发生在client.stop()称为,或autoReconnect已禁用,或已到达重联的指定限制。 如果您想要重新启动客户端, 您可以打电话client.start()在停止的事件.
// Registers a listener for the "stopped" event
client.on("stopped", () => {
console.log(`Client has stopped`);
});
使用谈判服务器生成客户端访问 URL 程序
在制作中,客户端通常从应用程序服务器取取客户端访问URL. 服务器持有连接字符串到您的 Web PubSub 资源, 在服务器库的帮助下生成客户端访问 URL @azure/web-pubsub。 。 。 .
1. 应用程序服务器
下面的代码片段是应用程序服务器曝光一个 /negotiate 路径并返回客户端访问 URL.
import express from "express";
import { WebPubSubServiceClient } from "@azure/web-pubsub";
const app = express();
const port = 8080;
// Imports the server library, which is different from the client library
const hubName = "sample_chat";
const serviceClient = new WebPubSubServiceClient("<web-pubsub-connectionstring>", hubName);
// Note that the token allows the client to join and send messages to any groups. It is specified with the "roles" option.
app.get(
"/negotiate",
async (
_req: unknown,
res: {
json: (body: { url: string }) => void;
},
) => {
const token = await serviceClient.getClientAccessToken({
roles: ["webpubsub.joinLeaveGroup", "webpubsub.sendToGroup"],
});
res.json({
url: token.url,
});
},
);
app.listen(port, () =>
console.log(`Application server listening at http://localhost:${port}/negotiate`),
);
2. 客户方
下面的代码片段是客户端的例子.
import { WebPubSubClient } from "@azure/web-pubsub-client";
const client = new WebPubSubClient({
getClientAccessUrl: async () => {
const negotiate = await fetch("/negotiate");
const { url } = (await negotiate.json()) as {
url: string;
};
return url;
},
});
await client.start();
要了解样本的完整代码,请参见: 样本浏览器。 。 。 .
客户端会从应用程序服务器或加入的组中导入信件
一个客户端可以添加回调来消耗来自应用程序服务器或组的信息. 请注意: group-message 客户端可以 仅限 接收它加入的组信件.
// Registers a listener for the "server-message". The callback will be invoked when your application server sends message to the connectionID, to or broadcast to all connections.
client.on("server-message", (e) => {
console.log(`Received message ${e.message.data}`);
});
// Registers a listener for the "group-message". The callback will be invoked when the client receives a message from the groups it has joined.
client.on("group-message", (e) => {
console.log(`Received message from ${e.message.group}: ${e.message.data}`);
});
处理复职失败
当一个客户端被断开并无法恢复时, 将会在您的 Web PubSub 资源中清除所有组上下文 。 这意味着当客户端重新连接时,它需要重新加入组. 默认情况下,客户端有 autoRejoinGroup 选项已启用.
不过,你应该知道 autoRejoinGroup限制.
- 客户端只能重新加入最初由客户端代码加入的组 没有 根据服务器侧码.
- "rejoin group"操作可能由于各种原因而失败,例如客户端没有加入组的许可. 在这种情况下,您需要添加回调处理此故障 .
import { WebPubSubClient } from "@azure/web-pubsub-client";
// By default autoRejoinGroups=true. You can disable it by setting to false.
const client = new WebPubSubClient("<client-access-url>", { autoRejoinGroups: true });
// Registers a listener to handle "rejoin-group-failed" event
client.on("rejoin-group-failed", (e) => {
console.log(`Rejoin group ${e.group} failed: ${e.error}`);
});
操作和重试
默认情况下, 例如 client.joinGroup(), (中文(简体) ), client.leaveGroup(), (中文(简体) ), client.sendToGroup(), (中文(简体) ), client.sendEvent() 有三个复试。 您可以通过 messageRetryOptions。如果所有重试都失败,则会出现错误。 你可以继续重试 通过通过同样的 ackId 作为之前的重试,以便Web PubSub服务可以去除操作.
import { WebPubSubClient, SendMessageError } from "@azure/web-pubsub-client";
const client = new WebPubSubClient("<client-access-url>");
await client.start();
const groupName = "group1";
try {
await client.joinGroup(groupName);
} catch (err) {
let id: number | undefined;
if (err instanceof SendMessageError) {
id = err.ackId;
}
await client.joinGroup(groupName, { ackId: id });
}
指定子议定书
您可以更改子协议, 供客户使用 。 默认情况下,客户端使用 json.reliable.webpubsub.azure.v1。您可以选择使用 json.reliable.webpubsub.azure.v1 或者说 json.webpubsub.azure.v1。 。 。 .
import { WebPubSubClient, WebPubSubJsonProtocol } from "@azure/web-pubsub-client";
// Change to use json.webpubsub.azure.v1
const client = new WebPubSubClient("<client-access-url>", {
protocol: WebPubSubJsonProtocol(),
});
import { WebPubSubClient, WebPubSubJsonReliableProtocol } from "@azure/web-pubsub-client";
// Change to use json.reliable.webpubsub.azure.v1
const client = new WebPubSubClient("<client-access-url>", {
protocol: WebPubSubJsonReliableProtocol(),
});
关键概念
连接
一个连接,也叫客户端或客户端连接,代表个人WebSocket连接到Web PubSub. 成功连接时,由Web PubSub为该连接指定了独特的连接ID. 每个 WebPubSubClient 建立自己的专属连接.
恢复
如果一个客户端使用可靠的协议断开,一个新的WebSocket试图使用丢失连接的连接ID来建立. 如果新的WebSocket连接成功连接,则连接被恢复. 在整个客户端断开时,服务会保留客户端上下文以及客户端订阅的所有消息,当客户端恢复时,服务会将这些消息发送给客户端. 如果服务返回 WebSocket 错误代码 1008 或回收尝试持续超过30秒,回收失败.
重新连接
重新连接发生在客户端连接下降而无法恢复时. 重新连接开始一个新的连接,而新的连接有新的连接ID. 与恢复不同,服务将重新连接的客户端视为新的客户端连接. 客户端连接需要重新加入组. 默认情况下,客户端库在重新连接后重新加入组.
枢纽
中枢是一组客户端连接的逻辑概念. 通常,您使用一个中枢用于一个目的,例如聊天中枢,或者通知中枢. 当客户端连接被创建时,它会连接到一个中枢,在其存在期间,它属于那个中枢. 不同的应用程序可以通过使用不同的中枢名称来共享一个Web PubSub.
组
一组是连接到中枢的子集. 您可以在组中添加客户端连接, 或者随时从组中去除客户端连接 。 例如,当客户端加入聊天室,或者当客户端离开聊天室时,这个聊天室可以被认为是一个组. 一个客户端可以加入多个组,一个组可以包含多个客户端.
用户
连接到 Web PubSub 可以属于一个用户. 一个用户可能拥有多个连接,例如当一个用户通过多个设备或多个浏览器标签连接时.
客户端寿命
每个Web PubSub客户端都能够安全地缓存并用作应用程序寿命的单通. 已注册的事件召回与客户共享相同的寿命. 这意味着您可以随时添加或删除回调,注册状态在重新连接或客户端被停止后不会改变.
Java 脚本套装
要在浏览器中使用这个客户端库,首先需要使用捆绑器. 关于如何做到这一点的详情,请参见我们 捆绑文件。 。 。 .
解决问题
启用日志
允许伐木可能有助于发现有关失败的有用信息。 为了查看 HTTP 请求和回复的日志,设置 AZURE_LOG_LEVEL 环境变量改为 info。 。 。 .
export AZURE_LOG_LEVEL=verbose
也可以在运行时通过呼叫启用日志 setLogLevel 输入 @azure/logger数字 :
import { setLogLevel } from "@azure/logger";
setLogLevel("info");
关于如何启用日志的更详细指示,您可以查看 @ azure/ logger 包文件。 。 。 .
-
现场追踪
使用 活追踪工具 从Web PubSub出入口查看直播流量.
额外资源
-
了解更多客户端权限, 查看 权限
捐款
如果您想为图书馆捐钱 请读一下 贡献指南 学习如何构建和测试密码.