Öğretici: Azure Web PubSub hizmetiyle sohbet uygulaması oluşturma

İleti yayımlama ve abone olma öğreticisinde, Azure Web PubSub ile iletileri yayımlama ve abone olma ile ilgili temel bilgileri öğrenirsiniz. Bu öğreticide Azure Web PubSub'un olay sistemini öğrenecek ve gerçek zamanlı iletişim işlevselliğine sahip eksiksiz bir web uygulaması oluşturmak için kullanacaksınız.

Bu öğreticide aşağıdakilerin nasıl yapılacağını öğreneceksiniz:

  • Web PubSub hizmet örneği oluşturma
  • Azure Web PubSub için olay işleyici ayarlarını yapılandırma
  • Uygulama sunucusundaki olayları işleme ve gerçek zamanlı sohbet uygulaması oluşturma

Azure hesabınız yoksa, başlamadan önce ücretsiz hesap oluşturun.

Önkoşullar

  • Bu kurulum, Azure CLI'nın 2.22.0 veya üzeri bir sürümünü gerektirir. Azure Cloud Shell kullanılıyorsa en son sürüm zaten yüklüdür.

Azure Web PubSub örneği oluşturma

Kaynak grubu oluşturma

Kaynak grubu, Azure kaynaklarının dağıtıldığı ve yönetildiği bir mantıksal kapsayıcıdır. az group create komutunu kullanarak konumunda adlı bir kaynak grubu oluşturun.

az group create --name myResourceGroup --location EastUS

Web PubSub örneği oluşturma

az extension add komutunu çalıştırarak webpubsub uzantısını yükleyin veya geçerli sürüme yükseltin.

az extension add --upgrade --name webpubsub

Oluşturduğunuz kaynak grubunda bir Web PubSub oluşturmak için Azure CLI az webpubsub create komutunu kullanın. Aşağıdaki komut, EastUS'ta myResourceGroup kaynak grubu altında bir Ücretsiz Web PubSub kaynağı oluşturur:

Önemli

Her Web PubSub kaynağının benzersiz bir adı olmalıdır. Aşağıdaki örneklerde <your-unique-resource-name> ifadesini Web PubSub hizmetinizin adıyla değiştirin.

az webpubsub create --name "<your-unique-resource-name>" --resource-group "myResourceGroup" --location "EastUS" --sku Free_F1

Bu komutun çıktısı yeni oluşturulan kaynağın özelliklerini gösterir. Aşağıda listelenen iki özelliği not edin:

  • Kaynak Adı: Yukarıdaki parametreye --name sağladığınız ad.
  • hostName: Örnekte ana bilgisayar adı şeklindedir <your-unique-resource-name>.webpubsub.azure.com/.

Bu noktada, azure hesabınız bu yeni kaynak üzerinde herhangi bir işlem gerçekleştirme yetkisi olan tek hesaptır.

Gelecekte kullanmak üzere ConnectionString'i edinin

Önemli

Ham bağlantı dizesi yalnızca tanıtım amacıyla bu makalede görünür.

Bir bağlantı dizesi, uygulamanızın Azure Web PubSub hizmetine erişmesi için ihtiyaç duyduğu yetkilendirme bilgilerini içerir. Bağlantı dizesindeki erişim anahtarı, hizmetiniz için kök parola görevi görür. Üretim ortamlarında erişim anahtarlarınızı her zaman koruyun. Anahtarlarınızı güvenli bir şekilde yönetmek ve döndürmek ve bağlantınızın WebPubSubServiceClientgüvenliğini sağlamak için Azure Key Vault kullanın.

Erişim anahtarlarını diğer kullanıcılara dağıtmaktan, sabit kodlamaktan veya başkalarının erişebileceği herhangi bir yerde düz metin olarak kaydetmekten kaçının. Ele geçirilmiş olabileceklerini düşünüyorsanız anahtarlarınızı döndürün.

Hizmetin ConnectionString değerini almak için Azure CLI az webpubsub key komutunu kullanın. Yer tutucuyu <your-unique-resource-name> Azure Web PubSub örneğinizin adıyla değiştirin.

az webpubsub key show --resource-group myResourceGroup --name <your-unique-resource-name> --query primaryConnectionString --output tsv

Daha sonra kullanmak üzere bağlantı dizesi kopyalayın.

Getirilen ConnectionString'i kopyalayın ve daha sonra öğreticinin okuyduğu ortam değişkenine WebPubSubConnectionStringayarlayın. Aşağıdaki <connection-string> değerini, aldığınız ConnectionString ile değiştirin.

export WebPubSubConnectionString="<connection-string>"

SET WebPubSubConnectionString=<connection-string>

Projeyi ayarlama

Önkoşullar

Uygulamayı oluşturma

Azure Web PubSub'da sunucu ve istemci olarak iki rol vardır. Bu kavram, bir web uygulamasındaki sunucu ve istemci rollerine benzer. Sunucu, istemcileri yönetmek, dinlemek ve istemci iletilerini yanıtlamakla sorumludur. İstemci, kullanıcının iletilerini sunucudan gönderip almaktan ve son kullanıcı için görselleştirmekten sorumludur.

Bu öğreticide, gerçek zamanlı bir sohbet web uygulaması oluşturacağız. Gerçek bir web uygulamasında, sunucunun sorumluluğu istemcilerin kimliğini doğrulamayı ve uygulama kullanıcı arabirimi için statik web sayfaları sunmayı da içerir.

Web sayfalarını barındırmak ve gelen istekleri işlemek için ASP.NET Core 8 kullanıyoruz.

İlk olarak bir klasörde ASP.NET Core web uygulaması chatapp oluşturalım.

  1. Yeni bir web uygulaması oluşturun.

    mkdir chatapp
cd chatapp
dotnet new web

  2. Statik web sayfalarını barındırmayı desteklemek için Program.cs ekleyin app.UseStaticFiles() .

    var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.UseStaticFiles();

app.Run();

  3. Bir HTML dosyası oluşturun ve olarak wwwroot/index.htmlkaydedin. Bunu daha sonra sohbet uygulamasının kullanıcı arabirimi için kullanacağız.

    <html>
  <body>
    <h1>Azure Web PubSub Chat</h1>
  </body>
</html>

dotnet run --urls http://localhost:8080 komutunu çalıştırarak sunucuyu test edebilir ve tarayıcıda http://localhost:8080/index.html adresine erişebilirsiniz.

Anlaşma uç noktası ekleme

İleti yayımlama ve abone olma eğitiminde abone, bağlantı dizesini doğrudan kullanır. Gerçek bir uygulamada, bağlantı dizesini herhangi bir istemciyle paylaşmak güvenli değildir; çünkü bağlantı dizesi, hizmet üzerinde her türlü işlemi gerçekleştirebilecek yüksek ayrıcalıklara sahiptir. Şimdi sunucunuzun bağlantı dizesini kullanacak şekilde yapılandıralım ve istemcinin erişim belirteci içeren tam URL'yi alabilmesi için bir negotiate uç noktasını kullanıma açalım. Bu şekilde, sunucu yetkisiz erişimi önlemek için uç noktanın negotiate önüne kimlik doğrulama ara yazılımı ekleyebilir.

İlk olarak bağımlılıkları yükleyin.

dotnet add package Microsoft.Azure.WebPubSub.AspNetCore

Şimdi istemcinin belirteç oluşturmak için çağıracağı bir /negotiate uç nokta ekleyelim.

using Azure.Core;
using Microsoft.Azure.WebPubSub.AspNetCore;
using Microsoft.Azure.WebPubSub.Common;
using Microsoft.Extensions.Primitives;

// Read connection string from environment
var connectionString = Environment.GetEnvironmentVariable("WebPubSubConnectionString");
if (connectionString == null)
{
    throw new ArgumentNullException(nameof(connectionString));
}

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddWebPubSub(o => o.ServiceEndpoint = new WebPubSubServiceEndpoint(connectionString))
    .AddWebPubSubServiceClient<Sample_ChatApp>();
var app = builder.Build();

app.UseStaticFiles();

// return the Client Access URL with negotiate endpoint
app.MapGet("/negotiate", (WebPubSubServiceClient<Sample_ChatApp> service, HttpContext context) =>
{
    var id = context.Request.Query["id"];
    if (StringValues.IsNullOrEmpty(id))
    {
        context.Response.StatusCode = 400;
        return null;
    }
    return new
    {
        url = service.GetClientAccessUri(userId: id).AbsoluteUri
    };
});
app.Run();

sealed class Sample_ChatApp : WebPubSubHub
{
}

AddWebPubSubServiceClient<THub>() , istemci bağlantı belirteci oluşturmak için anlaşma adımında ve hub olayları tetiklendiğinde hizmet REST API'lerini çağırmak için hub yöntemlerinde kullanabileceğimiz hizmet istemcisini WebPubSubServiceClient<THub>eklemek için kullanılır. Bu belirteç oluşturma kodu, yayımlama ve abone olma iletisi öğreticisinde kullandığımız koda benzer, ancak belirteci oluştururken bir bağımsız değişken daha (userId) geçiririz. kullanıcı kimliği istemci kimliğini tanımlamak için kullanılabilir, böylece bir ileti aldığınızda iletinin nereden geldiğini bilirsiniz.

Kod, önceki adımda ayarladığımız WebPubSubConnectionString ortam değişkeninden bağlantı dizesini okur.

Sunucuyu dotnet run --urls http://localhost:8080 kullanarak yeniden çalıştırın.

Bu API'ye erişerek http://localhost:8080/negotiate?id=user1 test edebilirsiniz ve size erişim belirteci ile Azure Web PubSub'un tam URL'sini verir.

Olayları işleme

Azure Web PubSub'da, istemci tarafında belirli etkinlikler gerçekleştiğinde (örneğin bir istemci bağlanıyor, bağlı, bağlantısı kesiliyor veya bir istemci ileti gönderiyorsa), hizmet bu olaylara tepki verebilmesi için sunucuya bildirimler gönderir.

Olaylar sunucuya Webhook olarak iletilir. Webhook, uygulama sunucusu tarafından barındırılır ve dışa açılır; ayrıca Azure Web PubSub hizmeti tarafında kaydedilir. Bir olay meydana geldiğinde hizmet webhook’ları tetikler.

Azure Web PubSub, olay verilerini açıklamak için CloudEvents'i izler.

Aşağıda, bir istemci bağlandığında connected sistem olaylarını ve bir istemci sohbet uygulamasını oluşturmak için mesaj gönderdiğinde message kullanıcı olaylarını ele alıyoruz.

Önceki adımda yüklediğimiz AspNetCore Microsoft.Azure.WebPubSub.AspNetCore için Web PubSub SDK'sı, CloudEvents isteklerini ayrıştırma ve işlemeye de yardımcı olabilir.

İlk olarak, app.Run() öğesinden önce olay işleyicileri ekleyin. Olaylar için uç nokta yolunu (diyelim ki /eventhandler) belirtin.

app.MapWebPubSubHub<Sample_ChatApp>("/eventhandler/{*path}");
app.Run();

Şimdi, önceki adımda oluşturduğumuz Sample_ChatApp sınıfının içine, Web PubSub hizmetini çağırmak için kullandığımız WebPubSubServiceClient<Sample_ChatApp> ile çalışmak üzere bir yapıcı ekleyin. Ve OnConnectedAsync() olay tetiklendiğinde connected yanıt vermek, OnMessageReceivedAsync() istemciden gelen iletileri işlemek için.

sealed class Sample_ChatApp : WebPubSubHub
{
    private readonly WebPubSubServiceClient<Sample_ChatApp> _serviceClient;

    public Sample_ChatApp(WebPubSubServiceClient<Sample_ChatApp> serviceClient)
    {
        _serviceClient = serviceClient;
    }

    public override async Task OnConnectedAsync(ConnectedEventRequest request)
    {
        Console.WriteLine($"[SYSTEM] {request.ConnectionContext.UserId} joined.");
    }

    public override async ValueTask<UserEventResponse> OnMessageReceivedAsync(UserEventRequest request, CancellationToken cancellationToken)
    {
        await _serviceClient.SendToAllAsync(RequestContent.Create(
        new
        {
            from = request.ConnectionContext.UserId,
            message = request.Data.ToString()
        }),
        ContentType.ApplicationJson);

        return new UserEventResponse();
    }
}

Yukarıdaki kodda, JSON biçiminde bir bildirim mesajını SendToAllAsync ile katılmış olan herkese göndermek için hizmet istemcisini kullanırız.

Web sayfasını güncelleştirme

Şimdi bağlanacak, ileti gönderecek ve alınan iletileri sayfada görüntüleyecek mantığı ekleyecek şekilde güncelleştirelim index.html .

<html>
  <body>
    <h1>Azure Web PubSub Chat</h1>
    <input id="message" placeholder="Type to chat...">
    <div id="messages"></div>
    <script>
      (async function () {
        let id = prompt('Please input your user name');
        let res = await fetch(`/negotiate?id=${id}`);
        let data = await res.json();
        let ws = new WebSocket(data.url);
        ws.onopen = () => console.log('connected');

        let messages = document.querySelector('#messages');
        
        ws.onmessage = event => {
          let m = document.createElement('p');
          let data = JSON.parse(event.data);
          m.innerText = `[${data.type || ''}${data.from || ''}] ${data.message}`;
          messages.appendChild(m);
        };

        let message = document.querySelector('#message');
        message.addEventListener('keypress', e => {
          if (e.charCode !== 13) return;
          ws.send(message.value);
          message.value = '';
        });
      })();
    </script>
  </body>

</html>

Yukarıdaki kodda, tarayıcıdaki yerel WebSocket API’sine bağlandığımızı ve mesaj göndermek için WebSocket.send(), alınan mesajları dinlemek için ise WebSocket.onmessage kullandığımızı görebilirsiniz.

Ayrıca hizmete bağlanmak için İstemci SDK'larını da kullanabilirsiniz. Bu da sizi otomatik yeniden bağlama, hata işleme ve daha fazlası ile güçlendirebilir.

Artık sohbetin çalışması için bir adım kaldı. Hangi olayları önemsediğimizi ve Web PubSub hizmetinde olayları nereye gönderebileceğimizi yapılandıralım.

Olay işleyicisini ayarlama

Web PubSub hizmetinde olay işleyicisini, hizmete olayların nereye gönderileceğine söyleyecek şekilde ayarladık.

Web sunucusu yerel olarak çalıştırıldığında, web PubSub hizmeti internetten erişilebilen uç noktası yoksa localhost'ı nasıl çağırır? Genellikle iki yol vardır. Bunlardan biri, localhost’u genel erişime açmak için genel amaçlı bir tünel aracını kullanmak; diğeri ise Web PubSub hizmetinden gelen trafiği araç üzerinden yerel sunucunuza tünellemek için awps-tunnel kullanmaktır.

Bu bölümde, olay işleyicilerini ayarlamak için Azure CLI'yi ve trafiği localhost'a yönlendirmek için awps-tunnel kullanacağız.

Hub ayarlarını yapılandırma

Web PubSub'un iletileri awps-tunnel'in tünel bağlantısı üzerinden yönlendirmesi için URL şablonunu tunnel şemasını kullanacak şekilde ayarladık. Olay işleyicileri, bu makalede açıklandığı gibi portaldan veya CLI'dan ayarlanabilir. Burada CLI aracılığıyla ayarlayacağız. Önceki adımda ayarlandığı gibi, /eventhandler yolundaki olayları dinlediğimiz için URL şablonunu tunnel:///eventhandler olarak ayarlarız.

Sample_ChatApp hub için olay işleyicisi ayarlarını oluşturmak üzere az webpubsub hub create Azure CLI komutunu kullanın.

Önemli

benzersiz-kaynak-adınızı< önceki adımlardan oluşturulan Web PubSub kaynağınızın adıyla değiştirin>.

az webpubsub hub create -n "<your-unique-resource-name>" -g "myResourceGroup" --hub-name "Sample_ChatApp" --event-handler url-template="tunnel:///eventhandler" user-event-pattern="*" system-event="connected"

awps-tunnel'ı yerel olarak çalıştırma

awps-tunnel indirme ve yükleme

Araç, Node.js sürüm 16 veya üzeri üzerinde çalışır.

npm install -g @azure/web-pubsub-tunnel-tool

Hizmet bağlantı dizesini kullanın ve çalıştırın

export WebPubSubConnectionString="<your connection string>"
awps-tunnel run --hub Sample_ChatApp --upstream http://localhost:8080

Web sunucusunu çalıştırma

Artık her şey ayarlandı. Şimdi web sunucusunu çalıştıralım ve sohbet uygulamasını çalışır durumda oynatalım.

Şimdi sunucuyu dotnet run --urls http://localhost:8080 kullanarak çalıştırın.

Bu öğreticinin tam kod örneğini burada bulabilirsiniz.

http://localhost:8080/index.html'ı açın. Kullanıcı adınızı girip sohbet etmeye başlayabilirsiniz.

Olay işleyicisi ile Gecikmeli connect Kimlik Doğrulaması

Önceki bölümlerde, istemcilerin Web PubSub hizmetine bağlanması için Web PubSub hizmet URL'sini ve JWT erişim belirtecini döndürmek için anlaşma uç noktasının nasıl kullanılacağını gösteriyoruz. Bazı durumlarda, örneğin, kaynakları sınırlı olan uç cihazlar, istemciler Web PubSub kaynaklarına doğrudan bağlanmayı tercih edebilir. Bu gibi durumlarda, istemcilere yavaş kimlik doğrulaması yapmak, istemcilere kullanıcı kimliği atamak, istemcilerin bağlandıktan sonra katıldığı grupları belirtmek, istemcilerin sahip olduğu izinleri ve WebSocket altprotocol'u istemciye WebSocket yanıtı olarak yapılandırmak için olay işleyicisini yapılandırabilirsinizconnect. Ayrıntılar lütfen olay işleyicisi belirtimini bağlama konusuna bakın.

Şimdi olay işleyicisini kullanarak connect anlaşma bölümünün yaptığı gibi benzer bir sonuç elde edelim.

Hub ayarlarını güncelleştirme

İlk olarak hub ayarlarını olay işleyicisini de içerecek connect şekilde güncelleştirelim. JWT erişim belirteci olmayan istemcilerin hizmete bağlanabilmesi için anonim bağlantıya da izin vermemiz gerekiyor.

Sample_ChatApp hub’ı için olay işleyicisi ayarlarını oluşturmak üzere Azure CLI az webpubsub hub update komutunu kullanın.

Önemli

benzersiz-kaynak-adınızı< önceki adımlardan oluşturulan Web PubSub kaynağınızın adıyla değiştirin>.

az webpubsub hub update -n "<your-unique-resource-name>" -g "myResourceGroup" --hub-name "Sample_ChatApp" --allow-anonymous true --event-handler url-template="tunnel:///eventhandler" user-event-pattern="*" system-event="connected" system-event="connect"

Bağlantı olayını işlemek için yukarı akış mantığını güncelleştirme

Şimdi bağlantı olayını işlemek için yukarı akış mantığını güncelleştirelim. Şimdi anlaşma uç noktasını da kaldırabiliriz.

Demo amacıyla negotiate uç noktasında yaptığımıza benzer şekilde, id’yi sorgu parametrelerinden de okuruz. Connect olayında, özgün istemci sorgusu bağlanma olayı istek gövdesinde korunur.

Sample_ChatApp sınıfının içinde, connect olayını işlemek için OnConnectAsync() öğesini geçersiz kılın:

sealed class Sample_ChatApp : WebPubSubHub
{
    private readonly WebPubSubServiceClient<Sample_ChatApp> _serviceClient;

    public Sample_ChatApp(WebPubSubServiceClient<Sample_ChatApp> serviceClient)
    {
        _serviceClient = serviceClient;
    }

    public override ValueTask<ConnectEventResponse> OnConnectAsync(ConnectEventRequest request, CancellationToken cancellationToken)
    {
        if (request.Query.TryGetValue("id", out var id))
        {
            return new ValueTask<ConnectEventResponse>(request.CreateResponse(userId: id.FirstOrDefault(), null, null, null));
        }

        // The SDK catches this exception and returns 401 to the caller
        throw new UnauthorizedAccessException("Request missing id");
    }

    public override async Task OnConnectedAsync(ConnectedEventRequest request)
    {
        Console.WriteLine($"[SYSTEM] {request.ConnectionContext.UserId} joined.");
    }

    public override async ValueTask<UserEventResponse> OnMessageReceivedAsync(UserEventRequest request, CancellationToken cancellationToken)
    {
        await _serviceClient.SendToAllAsync(RequestContent.Create(
        new
        {
            from = request.ConnectionContext.UserId,
            message = request.Data.ToString()
        }),
        ContentType.ApplicationJson);

        return new UserEventResponse();
    }
}

Index.html doğrudan bağlanacak şekilde güncelleştirme

Şimdi Web PubSub hizmetine doğrudan bağlanmak için web sayfasını güncelleştirelim. Belirtilmesi gereken bir nokta, Web PubSub hizmeti uç noktasının şu anda demo amacıyla istemci kodunda sabit kodlanmış olmasıdır; lütfen aşağıdaki HTML içindeki hizmet ana bilgisayar adını <the host name of your service> kendi hizmetinizin değeriyle güncelleyin. Web PubSub hizmet uç noktası değerini sunucunuzdan getirmek hala yararlı olabilir; istemcinin bağlandığı yere daha fazla esneklik ve denetlenebilirlik sağlar.

<html>
  <body>
    <h1>Azure Web PubSub Chat</h1>
    <input id="message" placeholder="Type to chat...">
    <div id="messages"></div>
    <script>
      (async function () {
        // sample host: mock.webpubsub.azure.com
        let hostname = "<the host name of your service>";
        let id = prompt('Please input your user name');
        let ws = new WebSocket(`wss://${hostname}/client/hubs/Sample_ChatApp?id=${id}`);
        ws.onopen = () => console.log('connected');

        let messages = document.querySelector('#messages');
        
        ws.onmessage = event => {
          let m = document.createElement('p');
          let data = JSON.parse(event.data);
          m.innerText = `[${data.type || ''}${data.from || ''}] ${data.message}`;
          messages.appendChild(m);
        };

        let message = document.querySelector('#message');
        message.addEventListener('keypress', e => {
          if (e.charCode !== 13) return;
          ws.send(message.value);
          message.value = '';
        });
      })();
    </script>
  </body>

</html>

Sunucuyu yeniden çalıştırma

Şimdi sunucuyu yeniden çalıştırın ve önceki yönergeleri izleyerek web sayfasını ziyaret edin. awps-tunnel durdurduysanız, lütfen tünel aracını yeniden çalıştırın.

Sonraki adımlar

Bu öğretici, Azure Web PubSub hizmetinde olay sisteminin nasıl çalıştığı hakkında temel bir fikir sağlar.

Hizmetin nasıl kullanılacağı hakkında daha fazla bilgi edinmek için diğer öğreticileri gözden geçirin.

Diğer Azure Web PubSub örneklerini keşfedin

  • Last updated on