Oktatóanyag: Üzenetek közzététele és feliratkozás a WebSocket-ügyfelek között alprotocol használatával

  • Cikk

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

If you don't have an Azure subscription, create an Azure free account before you begin.

Előfeltételek

  • 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.

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 Csatlakozás ionString lekérése jövőbeli használatra

Fontos

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 ügyeljen a hozzáférési kulcsok védelmére. Az Azure Key Vault használatával biztonságosan kezelheti és elforgathatja a kulcsokat. 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.

A szolgáltatás Csatlakozás ionString parancsának lekéréséhez használja az Azure CLI az webpubsub billentyűkombináció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 Csatlakozás ionStringet, é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.

  1. 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

  2. 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();

  3. 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.

  4. 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 az connectionId ü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.

  1. 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.

  2. 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ül ws.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.

  3. Frissítse kissé a ws.onmessage visszahívási logikát, hogy elemezhesse a JSON-választ, és csak a csoportból stream 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);
  }
};

  4. 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 mikor GenerateClientAccessUri értéket az Startup.cs alábbihoz hasonlóan:

    service.GenerateClientAccessUri(roles: new string[] { "webpubsub.sendToGroup.stream", "webpubsub.joinLeaveGroup.stream" })

  5. 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ó.

További 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.

További Azure Web PubSub-minták felfedezése