Aracılığıyla paylaş

JavaScript için Web PubSub istemci kitaplığı

  • Makale

Azure Web PubSub , geliştiricilerin büyük ölçekte yayımlama-abone olma desenleriyle web uygulamalarında gerçek zamanlı özellikleri kolayca oluşturmalarına yardımcı olan bir bulut hizmetidir.

Sunucu ile istemciler arasında veya yayımla-abone ol desenlerini izleyen istemciler arasında gerçek zamanlı mesajlaşma gerektiren tüm senaryolar Web PubSub'un kullanılmasından yararlanabilir. Geliştiricilerin artık zaman aralıklarında yinelenen HTTP istekleri göndererek sunucuyu yoklaması gerekmez ve bu da boşa harcanabilir ve ölçeklendirilmesi zor olur.

Aşağıdaki diyagramda gösterildiği gibi, istemcileriniz Web PubSub kaynağınızla WebSocket bağlantıları kurar. Bu istemci kitaplığı:

  • istemci bağlantılarını yönetmeyi basitleştirir
  • istemciler arasında ileti göndermeyi basitleştirir
  • İstenmeyen istemci bağlantısı bırakıldıktan sonra otomatik olarak yeniden denemeler
  • bağlantı bırakmalarından kurtarıldıktan sonra iletileri sayı ve sırayla güvenilir bir şekilde teslim ediyor

Taşma

Burada kullanılan terimlerle ilgili ayrıntılar temel kavramlar bölümünde açıklanmıştır.

Bu kitaplık NPM'de barındırılır.

Başlarken

Şu anda desteklenen ortamlar

Önkoşullar

1. Paketi yükleyin @azure/web-pubsub-client

npm install @azure/web-pubsub-client

2. Web PubSub kaynağınıza bağlanma

İstemci, hizmete bağlanmak ve hizmetle kimlik doğrulaması yapmak için bir İstemci Erişim URL'si kullanır ve bu da desenini wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>izler. İstemcinin İstemci Erişim URL'sini almak için birkaç yolu olabilir. Bu hızlı başlangıç için aşağıda gösterilen Azure Portalı'ndan kopyalayıp yapıştırabilirsiniz. (Üretim için, istemcileriniz genellikle uygulama sunucunuzda genel olarak dağıtılan İstemci Erişimi URL'sini alır. Aşağıdaki ayrıntılara bakın )

get_client_url

Yukarıdaki diyagramda gösterildiği gibi, istemcinin "group1" adlı belirli bir gruba ileti gönderme ve gruba katılma izinleri vardır.

// Imports the client libray
const { WebPubSubClient } = require("@azure/web-pubsub-client");

// Instantiates the client object
const client = new WebPubSubClient("<client-access-url>");

// Starts the client connection with your Web PubSub resource
await client.start();

// ...
// The client can join/leave groups, send/receive messages to and from those groups all in real-time

3. Gruplara katılma

İstemcinin yalnızca katıldığı gruplardan ileti alabildiğini ve iletileri alırken mantığı belirtmek için bir geri çağırma eklemeniz gerektiğini unutmayın.

// ...continues the code snippet from above

// Specifies the group to join
let groupName = "group1";

// Registers a listener for the event 'group-message' early before joining a group to not miss messages
client.on("group-message", (e) => {
  console.log(`Received message: ${e.message.data}`);
});

// A client needs to join the group it wishes to receive messages from
await client.joinGroup(groupName);

4. Gruba ileti gönderme

// ...continues the code snippet from above

// Send a message to a joined group
await client.sendToGroup(groupName, "hello world", "text");

// In the Console tab of your developer tools found in your browser, you should see the message printed there.

Örnekler

Bağlı, bağlantısı kesilmiş ve durdurulmuş olaylar için geri arama ekleme

  1. bir istemci Web PubSub kaynağınıza başarıyla bağlandığında, connected olay tetikler.
client.on("connected", (e) => {
  console.log(`Connection ${e.connectionId} is connected.`);
});
  1. bir istemcinin bağlantısı kesildiğinde ve bağlantıyı kurtaramadığında disconnected , olay tetikler.
client.on("disconnected", (e) => {
  console.log(`Connection disconnected: ${e.message}`);
});
  1. İstemcinin stopped bağlantısı kesildiğinde ve istemci yeniden bağlanmayı denemeyi durdurduğunda olay tetiklenir. Bu genellikle çağrıldıktan veya autoReconnect devre dışı bırakıldıktan veya yeniden bağlanmaya çalışırken belirtilen sınıra ulaşıldıktan sonra client.stop() gerçekleşir. İstemciyi yeniden başlatmak istiyorsanız durdurulan olayda öğesini çağırabilirsiniz client.start() .
// Registers a listener for the "stopped" event
client.on("stopped", () => {
  console.log(`Client has stopped`);
});

Program aracılığıyla İstemci Erişimi URL'si oluşturmak için anlaşma sunucusu kullanma

Üretimde istemciler genellikle bir uygulama sunucusundan İstemci Erişim URL'sini getirir. Sunucu, Web PubSub kaynağınızın bağlantı dizesi tutar ve sunucu kitaplığının @azure/web-pubsubyardımıyla İstemci Erişim URL'sini oluşturur.

1. Uygulama sunucusu

Aşağıdaki kod parçacığı bir uygulama sunucusu örneğidir ve bir /negotiate yolu kullanıma sunar ve İstemci Erişimi URL'sini döndürür.

// This code snippet uses the popular Express framework
const express = require('express');
const app = express();
const port = 8080;

// Imports the server library, which is different from the client library
const { WebPubSubServiceClient } = require('@azure/web-pubsub');
const hubName = 'sample_chat';

const serviceClient = new WebPubSubServiceClient("<web-pubsub-connectionstring>", hubName);

// Note that the token allows the client to join and send messages to any groups. It is specified with the "roles" option.
app.get('/negotiate', async (req, res) => {
  let token = await serviceClient.getClientAccessToken({roles: ["webpubsub.joinLeaveGroup", "webpubsub.sendToGroup"] });
  res.json({
    url: token.url
  });
});

app.listen(port, () => console.log(`Application server listening at http://localhost:${port}/negotiate`));

2. İstemci tarafı

Aşağıdaki kod parçacığı, istemci tarafının bir örneğidir.

const { WebPubSubClient } = require("@azure/web-pubsub-client")

const client = new WebPubSubClient({
  getClientAccessUrl: async () => {
    let value = await (await fetch(`/negotiate`)).json();
    return value.url;
  }
});

await client.start();

Bu örneğin tam kodunu görmek için samples-browser konusuna bakın.

İstemci, uygulama sunucusundan veya birleştirilmiş gruplardan gelen iletileri tüketir

İstemci, uygulama sunucunuzdan veya gruplarınızdan gelen iletileri kullanmak için geri çağırmalar ekleyebilir. Olay için group-message istemcinin yalnızca katıldığı grup iletilerini alabileceğini lütfen unutmayın.

// Registers a listener for the "server-message". The callback will be invoked when your application server sends message to the connectionID, to or broadcast to all connections.
client.on("server-message", (e) => {
  console.log(`Received message ${e.message.data}`);
});

// Registers a listener for the "group-message". The callback will be invoked when the client receives a message from the groups it has joined.
client.on("group-message", (e) => {
    console.log(`Received message from ${e.message.group}: ${e.message.data}`);
});

Yeniden katılma hatasını işleme

İstemcinin bağlantısı kesildiğinde ve kurtarılamazsa, Web PubSub kaynağınızda tüm grup bağlamları temizlenir. Bu, istemci yeniden bağlandığında gruplara yeniden katılması gerektiği anlamına gelir. Varsayılan olarak, istemci seçeneği etkindir autoRejoinGroup .

Ancak sınırlamaların autoRejoinGroupfarkında olmanız gerekir.

  • İstemci yalnızca başlangıçta istemci kodu tarafından katılmış olan gruplara sunucu tarafı koduyla değil yeniden bağlanabilir.
  • "Gruba yeniden katılma" işlemleri çeşitli nedenlerle başarısız olabilir; örneğin istemcinin gruplara katılma izni yoktur. Böyle durumlarda, bu hatayı işlemek için bir geri çağırma eklemeniz gerekir.
// By default autoRejoinGroups=true. You can disable it by setting to false.
const client = new WebPubSubClient("<client-access-url>", { autoRejoinGroups: true });

// Registers a listener to handle "rejoin-group-failed" event
client.on("rejoin-group-failed", e => {
  console.log(`Rejoin group ${e.group} failed: ${e.error}`);
})

İşlem ve yeniden deneme

Varsayılan olarak, , client.leaveGroup(), client.sendToGroup()client.sendEvent() gibi client.joinGroup()işlemin üç yeniden denemesi vardır. aracılığıyla messageRetryOptionsyapılandırabilirsiniz. Tüm yeniden denemeler başarısız olursa bir hata oluşur. Web PubSub hizmetinin işlemi yinelenenleri kaldırması için önceki yeniden denemelerle aynı ackId işlemi geçirerek yeniden denemeyi sürdürebilirsiniz.

try {
  await client.joinGroup(groupName);
} catch (err) {
  let id = null;
  if (err instanceof SendMessageError) {
    id = err.ackId;
  }
  await client.joinGroup(groupName, {ackId: id});
}

Altprotocol belirtme

İstemci tarafından kullanılacak altprotokolü değiştirebilirsiniz. Varsayılan olarak, istemci kullanır json.reliable.webpubsub.azure.v1. veya json.webpubsub.azure.v1kullanmayı json.reliable.webpubsub.azure.v1 seçebilirsiniz.

// Change to use json.webpubsub.azure.v1
const client = new WebPubSubClient("<client-access-url>", { protocol: WebPubSubJsonProtocol() });

// Change to use json.reliable.webpubsub.azure.v1
const client = new WebPubSubClient("<client-access-url>", { protocol: WebPubSubJsonReliableProtocol() });

Önemli kavramlar

Bağlantı

İstemci veya istemci bağlantısı olarak da bilinen bağlantı, Web PubSub'a bağlı tek bir WebSocket bağlantısını temsil eder. Başarıyla bağlanıldığında, Web PubSub tarafından bu bağlantıya benzersiz bir bağlantı kimliği atanır. Her WebPubSubClient biri kendi özel bağlantı oluşturur.

Kurtarma

Güvenilir protokoller kullanan bir istemcinin bağlantısı kesilirse, yeni bir WebSocket kayıp bağlantının bağlantı kimliğini kullanarak kurmaya çalışır. Yeni WebSocket bağlantısı başarıyla bağlanırsa, bağlantı kurtarılır. Bir istemcinin bağlantısı kesildiği süre boyunca hizmet, istemcinin bağlamını ve istemcinin abone olduğu tüm iletileri korur ve istemci kurtarıldığında bu iletileri istemciye gönderir. Hizmet WebSocket hata kodu 1008 döndürürse veya kurtarma girişimi 30 saniyeden uzun sürerse kurtarma başarısız olur.

Yeniden bağlan

İstemci bağlantısı bırakıldığında ve kurtarılamadığında yeniden bağlantı gerçekleşir. Yeniden bağlanma yeni bir bağlantı başlatır ve yeni bağlantının yeni bir bağlantı kimliği vardır. Kurtarmadan farklı olarak, hizmet yeniden bağlanan istemciyi yeni bir istemci bağlantısı olarak kabul eder. İstemci bağlantısının gruplara yeniden katılması gerekir. Varsayılan olarak, istemci kitaplığı yeniden bağlantıdan sonra gruplara yeniden katılır.

Hub

Hub, bir dizi istemci bağlantısı için mantıksal bir kavramdır. Genellikle bir hub'ı tek bir amaçla kullanırsınız; örneğin sohbet hub'ı veya bildirim hub'ı. bir istemci bağlantısı oluşturulduğunda bir hub'a bağlanır ve kullanım ömrü boyunca bu hub'a aittir. Farklı uygulamalar, farklı hub adlarını kullanarak bir Web PubSub'ı paylaşabilir.

Grup

Grup, hub'a yönelik 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.

Kullanıcı

Web PubSub'a Connections 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 cihaz veya birden çok tarayıcı sekmesi arasında bağlandığında.

İstemci Ömrü

Web PubSub istemcilerinin her biri önbelleğe alınır ve uygulamanın ömrü boyunca tekil olarak kullanılır. Kayıtlı olay geri çağırmaları istemciyle aynı yaşam süresine sahip olur. Bu, geri çağırmaları istediğiniz zaman ekleyebileceğiniz veya kaldırabileceğiniz anlamına gelir ve yeniden bağlantı veya istemci durdurulduktan sonra kayıt durumu değişmez.

JavaScript Paketi

Bu istemci kitaplığını tarayıcıda kullanmak için önce bir paketleyici kullanmanız gerekir. Bunun nasıl yapılacağının ayrıntıları için lütfen paketleme belgelerimize bakın.

Sorun giderme

  • Günlükleri etkinleştirme

    Bu kitaplığı kullanırken hata ayıklama günlüklerini almak için aşağıdaki ortam değişkenini ayarlayabilirsiniz.

export AZURE_LOG_LEVEL=verbose

Günlükleri etkinleştirme hakkında daha ayrıntılı yönergeler için @azure/günlükçü paketi belgelerine bakabilirsiniz.

Ek kaynaklar

Katkıda bulunma

Bu kitaplığa katkıda bulunmak isterseniz, kodu derleme ve test etme hakkında daha fazla bilgi edinmek için lütfen katkıda bulunma kılavuzunu okuyun.