Azure Web PubSub hizmeti iç işlevleri

Azure Web PubSub Hizmeti, basit WebSocket bağlantılarını kullanarak iletileri yayımlamak/abone olmak için kolay bir yol sağlar.

• İstemciler WebSocket desteği olan herhangi bir dilde yazılabilir.
• Hem metin hem de ikili iletiler tek bir bağlantıda desteklenir.
• Basit bir protokol, istemcilerin masajları doğrudan birbirlerine yayımlamalarını sağlar.
• Hizmet, WebSocket bağlantılarını sizin için yönetir.

Terimler

• Hizmet: Azure Web PubSub Hizmeti.

• Bağlantı: İstemci veya istemci bağlantısı olarak da bilinen bağlantı, istemci ile Web PubSub hizmeti arasındaki mantıksal bir ilişkidir. Bir 'bağlantı' üzerinden, istemci ve hizmet durum bilgisi olan bir dizi etkileşimde bulunur. Farklı protokoller kullanan bağlantılar farklı davranabilir, örneğin, bazı bağlantılar ağ bağlantısının süresiyle sınırlandırılırken, diğerleri bir istemci ile hizmet arasında ardışık birden çok ağ bağlantısına yayılabilir.

• Hub: Hub, bir dizi istemci bağlantısı için mantıksal bir kavramdır. Genellikle bir senaryo için bir hub kullanırsınız, örneğin sohbet hub'ı veya bildirim hub'ı. bir istemci bağlantısı bağlandığında bir hub'a bağlanır ve kullanım ömrü boyunca bu hub'a aittir. bir istemci bağlantısı hub'a bağlandıktan sonra hub mevcut olur. Farklı uygulamalar, farklı hub adlarını kullanarak bir Azure Web PubSub hizmetini paylaşabilir. Hub sayısı üzerinde kesin bir sınır olmasa da, hub bir grupla karşılaştırıldığında daha fazla hizmet yükü tüketir. Bunları dinamik olarak oluşturmak yerine önceden belirlenmiş bir hub kümesine sahip olmanız önerilir.

• Grup: Grup, hub'a bağlantıların bir alt kümesidir. Bir gruba istemci bağlantısı ekleyebilir veya istemci bağlantısını istediğiniz zaman gruptan kaldırabilirsiniz. Örneğin, bir istemci bir sohbet odasına katıldığında veya bir istemci sohbet odasından ayrıldığında, bu sohbet odası bir grup olarak kabul edilebilir. bir istemci birden çok gruba katılabilir ve bir grup birden çok istemci içerebilir. Grup bir grup "oturumu" gibidir, bir kişi gruba katıldıktan sonra grup oturumu oluşturulur ve grupta kimse olmadığında oturum kaybolur. Gruba gönderilen iletiler, gruba bağlı tüm istemcilere teslim edilir.

• Kullanıcı: Web PubSub bağlantıları tek bir kullanıcıya ait olabilir. Bir kullanıcının birden çok bağlantısı olabilir; örneğin, tek bir kullanıcı birden çok cihaza veya birden çok tarayıcı sekmesine bağlandığında.

• İleti: İstemci bağlandığında, WebSocket bağlantısı aracılığıyla yukarı akış uygulamasına ileti gönderebilir veya yukarı akış uygulamasından ileti alabilir. İletiler düz metin, ikili veya JSON biçiminde olabilir ve boyut üst sınırı 1 MB olabilir.

• İstemci Olayları: Olaylar, istemci bağlantısının yaşam döngüsü sırasında oluşturulur. Örneğin, basit bir WebSocket istemci bağlantısı hizmete bağlanmaya çalıştığında bir connect olay, hizmete başarıyla bağlandığında bir connected olay, hizmete varsayılan modunda sendEvent ileti gönderdiğinde bir message olay ve hizmetle bağlantısı kesildiğinde bir disconnected olay oluşturur. İstemci olayları hakkındaki ayrıntılar İstemci protokolü bölümünde gösterilmiştir.

• Olay İşleyicisi: Olay işleyicisi, istemci olaylarını işleme mantığını içerir. Portal veya Azure CLI aracılığıyla hizmette olay işleyicilerini önceden kaydedin ve yapılandırın. Ayrıntılar Olay işleyicisi bölümünde açıklanmıştır.

• Olay Dinleyicisi(önizleme): Olay dinleyicisi yalnızca istemci olaylarını dinler, ancak yanıtlarıyla istemcilerinizin ömrünü engelleyemez. Ayrıntılar Olay dinleyicisi bölümünde açıklanmıştır.

• Sunucu: Sunucu istemci olaylarını işleyebilir, istemci bağlantılarını yönetebilir veya iletileri gruplara yayımlayabilir. Hem olay işleyicisi hem de olay dinleyicisi sunucu tarafı olarak kabul edilir. Sunucuyla ilgili ayrıntılar Sunucu protokolü bölümünde açıklanmıştır.

İş Akışı

Yukarıdaki grafikte gösterildiği gibi iş akışı:

1. İstemci, WebSocket aktarımını kullanarak hizmet /client uç noktasına bağlanır. Hizmet, her WebSocket çerçevesini varsayılan olarak yapılandırılan yukarı akışa (sunucu) iletir. WebSocket bağlantısı, sunucunun işleyebileceği herhangi bir özel alt protokole bağlanabilir. Alternatif olarak, istemci moda sendToGroup bağlanabilir ve her WebSocket çerçevesini belirli bir gruba gönderebilir. İstemci, yukarı akışınıza olay gönderme, grupları birleştirme ve gruplara doğrudan ileti gönderme gibi özellikler sunan hizmet tarafından desteklenen alt protokollerle de bağlanabilir. Ayrıntılar istemci protokolünde açıklanmıştır.
2. Farklı istemci olaylarında hizmet, CloudEvents protokolunu kullanarak sunucuyu çağırır. CloudEvents , Cloud Native Computing Foundation (CNCF) tarafından barındırılan olayların yapısının ve meta veri açıklamasının standartlaştırılmış ve protokolden bağımsız bir tanımıdır. CloudEvents protokolünün ayrıntılı uygulaması, sunucu protokolünde açıklanan sunucu rolüne dayanır.
3. Web PubSub sunucusu, istemcilere ileti göndermek veya bağlı istemcileri yönetmek için REST API kullanarak hizmeti çağırabilir. Ayrıntılar sunucu protokolünde açıklanmıştır

İstemci protokolü

İstemci bağlantısı, WebSocket protokolünün kullanıldığı hizmetin uç noktasına bağlanır/client. WebSocket protokolü, tek bir TCP bağlantısı üzerinden tam çift yönlü iletişim kanalları sağlar ve IETF tarafından 2011'de RFC 6455 olarak standartlaştırılmıştır. Çoğu dil, WebSocket bağlantılarını başlatmak için yerel desteğe sahiptir.

Hizmetimiz iki tür istemciyi destekler:

• Biri basit WebSocket istemcisi olarak adlandırılır
• Diğer adı PubSub WebSocket istemcisidir

Basit WebSocket istemcisi

Adlandırmanın da belirttiği gibi basit bir WebSocket istemcisi basit bir WebSocket bağlantısıdır. Ayrıca özel altprotocol'una da sahip olabilir.

Örneğin, JS'de aşağıdaki kod kullanılarak basit bir WebSocket istemcisi oluşturulabilir.

// simple WebSocket client1
var client1 = new WebSocket("wss://test.webpubsub.azure.com/client/hubs/hub1");

// simple WebSocket client2 with some custom subprotocol
var client2 = new WebSocket(
  "wss://test.webpubsub.azure.com/client/hubs/hub1",
  "custom.subprotocol"
);

Basit WebSocket istemcisinin iki modu vardır. Aşağıdaki sıralı diyagramda gösterildiği gibi varsayılan modu sendEvent bir istemci-sunucu<> mimarisini izler:

1. İstemci bir WebSocket el sıkışması başlattığında, hizmet WebSocket el sıkışması connect için olay işleyicisini çağırmaya çalışır. Geliştiriciler WebSocket el sıkışmasını işlemek, kullanılacak altprotokolü belirlemek, istemcinin kimliğini doğrulamak ve istemciyi gruplara eklemek için bu işleyiciyi kullanabilir.
2. İstemci başarıyla bağlandığında, hizmet bir connected olay işleyicisi çağırır. Bildirim olarak çalışır ve istemcinin ileti göndermesini engellemez. Geliştiriciler veri depolama yapmak için bu işleyiciyi kullanabilir ve istemciye iletilerle yanıt verebilir. Hizmet ayrıca, varsa olay dinleyicileri ile ilgili tüm ilgili olaylara bir connected olay da iletir.
3. İstemci ileti gönderdiğinde, hizmet olay işleyicisine bir message olay tetikler. Bu olay bir WebSocket çerçevesinde gönderilen iletileri içerir. Kodunuzun iletileri bu olay işleyicisinin içinde göndermesi gerekir. Olay işleyicisi başarısız bir yanıt kodu döndürürse, hizmet istemci bağlantısını bırakır. Hizmet ayrıca bir message olayı varsa ilgili tüm olay dinleyicilerine gönderir. Hizmet, iletileri almak için kayıtlı sunucu bulamazsa istemci bağlantısını da bırakır.
4. İstemcinin bağlantısı kesildiğinde, hizmet bağlantıyı algıladığında olayı olay işleyicisine tetiklemeye disconnected çalışır. Hizmet ayrıca, varsa olay dinleyicileri ile ilgili tüm ilgili olaylara bir disconnected olay da iletir.

Senaryolar

Bu bağlantılar, istemcinin sunucuya ileti gönderdiği ve sunucunun Olay İşleyicileri kullanarak gelen iletileri işlediği tipik bir istemci-sunucu mimarisinde kullanılabilir. Müşteriler uygulama mantığına mevcut alt protokolleri uyguladığında da kullanılabilir.

PubSub WebSocket istemcisi

Hizmet, istemcileri yukarı akış sunucusuna gidiş dönüş yerine doğrudan yayımlama/abone olma konusunda güçlendiren adlı json.webpubsub.azure.v1belirli bir altprotocol'u da destekler. Altprotocol ile json.webpubsub.azure.v1 WebSocket bağlantısını PubSub WebSocket istemcisi olarak adlandırıyoruz. Daha fazla bilgi için GitHub'da Web PubSub istemci belirtimine bakın.

Örneğin, JS'de pubsub WebSocket istemcisi aşağıdaki kod kullanılarak oluşturulabilir.

// PubSub WebSocket client
var pubsub = new WebSocket(
  "wss://test.webpubsub.azure.com/client/hubs/hub1",
  "json.webpubsub.azure.v1"
);

PubSub WebSocket istemcisi şu işlemleri yapabilir:

• Gruba katılın, örneğin:

  {
    "type": "joinGroup",
    "group": "<group_name>"
  }
  

• Gruptan ayrıl, örneğin:

  {
    "type": "leaveGroup",
    "group": "<group_name>"
  }
  

• İletileri bir gruba yayımlama, örneğin:

  {
    "type": "sendToGroup",
    "group": "<group_name>",
    "data": { "hello": "world" }
  }
  

• Yukarı akış sunucusuna özel olaylar gönderin, örneğin:

  {
    "type": "event",
    "event": "<event_name>",
    "data": { "hello": "world" }
  }
  

PubSub WebSocket Subprotocol, altprotocol'unjson.webpubsub.azure.v1 ayrıntılarını içerir.

Basit WebSocket istemcisinin dafult modundasendEvent, sunucuistemcilerden olayları almak message için bir role sahip olmalıdır. Modda sendEvent basit bir WebSocket bağlantısı her zaman ileti gönderdiğinde bir message olayı tetikler ve iletileri işlemek ve diğer işlemleri yapmak için her zaman sunucu tarafında çalışır. Bu sendToGroup mod, istemcilere yalnızca sunucuya yönelik istekleri tetiklemeden doğrudan gruplara ileti yayımlama gücü sağlar ve bu da hala sınırlıdır. json.webpubsub.azure.v1 subprotocol, istemcilerin sunucuya yönelik istekleri tetiklemeden çok daha fazlasını yapmalarını sağlar. Bunun yardımıyla, yetkili bir istemci bir gruba katılabilir ve iletileri doğrudan bir gruba yayımlayabilir. Ayrıca, iletinin ait olduğu olayı özelleştirerek iletileri farklı olay işleyicilerine /olay dinleyicilerine yönlendirebilir.

Senaryolar

Bu tür istemciler, istemciler birbirleriyle konuşmak istediğinde kullanılabilir. İletiler hizmetten client2 gönderilir ve istemciler bu yetkiye sahipse hizmet iletiyi doğrudan client1 adresine gönderir.

İstemci1:

var client1 = new WebSocket(
  "wss://xxx.webpubsub.azure.com/client/hubs/hub1",
  "json.webpubsub.azure.v1"
);
client1.onmessage = (e) => {
  if (e.data) {
    var message = JSON.parse(e.data);
    if (message.type === "message" && message.group === "Group1") {
      // Only print messages from Group1
      console.log(message.data);
    }
  }
};

client1.onopen = (e) => {
  client1.send(
    JSON.stringify({
      type: "joinGroup",
      group: "Group1",
    })
  );
};

İstemci2:

var client2 = new WebSocket("wss://xxx.webpubsub.azure.com/client/hubs/hub1", "json.webpubsub.azure.v1");
client2.onopen = e => {
    client2.send(JSON.stringify({
        type: "sendToGroup",
        group: "Group1",
        data: "Hello Client1"
    });
};

Yukarıdaki örnekte gösterildiği gibi, client2 içinde bulunduğu client1 iletileri yayımlayarak verileri doğrudan client1 adresine Group1 gönderir.

İstemci olayları özeti

İstemci olayları iki kategoriye ayrılır:

• Zaman uyumlu olaylar (engelleme) Zaman uyumlu olaylar istemci iş akışını engeller.

  • connect: Bu olay yalnızca olay işleyici içindir. İstemci bir WebSocket el sıkışması başlattığında, olay tetikler ve geliştiriciler WebSocket el sıkışmasını işlemek, kullanılacak altprotokolü belirlemek, istemcinin kimliğini doğrulamak ve istemciyi gruplara eklemek için olay işleyicisini kullanabilir connect .
  • message: İstemci bir ileti gönderdiğinde bu olay tetikleniyor.

• Zaman uyumsuz olaylar (engelleyici olmayan) Zaman uyumsuz olaylar istemci iş akışını engellemez. Bunun yerine sunucuya bir bildirim gönderir. Böyle bir olay tetikleyicisi başarısız olduğunda hizmet hata ayrıntılarını günlüğe kaydeder.

  • connected: İstemci hizmete başarıyla bağlandığında bu olay tetikleniyor.
  • disconnected: İstemcinin hizmetle bağlantısı kesildiğinde bu olay tetikleniyor.

İstemci ileti sınırı

Bir WebSocket çerçevesi için izin verilen ileti boyutu üst sınırı 1 MB'tır.

İstemci kimlik doğrulaması

Kimlik doğrulaması iş akışı

İstemci, hizmete bağlanmak için imzalı bir JWT belirteci kullanır. Yukarı akış, gelen istemcinin olay işleyicisi olduğunda connect da istemciyi reddedebilir. Olay işleyicisi, istemcinin web kancası yanıtında sahip olduğu ve roledeğerlerini belirterek userId istemcinin kimliğini doğrular veya istemciyi 401 ile reddeder. Olay işleyicisi bölümü bunu ayrıntılı olarak açıklar.

Aşağıdaki grafikte iş akışı açıklanmaktadır.

bir istemci diğer istemcilere yalnızca yetkilendirildiğinde yayımlayabilir. roleİstemcinin s'leri, istemcinin sahip olduğu ilk izinleri belirler:

Sunucu tarafı, daha sonraki bir bölümde gösterildiği gibi sunucu protokolü aracılığıyla istemcinin izinlerini dinamik olarak verebilir veya iptal edebilir.

Sunucu protokolü

Sunucu protokolü, sunucuya istemci olaylarını işleme ve istemci bağlantılarını ve grupları yönetme işlevselliği sağlar.

Genel olarak, sunucu protokolü üç rol içerir:

1. Olay işleyicisi
2. Bağlantı yöneticisi
3. Olay dinleyicisi

Olay işleyicisi

Olay işleyicisi gelen istemci olaylarını işler. Olay işleyicileri portal veya Azure CLI aracılığıyla hizmete kaydedilir ve yapılandırılır. bir istemci olayı tetiklendiğinde, hizmet olayın işlenip işlenmediğini belirleyebilir. Şimdi olay işleyicisini çağırmak için modu kullanıyoruz PUSH . Sunucu tarafındaki olay işleyicisi, olay tetiklendiğinde hizmetin çağırması için genel olarak erişilebilir bir uç nokta sunar. Bir web kancası işlevi görür.

Web PubSub hizmeti CloudEvents HTTP protokolunu kullanarak istemci olaylarını yukarı akış web kancasına teslim eder.

Her olay için hizmet, kayıtlı yukarı akışa bir HTTP POST isteği formüle eder ve bir HTTP yanıtı bekler.

Hizmetten sunucuya gönderilen veriler her zaman CloudEvents binary biçimindedir.

Yukarı akış ve Doğrulama

Olay işleyicilerinin ilk kullanımdan önce portal veya Azure CLI aracılığıyla hizmete kaydedilmesi ve yapılandırılması gerekir. bir istemci olayı tetiklendiğinde, hizmet olayın işlenmesi gerekip gerekmediğini belirleyebilir. Genel önizleme için, olay işleyicisini çağırmak için modu kullanırız PUSH . Sunucu tarafındaki olay işleyicisi, olay tetiklendiğinde hizmetin çağırması için genel olarak erişilebilen uç noktayı kullanıma sunar. Web kancası yukarı akışı işlevi görür.

URL, web kancası işleyicisi için bir URL şablonu tanımlamak için parametresini kullanabilir {event} . Hizmet, istemci isteği geldiğinde web kancası URL'sinin değerini dinamik olarak hesaplar. Örneğin, bir istek /client/hubs/chat geldiğinde, hub chatiçin yapılandırılmış bir olay işleyici URL'si deseni http://host.com/api/{event} ile istemci bağlandığında, ilk olarak şu URL'ye POST olur: http://host.com/api/connect. Bir PubSub WebSocket istemcisi özel olaylar gönderdiğinde, olay işleyicisinin farklı yukarı akışa farklı olaylar göndermeye yardımcı olması bu davranış yararlı olabilir. {event} URL etki alanı adında parametresine izin verilmez.

Azure portalı veya CLI aracılığıyla olay işleyici yukarı akışını ayarlarken hizmet, yukarı akış web kancasını doğrulamak için CloudEvents kötüye kullanım korumasını izler. İstek WebHook-Request-Origin üst bilgisi hizmet etki alanı adına xxx.webpubsub.azure.comayarlanır ve üst WebHook-Allowed-Origin bilgi içeren yanıtın bu etki alanı adını içermesini bekler.

Doğrulama {event} yapılırken parametresi olarak validateçözümlenir. Örneğin, URL'yi http://host.com/api/{event}olarak ayarlamaya çalışırken, hizmet bir isteğin http://host.com/api/validate SEÇENEKLERİne çalışır ve yalnızca yanıt geçerli olduğunda yapılandırma başarıyla ayarlanabilir.

Şimdilik WebHook-Request-Rate ve WebHook-Request-Callback'i desteklemiyoruz.

Hizmet ve web kancası arasında kimlik doğrulaması/yetkilendirme

Hizmetinizle web kancası arasında güvenli kimlik doğrulaması ve yetkilendirme oluşturmak için aşağıdaki seçenekleri ve adımları göz önünde bulundurun:

• Anonim mod
• Yapılandırılmış Web Kancası URL'si aracılığıyla sağlanan basit kimlik doğrulaması code .
• Microsoft Entra yetkilendirmesini kullanın. Daha fazla bilgi için bkz . Yönetilen kimliği kullanma.

1. Web PubSub hizmeti için Kimlik'i etkinleştirin.
2. Web kancası web uygulamanızın kısaltması olan mevcut Microsoft Entra uygulamasından seçim yapın.

Bağlantı yöneticisi

Sunucu doğası gereği yetkili bir kullanıcıdır. Sunucu, olay işleyicisi rolünün yardımıyla istemcilerin meta verilerini (örneğin, connectionId ve) bilir, userIdböylece şunları yapabilir:

• İstemci bağlantısını kapatma
• İstemciye ileti gönderme
• Aynı kullanıcıya ait istemcilere ileti gönderme
• Gruba istemci ekleme
• Bir gruba aynı kullanıcı olarak kimliği doğrulanmış istemciler ekleme
• Gruptan istemci kaldırma
• Bir gruptan aynı kullanıcıyla kimliği doğrulanmış istemcileri kaldırma
• İletileri bir gruba yayımlama

Ayrıca PubSub istemcisi için yayımlama/katılma izinleri verebilir veya iptal edebilir:

• Belirli bir gruba veya tüm gruplara yayımlama/katılma izinleri verme
• Belirli bir grup veya tüm gruplar için yayımlama/birleştirme izinlerini iptal etme
• İstemcinin belirli bir gruba veya tüm gruplara katılma veya yayımlama izni olup olmadığını denetleyin

Hizmet, sunucunun bağlantı yönetimi yapması için REST API'leri sağlar.

Ayrıntılı REST API protokolü burada tanımlanmıştır.

Olay dinleyicisi

Olay dinleyicisi gelen istemci olaylarını dinler. Her olay dinleyicisi, hangi olay türlerinin ilgileneceğini belirten bir filtre, olayların nereye gönderileceğiyle ilgili bir uç nokta içerir.

Şu anda olay dinleyicisi uç noktası olarak Event Hubs'ı destekliyoruz.

Bir istemci olayı tetiklendiğinde hizmetin olayı ilgili olay dinleyicilerine gönderebilmesi için olay dinleyicilerini önceden kaydetmeniz gerekir. Olay hub'ı uç noktasıyla olay dinleyicisini yapılandırma hakkında bilgi edinmek için bu belgeyi görüntüleyin.

Birden çok olay dinleyicisi yapılandırabilirsiniz. Bunları yapılandırma sırası işlevlerini etkilemez. Bir olay birden çok dinleyiciyle eşleşiyorsa, olay eşleşen tüm dinleyicilere gönderilir. Bir örnek için aşağıdaki diyagrama bakın. Örneğin, aynı anda dört olay dinleyicisi yapılandırıyorsanız, bir eşleşme alan her dinleyici olayı işler. Bu dinleyicilerden üçüyle eşleşen bir istemci olayı, kalan dinleyicinin yoksayıldığı üç dinleyiciye gönderilir.

Aynı olay için bir olay işleyicisini ve olay dinleyicilerini birleştirebilirsiniz. Bu durumda hem olay işleyicisi hem de olay dinleyicileri olayı alır.

Web PubSub hizmeti, Azure Web PubSub için CloudEvents AMQP uzantısını kullanarak olay dinleyicilerine istemci olayları sunar.

Özet

Olay işleyicisi rolü hizmetten sunucuya iletişimi işlerken , yönetici rolü sunucudan hizmete iletişimi işler. İki rolü birleştirdikten sonra, hizmet ve sunucu arasındaki veri akışı HTTP protokolunu kullanarak aşağıdaki diyagrama benzer.

Sonraki adımlar

Kendi uygulamanızı oluşturmaya başlamak için şu kaynakları kullanın: