JavaScript SDK pro Azure Web PubSub
Služba Azure Web PubSub je služba spravovaná v Azure, která vývojářům pomáhá snadno vytvářet webové aplikace s funkcemi v reálném čase a vzorem publikování a odběru. Jakýkoli scénář, který vyžaduje zasílání zpráv publikování a odběru v reálném čase mezi servery a klienty nebo mezi klienty, může používat službu Azure Web PubSub. Tradiční funkce v reálném čase, které často vyžadují dotazování ze serveru nebo odesílání požadavků HTTP, můžou také používat službu Azure Web PubSub.
JavaScript nabízí dvě knihovny: klientskou knihovnu služby a expresní middleware. Následující části obsahují další informace o těchto knihovnách.
Klientská knihovna služby Azure Web PubSub pro JavaScript
Tuto knihovnu můžete použít na straně aplikačního serveru ke správě připojení klienta WebSocket, jak je znázorněno na následujícím diagramu:
- Odesílání zpráv do center a skupin
- Odesílání zpráv konkrétním uživatelům a připojením
- Uspořádejte uživatele a připojení do skupin.
- Zavření připojení
- Udělení, odvolání a kontrola oprávnění pro existující připojení
Referenční dokumentace k rozhraní API balíčku zdrojového kódu | (NPM) | – ukázky dokumentace | | k produktům
Začínáme
Aktuálně podporovaná prostředí
Předpoklady
- Předplatné Azure
- Existující instance služby Azure Web PubSub.
1. Instalace @azure/web-pubsub balíčku
npm install @azure/web-pubsub
2. Vytvoření a ověření WebPubSubServiceClient
const { WebPubSubServiceClient } = require("@azure/web-pubsub");
const serviceClient = new WebPubSubServiceClient(
"<ConnectionString>",
"<hubName>"
);
Můžete také ověřit WebPubSubServiceClient pomocí koncového bodu a AzureKeyCredential:
const {
WebPubSubServiceClient,
AzureKeyCredential,
} = require("@azure/web-pubsub");
const key = new AzureKeyCredential("<Key>");
const serviceClient = new WebPubSubServiceClient(
"<Endpoint>",
key,
"<hubName>"
);
Nebo ověřte WebPubSubServiceClient pomocí ID Microsoft Entra.
@azure/identityInstalace závislosti
npm install @azure/identity
- Aktualizujte zdrojový kód tak, aby používal
DefaultAzureCredential:
const {
WebPubSubServiceClient,
AzureKeyCredential,
} = require("@azure/web-pubsub");
const key = new DefaultAzureCredential();
const serviceClient = new WebPubSubServiceClient(
"<Endpoint>",
key,
"<hubName>"
);
Příklady
Získání přístupového tokenu pro klienta pro spuštění připojení WebSocket
const { WebPubSubServiceClient } = require("@azure/web-pubsub");
const serviceClient = new WebPubSubServiceClient(
"<ConnectionString>",
"<hubName>"
);
// Get the access token for the WebSocket client connection to use
let token = await serviceClient.getClientAccessToken();
// Or get the access token and assign the client a userId
token = await serviceClient.getClientAccessToken({ userId: "user1" });
// return the token to the WebSocket client
Vysílání zpráv pro všechna připojení v centru
const { WebPubSubServiceClient } = require("@azure/web-pubsub");
const serviceClient = new WebPubSubServiceClient(
"<ConnectionString>",
"<hubName>"
);
// Send a JSON message
await serviceClient.sendToAll({ message: "Hello world!" });
// Send a plain text message
await serviceClient.sendToAll("Hi there!", { contentType: "text/plain" });
// Send a binary message
const payload = new Uint8Array(10);
await serviceClient.sendToAll(payload.buffer);
Odesílání zpráv všem připojením ve skupině
const { WebPubSubServiceClient } = require("@azure/web-pubsub");
const serviceClient = new WebPubSubServiceClient(
"<ConnectionString>",
"<hubName>"
);
const groupClient = serviceClient.group("<groupName>");
// Add user to the group
await groupClient.addUser("user1");
// Send a JSON message
await groupClient.sendToAll({ message: "Hello world!" });
// Send a plain text message
await groupClient.sendToAll("Hi there!", { contentType: "text/plain" });
// Send a binary message
const payload = new Uint8Array(10);
await groupClient.sendToAll(payload.buffer);
Odesílání zpráv všem připojením pro uživatele
const { WebPubSubServiceClient } = require("@azure/web-pubsub");
const serviceClient = new WebPubSubServiceClient(
"<ConnectionString>",
"<hubName>"
);
// Send a JSON message
await serviceClient.sendToUser("user1", { message: "Hello world!" });
// Send a plain text message
await serviceClient.sendToUser("user1", "Hi there!", {
contentType: "text/plain",
});
// Send a binary message
const payload = new Uint8Array(10);
await serviceClient.sendToUser("user1", payload.buffer);
Kontrola, jestli skupina obsahuje nějaké připojení
const { WebPubSubServiceClient } = require("@azure/web-pubsub");
const WebSocket = require("ws");
const serviceClient = new WebPubSubServiceClient(
"<ConnectionString>",
"<hubName>"
);
const groupClient = serviceClient.group("<groupName>");
// close all the connections in the group
await groupClient.closeAllConnections({ reason: "<closeReason>" });
// check if the group has any connections
const hasConnections = await serviceClient.groupExists("<groupName>");
Přístup k nezpracované odpovědi HTTP pro operaci
const { WebPubSubServiceClient } = require("@azure/web-pubsub");
function onResponse(rawResponse: FullOperationResponse): void {
console.log(rawResponse);
}
const serviceClient = new WebPubSubServiceClient(
"<ConnectionString>",
"<hubName>"
);
await serviceClient.sendToAll({ message: "Hello world!" }, { onResponse });
Řešení potíží s klientem služby
Povolení protokolů
Následující proměnnou prostředí můžete nastavit tak, aby při používání této knihovny získala protokoly ladění.
- Získání protokolů ladění z klientské knihovny Azure Web PubSub
export AZURE_LOG_LEVEL=verbose
Podrobnější pokyny k povolení protokolů najdete v dokumentaci k @azure/protokolovacímu balíčku.
Živé trasování
K zobrazení živého provozu použijte živé trasování z portálu služby Web PubSub.
Obslužné rutiny Azure Web PubSub CloudEvents pro Express
Když se připojí připojení WebSocket, služba Web PubSub transformuje životní cyklus připojení a zprávy na události ve formátu CloudEvents. Tato knihovna poskytuje expresní middleware pro zpracování událostí představujících životní cyklus a zprávy připojení WebSocket, jak je znázorněno na následujícím diagramu:
Referenční dokumentace k rozhraní API balíčku zdrojového kódu | (NPM) | – ukázky dokumentace | | k produktům
Začínáme
Aktuálně podporovaná prostředí
- Verze LTS Node.js
- Express verze 4.x.x nebo vyšší
Předpoklady
- Předplatné Azure
- Existující koncový bod Azure Web PubSub.
1. Instalace @azure/web-pubsub-express balíčku
npm install @azure/web-pubsub-express
2. Vytvoření 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}`
)
);
Příklady Express
connect Zpracování požadavku a přiřazení<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}`
)
);
Povolit pouze zadané koncové body
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}`
)
);
Nastavení cesty obslužné rutiny vlastní události
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}`
)
);
Nastavení a čtení stavu připojení
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}`
)
);
Řešení problému
Povolení protokolů
Následující proměnnou prostředí můžete nastavit tak, aby při používání této knihovny získala protokoly ladění.
- Získání protokolů ladění z klientské knihovny Azure Web PubSub
export AZURE_LOG_LEVEL=verbose
Podrobnější pokyny k povolení protokolů najdete v dokumentaci k balíčku @azure/loggeru.
Živé trasování
K zobrazení živého provozu použijte živé trasování z portálu služby Web PubSub.
Další kroky
Pomocí těchto prostředků můžete začít vytvářet vlastní aplikaci: