Oktatóanyag: Üzenetek közzététele és feliratkozás a WebSocket-ügyfelek között alprotocol használatával
A csevegőalkalmazás-oktatóanyagban megtanulta, hogyan küldhet és fogadhat adatokat a WebSocket API-kkal az Azure Web PubSub használatával. Láthatja, hogy nincs szükség protokollra, amikor az ügyfél kommunikál a szolgáltatással. Elküldhet például bármilyen típusú adatot WebSocket.send()
, és a kiszolgáló ugyanúgy kapja meg, ahogy van. A WebSocket API-k használata egyszerű, de a funkció korlátozott. Például nem adhatja meg az esemény nevét, amikor az eseményt a kiszolgálóra küldi, vagy nem tehet közzé üzenetet más ügyfeleknek a kiszolgálóra való küldés helyett. Ebben az oktatóanyagban megtudhatja, hogyan használható az alprotocol az ügyfél funkcióinak bővítésére.
Ebben az oktatóanyagban az alábbiakkal fog megismerkedni:
- Web PubSub szolgáltatáspéldány létrehozása
- A WebSocket-kapcsolat létrehozásához hozza létre a teljes URL-címet
- Üzenetek közzététele WebSocket-ügyfelek között alprotocol használatával
Ha nem rendelkezik Azure-előfizetéssel, első lépésként hozzon létre egy ingyenes Azure-fiókot.
Előfeltételek
Használja a Bash-környezetet az Azure Cloud Shellben. További információ: A Bash rövid útmutatója az Azure Cloud Shellben.
Ha inkább helyi cli-referenciaparancsokat szeretne futtatni, telepítse az Azure CLI-t. Ha Windows vagy macOS rendszert használ, fontolja meg az Azure CLI Docker-tárolóban való futtatását. További információ: Az Azure CLI futtatása Docker-tárolóban.
Ha helyi telepítést használ, jelentkezzen be az Azure CLI-be az az login parancs futtatásával. A hitelesítési folyamat befejezéséhez kövesse a terminálon megjelenő lépéseket. További bejelentkezési lehetőségekért lásd : Bejelentkezés az Azure CLI-vel.
Amikor a rendszer kéri, először telepítse az Azure CLI-bővítményt. További információ a bővítményekről: Bővítmények használata az Azure CLI-vel.
Futtassa az az version parancsot a telepített verzió és a függő kódtárak megkereséséhez. A legújabb verzióra az az upgrade paranccsal frissíthet.
- Ehhez a beállításhoz az Azure CLI 2.22.0-s vagy újabb verziója szükséges. Az Azure Cloud Shell használata esetén a legújabb verzió már telepítve van.
Fontos
A cikkben szereplő nyers kapcsolati sztring csak bemutató célokra jelennek meg.
A kapcsolati sztring tartalmazzák azokat az engedélyezési információkat, amelyekre az alkalmazásnak szüksége van az Azure Web PubSub szolgáltatás eléréséhez. A kapcsolati sztring belüli hozzáférési kulcs hasonló a szolgáltatás gyökérjelszójához. Éles környezetben mindig védje a hozzáférési kulcsokat. Az Azure Key Vault használatával biztonságosan kezelheti és elforgathatja a kulcsokat, és biztonságossá teheti a kapcsolatot.WebPubSubServiceClient
Kerülje a hozzáférési kulcsok más felhasználók számára való terjesztését, a szigorú kódolást, illetve a mások számára hozzáférhető egyszerű szövegek mentését. Ha úgy véli, hogy illetéktelenek lettek, forgassa el a kulcsokat.
Azure Web PubSub-példány létrehozása
Erőforráscsoport létrehozása
Az erőforráscsoport olyan logikai tároló, amelybe a rendszer üzembe helyezi és kezeli az Azure-erőforrásokat. Az az group create paranccsal hozzon létre egy, a eastus
helyen elnevezett myResourceGroup
erőforráscsoportot.
az group create --name myResourceGroup --location EastUS
Web PubSub-példány létrehozása
Futtassa az az extension add parancsot a webpubsub bővítmény telepítéséhez vagy frissítéséhez az aktuális verzióra.
az extension add --upgrade --name webpubsub
Az Azure CLI az webpubsub create paranccsal hozzon létre egy Web PubSub-t a létrehozott erőforráscsoportban. Az alábbi parancs létrehoz egy ingyenes Web PubSub-erőforrást a myResourceGroup erőforráscsoportban az EastUS-ban:
Fontos
Minden Web PubSub-erőforrásnak egyedi névvel kell rendelkeznie. Az alábbi példákban cserélje le <az egyedi erőforrás nevét> a Web PubSub nevére.
az webpubsub create --name "<your-unique-resource-name>" --resource-group "myResourceGroup" --location "EastUS" --sku Free_F1
A parancs kimenete az újonnan létrehozott erőforrás tulajdonságait jeleníti meg. Jegyezze fel az alábbi két tulajdonságot:
-
Erőforrás neve: A fenti paraméternek
--name
megadott név. -
hostName: A példában a gazdagép neve .
<your-unique-resource-name>.webpubsub.azure.com/
Ezen a ponton az Azure-fiók az egyetlen jogosult az új erőforráson végzett műveletek végrehajtására.
A ConnectionString lekérése későbbi használatra
A cikkben szereplő nyers kapcsolati sztring csak bemutató célokra jelennek meg. Éles környezetben mindig védje a hozzáférési kulcsokat. Az Azure Key Vault használatával biztonságosan kezelheti és elforgathatja a kulcsokat, és biztonságossá teheti a kapcsolatot.WebPubSubServiceClient
Az Azure CLI az webpubsub billentyű parancsával kérje le a szolgáltatás ConnectionString szolgáltatását. Cserélje le a <your-unique-resource-name>
helyőrzőt az Azure Web PubSub-példány nevére.
az webpubsub key show --resource-group myResourceGroup --name <your-unique-resource-name> --query primaryConnectionString --output tsv
Másolja a kapcsolati sztring későbbi használatra.
Másolja ki a beolvasott ConnectionStringet , és használja az oktatóanyag későbbi részében az értékként <connection_string>
.
A projekt előkészítése
Előfeltételek
Alprotocol használata
Az ügyfél elindíthat egy WebSocket-kapcsolatot egy adott alprotocol használatával. Az Azure Web PubSub szolgáltatás egy alprojektet json.webpubsub.azure.v1
támogat, amely lehetővé teszi az ügyfelek számára, hogy közvetlenül a Web PubSub szolgáltatáson keresztül tegyenek közzé vagy iratkozzanak fel a felsőbb rétegbeli kiszolgálóra való oda-vissza utazás helyett. Az alprotocol részleteiért tekintse meg az Azure Web PubSub által támogatott JSON WebSocket-alprotocolt .
Ha más protokollneveket használ, a szolgáltatás figyelmen kívül hagyja őket, és átengedi őket a kiszolgálónak a kapcsolódási eseménykezelőben, így saját protokollokat hozhat létre.
Most hozzunk létre egy webalkalmazást az json.webpubsub.azure.v1
alprotocol használatával.
Függőségek telepítése
mkdir logstream cd logstream dotnet new web dotnet add package Microsoft.Extensions.Azure dotnet add package Azure.Messaging.WebPubSub
Hozza létre a kiszolgálóoldalt az API és a
/negotiate
weblap üzemeltetéséhez.Frissítsen
Program.cs
az alábbi kóddal.- A szolgáltatásügyfél hozzáadásához és a kapcsolati sztring a konfigurációból való olvasásához használható
AddAzureClients
. -
app.Run();
Mielőtt hozzáadja a statikus fájlokat, vegye felapp.UseStaticFiles();
. - És frissítsen
app.MapGet
az ügyfél hozzáférési jogkivonatának kérésekkel való/negotiate
létrehozásához.
using Azure.Messaging.WebPubSub; using Microsoft.Extensions.Azure; var builder = WebApplication.CreateBuilder(args); builder.Services.AddAzureClients(s => { s.AddWebPubSubServiceClient(builder.Configuration["Azure:WebPubSub:ConnectionString"], "stream"); }); var app = builder.Build(); app.UseStaticFiles(); app.MapGet("/negotiate", async context => { var service = context.RequestServices.GetRequiredService<WebPubSubServiceClient>(); var response = new { url = service.GetClientAccessUri(roles: new string[] { "webpubsub.sendToGroup.stream", "webpubsub.joinLeaveGroup.stream" }).AbsoluteUri }; await context.Response.WriteAsJsonAsync(response); }); app.Run();
- A szolgáltatásügyfél hozzáadásához és a kapcsolati sztring a konfigurációból való olvasásához használható
A weblap létrehozása
Hozzon létre egy HTML-lapot az alábbi tartalommal, és mentse a következőként
wwwroot/index.html
:<html> <body> <div id="output"></div> <script> (async function () { let res = await fetch('/negotiate') let data = await res.json(); let ws = new WebSocket(data.url, 'json.webpubsub.azure.v1'); ws.onopen = () => { console.log('connected'); }; let output = document.querySelector('#output'); ws.onmessage = event => { let d = document.createElement('p'); d.innerText = event.data; output.appendChild(d); }; })(); </script> </body> </html>
A fenti kód csatlakozik a szolgáltatáshoz, és kinyomtatja a lapra érkező üzeneteket. A fő változás az, hogy a WebSocket-kapcsolat létrehozásakor meg kell adni az alprotocolt.
A kiszolgáló futtatása
A .NET Core-hoz készült Secret Manager eszközzel állítjuk be a kapcsolati sztring. Futtassa az alábbi parancsot, cserélje le
<connection_string>
az előző lépésben lekért parancsra, és nyissa meg http://localhost:5000/index.html a böngészőben:dotnet user-secrets init dotnet user-secrets set Azure:WebPubSub:ConnectionString "<connection-string>" dotnet run
Ha Chrome-ot használ, nyomja le az F12 billentyűt, vagy kattintson a jobb gombbal a ->Vizsgálat –>Fejlesztői eszközök elemre, és válassza a Hálózat lapot. Töltse be a weblapot, és láthatja, hogy létrejött a WebSocket-kapcsolat. A WebSocket-kapcsolat vizsgálatához az alábbi
connected
eseményüzenet jelenik meg az ügyfélben. Láthatja, hogy lekérheti azconnectionId
ügyfélhez létrehozott elemet.{"type":"system","event":"connected","userId":null,"connectionId":"<the_connection_id>"}
Láthatja, hogy a subprotocol segítségével lekérheti a kapcsolat metaadatait, ha a kapcsolat .connected
Az ügyfél mostantól JSON-üzenetet kap egyszerű szöveg helyett. A JSON-üzenet további információkat tartalmaz, például az üzenet típusát és forrását. Így ezen információk segítségével további feldolgozást végezhet az üzeneten (például más stílusban jelenítheti meg az üzenetet, ha más forrásból származik), amelyet a későbbi szakaszokban talál.
Üzenetek közzététele az ügyféltől
A csevegőalkalmazás összeállítása oktatóanyagban, amikor az ügyfél a Web PubSub szolgáltatás WebSocket-kapcsolatán keresztül küld üzenetet, a szolgáltatás elindít egy felhasználói eseményt a kiszolgáló oldalán. Az alprojekttel az ügyfél több funkcióval rendelkezik egy JSON-üzenet küldésével. Üzeneteket tehet közzé például közvetlenül az ügyfélről a Web PubSub szolgáltatáson keresztül más ügyfeleknek.
Ez akkor hasznos, ha nagy mennyiségű adatot szeretne valós időben továbbítani más ügyfeleknek. Ezzel a funkcióval hozzunk létre egy naplóstreamelési alkalmazást, amely valós időben streamelheti a konzolnaplókat a böngészőbe.
A streamelési program létrehozása
stream
Program létrehozása:mkdir stream cd stream dotnet new console
Frissítsen
Program.cs
a következő tartalommal:using System; using System.Net.Http; using System.Net.WebSockets; using System.Text; using System.Text.Json; using System.Threading.Tasks; namespace stream { class Program { private static readonly HttpClient http = new HttpClient(); static async Task Main(string[] args) { // Get client url from remote var stream = await http.GetStreamAsync("http://localhost:5000/negotiate"); var url = (await JsonSerializer.DeserializeAsync<ClientToken>(stream)).url; var client = new ClientWebSocket(); client.Options.AddSubProtocol("json.webpubsub.azure.v1"); await client.ConnectAsync(new Uri(url), default); Console.WriteLine("Connected."); var streaming = Console.ReadLine(); while (streaming != null) { if (!string.IsNullOrEmpty(streaming)) { var message = JsonSerializer.Serialize(new { type = "sendToGroup", group = "stream", data = streaming + Environment.NewLine, }); Console.WriteLine("Sending " + message); await client.SendAsync(Encoding.UTF8.GetBytes(message), WebSocketMessageType.Text, true, default); } streaming = Console.ReadLine(); } await client.CloseAsync(WebSocketCloseStatus.NormalClosure, null, default); } private sealed class ClientToken { public string url { get; set; } } } }
Itt láthatja, hogy van egy új fogalom , a "csoport". A csoport egy logikai fogalom egy központban, ahol közzéteheti az üzenetet egy kapcsolatcsoportban. A központban több csoport is lehet, és egy ügyfél egyszerre több csoportra is előfizethet. Alprotocol használata esetén csak egy csoportban tehet közzé közzétételt ahelyett, hogy az egész központnak közvetítenél. A feltételekkel kapcsolatos részletekért tekintse meg az alapfogalmakat.
Mivel itt a csoportot használjuk, frissíteni kell a weblapot
index.html
is a csoporthoz való csatlakozáshoz, amikor a WebSocket-kapcsolat létrejön a visszahíváson belülws.onopen
.let ackId = 0; ws.onopen = () => { console.log('connected'); ws.send(JSON.stringify({ type: 'joinGroup', group: 'stream', ackId: ++ackId })); };
Láthatja, hogy az ügyfél csatlakozik a csoporthoz egy üzenet típusának
joinGroup
elküldésével.Frissítse kissé a
ws.onmessage
visszahívási logikát, hogy elemezhesse a JSON-választ, és csak a csoportbólstream
nyomtassa ki az üzeneteket, hogy élő streamnyomtatóként funksson.ws.onmessage = event => { let message = JSON.parse(event.data); if (message.type === 'message' && message.group === 'stream') { let d = document.createElement('span'); d.innerText = message.data; output.appendChild(d); window.scrollTo(0, document.body.scrollHeight); } };
Biztonsági megfontolásokból az ügyfél alapértelmezés szerint nem tehet közzé vagy nem iratkozhat fel egy csoportra önmagában. Ezért észrevette, hogy a jogkivonat létrehozásakor az ügyfélre állítottunk
roles
be:Adja meg a
roles
mikorGenerateClientAccessUri
értéket azStartup.cs
alábbihoz hasonlóan:service.GenerateClientAccessUri(roles: new string[] { "webpubsub.sendToGroup.stream", "webpubsub.joinLeaveGroup.stream" })
Végül alkalmazzon némi stílust
index.html
is, hogy szépen jelenjen meg.<html> <head> <style> #output { white-space: pre; font-family: monospace; } </style> </head>
Most futtassa az alábbi kódot, és írjon be bármilyen szöveget, és valós időben jelennek meg a böngészőben:
ls -R | dotnet run
# Or call `dir /s /b | dotnet run` when you are using CMD under Windows
Vagy lassabbá teheti, hogy láthassa, hogy az adatok valós időben streamelhetők a böngészőbe:
for i in $(ls -R); do echo $i; sleep 0.1; done | dotnet run
Az oktatóanyag teljes kódmintája itt található.
Következő lépések
Ez az oktatóanyag bemutatja, hogyan csatlakozhat a Web PubSub szolgáltatáshoz, és hogyan tehet közzé üzeneteket a csatlakoztatott ügyfelek számára a subprotocol használatával.
A szolgáltatás használatának további megismeréséhez tekintse meg a többi oktatóanyagot.