JavaScript için Web PubSub istemci tarafı SDK'sı

Not

Burada kullanılan terimlerle ilgili ayrıntılar temel kavramlar makalesinde açıklanmıştır.

İstemci tarafı SDK'sı, geliştiricinin iş akışını hızlandırmayı amaçlar; daha ayrıntılı olarak,

istemci bağlantılarını yönetmeyi kolaylaştırır
istemciler arasında ileti göndermeyi kolaylaştırır
İstenmeyen istemci bağlantısı bırakıldıktan sonra otomatik olarak yeniden denenir
bağlantı bırakıldıktan sonra iletileri sayı ve sırayla güvenilir bir şekilde teslim ediyor

Diyagramda gösterildiği gibi, istemcileriniz Web PubSub kaynağınızla WebSocket bağlantıları kurar.

Web PubSub kaynağıyla WebSocket bağlantısı kuran istemcileri gösteren ekran görüntüsü

Önemli

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

bağlantı dizesi, uygulamanızın Azure Web PubSub hizmetine erişmesi için gereken yetkilendirme bilgilerini içerir. bağlantı dizesi içindeki erişim anahtarı, hizmetinizin kök parolasına benzer. Ü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.

Başlarken

Önkoşullar

Node.js LTS sürümleri
Bir Azure aboneliği
Web PubSub kaynağı

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

npm install @azure/web-pubsub-client

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

İstemci, hizmetine bağlanmak ve hizmetle kimlik doğrulaması yapmak için kullanır Client Access URL ve bu da bir deseni izler wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>. İstemcinin elde Client Access URLetmek için birkaç yolu olabilir. Bu hızlı kılavuz için, gösterilen Azure portalından kopyalayıp yapıştırabilirsiniz. (Üretim için istemcileriniz genellikle Client Access URL uygulama sunucunuzda oluşturulur. Ayrıntılara bakın )

Azure portalında İstemci Erişim Url'sini alma işlemini gösteren ekran görüntüsü

Diyagramda gösterildiği gibi, istemciye ileti gönderme ve adlı group1belirli bir gruba katılma izinleri vardır.

// Imports the client library
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

İstemci yalnızca katıldığı gruplardan ileti alabilir. İletileri alırken yapılması gerekenlerin mantığını belirtmek için bir geri arama ekleyebilirsiniz.

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

ve `connecteddisconnected` olaylarını işleme `stopped`

Azure Web PubSub, connected ve disconnectedgibi stoppedsistem olaylarını tetikler. Olaylar tetiklendiğinde programın ne yapacağına karar vermek için olay işleyicilerini kaydedebilirsiniz.

Bir istemci Web PubSub kaynağınıza başarıyla bağlandığında, connected olay tetikler. Bu kod parçacığı yalnızca bağlantı kimliğini yazdırır

client.on("connected", (e) => {
  console.log(`Connection ${e.connectionId} is connected.`);
});

İstemcinin bağlantısı kesildiğinde ve bağlantı kurtarılamadığında olay disconnected tetikleniyor. Bu kod parçacığı yalnızca iletiyi yazdırır.

client.on("disconnected", (e) => {
  console.log(`Connection disconnected: ${e.message}`);
});

İstemci stopped bağlantısı kesildiğinde ve istemci yeniden bağlanmaya çalışmayı durdurduğunda olay tetikleniyor. Bu genellikle çağrıldıktan veya devre dışı bırakıldıktan veya client.stop() yeniden bağlanmaya çalışmak için belirtilen sınıra ulaşıldıktan sonra autoReconnect gerçekleşir. İstemciyi yeniden başlatmak istiyorsanız durdurulan olayı çağırabilirsiniz client.start() .

// Registers an event handler for the "stopped" event
client.on("stopped", () => {
  console.log(`Client has stopped`);
});

Uygulama sunucusu kullanarak `Client Access URL` program aracılığıyla oluşturun

Üretimde istemciler genellikle bir uygulama sunucusundan getirir Client Access URL . Sunucu, Web PubSub kaynağınızda öğesini tutar connection string ve sunucu tarafı kitaplığından Client Access URLyardım ile öğesini oluşturur@azure/web-pubsub.

1. Uygulama sunucusu

Kod parçacığı, bir uygulama sunucusunun uç noktayı kullanıma seçip döndürdüğü /negotiatebir Client Access URL örnektir.

Ham bağlantı dizesi yalnızca tanıtım amacıyla bu makalede görünü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.

// 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ı

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

Not

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 sunucusundan veya gruplardan gelen iletileri kullanmak için geri çağırmalar ekleyebilir.

// Registers a listener for the "server-message". The callback is 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 is 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}`);
});

Not

Olay için group-message istemci yalnızca katıldığı gruplardan ileti alabilir.

Yeniden katılma hatasını işleme

İstemcinin bağlantısı kesildiğinde ve kurtarılamadığında, 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, istemcinin seçeneği etkindir autoRejoinGroup .

Ancak, 'nin sınırlamalarını autoRejoinGroupbilmeniz gerekir.

İstemci, sunucu tarafı kodu tarafından değil, yalnızca istemci kodu tarafından katılmış olan gruplara yeniden bağlanabilir.
"Gruba yeniden katıl" 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}`);
})

Yeniden Dene

Varsayılan olarak, , client.joinGroup(), client.leaveGroup()client.sendToGroup() gibi client.sendEvent()işlem üç yeniden denemeye sahiptir. 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ırabilmesi için önceki yeniden denemelerle aynı ackId işlemi geçirerek yeniden denemeye devam edebilirsiniz.

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

JavaScript Paketi

Bu istemci kitaplığını tarayıcıda kullanmak için bir paketleyici kullanmanız gerekir. Paket oluşturma hakkında ayrıntılı bilgi için 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.

Canlı İzleme

Web PubSub kaynağınız aracılığıyla canlı ileti trafiğini incelemek için Azure portalındaki Canlı İzleme aracını kullanın.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2024-12-12