JavaScript için Web PubSub istemci kitaplığı

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 ve istemciler arasında veya yayımlama-abone olma 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 belirli aralıklarla yinelenen HTTP istekleri göndererek sunucuyu yoklaması gerekmez ve bu da boşa harcanıp ö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 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

taşma

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

Bu kitaplık NPMüzerinde barındırılır.

Başlarken

Şu anda desteklenen ortamlar

Node.js LTS sürümleri

Önkoşullar

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

npm install @azure/web-pubsub-client

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

İstemci, wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>desenini izleyen hizmete bağlanmak ve hizmetle kimlik doğrulaması yapmak için bir İstemci Erişim URL'si kullanır. İstemcinin İstemci Erişimi 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 Client Access URL'si oluşturulur. Aşağıdaki detaylara bakınız :)

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.

import { WebPubSubClient } from "@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();

3. Gruplara katılma

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

import { WebPubSubClient } from "@azure/web-pubsub-client";

const client = new WebPubSubClient("<client-access-url>");

// 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}`);
});

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

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

4. Gruba ileti gönderme

import { WebPubSubClient } from "@azure/web-pubsub-client";

const client = new WebPubSubClient("<client-access-url>");
await client.start();

const groupName = "group1";
await client.joinGroup(groupName);

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

5. Yukarı akış olaylarını çağırma (önizleme)

import { WebPubSubClient } from "@azure/web-pubsub-client";

const client = new WebPubSubClient("<client-access-url>");
await client.start();

const result = await client.invokeEvent("processOrder", { orderId: 1 }, "json");
console.log(`Invocation result: ${JSON.stringify(result.data)}`);

invokeEvent servise bir invoke istek gönderir, ilişkili invokeResponseprogramı bekler ve yükü geri getirir. Çağrıyı sonlandırarak 'yi geçebilirsiniz { abortSignal }. Hizmet başlatan çağrılar henüz desteklenmemektedir.

6. Mesajları bir gruba akış (önizleme)

Büyük veya sürekli bir yükü bir gruba sıralı bir parça akışı olarak gönderebilir ve gelen her akışı alıcı tarafta bir birim olarak tüketebilirsiniz.

import { WebPubSubClient } from "@azure/web-pubsub-client";

const client = new WebPubSubClient("<client-access-url>");

// Receiving side: subscribe once, then consume each inbound stream with for-await.
client.onGroupStream(
  async (stream) => {
    const parts: string[] = [];
    try {
      for await (const message of stream) {
        parts.push(message.data as string);
      }
      console.log(`Stream ${stream.streamId} completed: ${parts.join("")}`);
    } catch (err) {
      console.log(
        `Stream ${stream.streamId} failed: ${
          (
            err as {
              name?: string;
            }
          ).name
        }`,
      );
    }
  },
  { handleFromStart: true },
);

await client.start();
const groupName = "group1";
await client.joinGroup(groupName);

// Sending side: write a logical stream in ordered fragments, then end it.
const stream = await client.openGroupStream(groupName);
await stream.write("hello ", "text");
await stream.write("world", "text");
await stream.end();

onGroupStream dinleyiciyi kayddan çıkarmak için abonelik close() iade eder. Her geri çağrı, parçaları üzerinde asenkron olarak tekrarlanabilir bir GroupStream kart alır. openGroupStream GroupStreamWriter Bir parçaya write döndürürsünüz, end akışı başarıyla veya abort hatayla döndürür.

Örnekler

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

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.`);
});

İstemcinin bağlantısı kesildiğinde ve bağlantı kurtarılamıyorsa, disconnected olayı tetikler.

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

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

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

programlı olarak İstemci Erişimi URL'si oluşturmak için anlaşma sunucusu kullanma

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

1. Uygulama sunucusu

Aşağıdaki kod parçacığı, uygulama sunucusunun bir /negotiate yolunu kullanıma sunma ve İstemci Erişimi URL'sini döndürme örneğidir.

import express from "express";
import { WebPubSubServiceClient } from "@azure/web-pubsub";

const app = express();
const port = 8080;

// Imports the server library, which is different from the client library
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: unknown,
    res: {
      json: (body: { url: string }) => void;
    },
  ) => {
    const 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.

import { WebPubSubClient } from "@azure/web-pubsub-client";

const client = new WebPubSubClient({
  getClientAccessUrl: async () => {
    const negotiate = await fetch("/negotiate");
    const { url } = (await negotiate.json()) as {
      url: string;
    };
    return url;
  },
});

await client.start();

Bu örneğin tam kodunu görmek için lütfen samples-browserkonusuna 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. group-message olay için istemcinin yalnızca katıldığı grup iletilerini olabileceğ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

bir istemcinin 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, istemcide autoRejoinGroup seçeneği etkindir.

Ancak, autoRejoinGroupsınırlamalarını bilmeniz gerekir.

İstemci yalnızca başlangıçta istemci koduyla birleştirilen gruplara yeniden bağlanabilir sunucu tarafı kodu tarafından.
"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.

import { WebPubSubClient } from "@azure/web-pubsub-client";

// 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.joinGroup(), client.leaveGroup(), client.sendToGroup(), client.sendEvent() gibi işlem üç yeniden denemeye sahiptir. messageRetryOptionsaracılığıyla yapılandırabilirsiniz. Tüm yeniden denemeler başarısız olursa bir hata oluşturulur. Web PubSub hizmetinin işlemi yinelenenleri kaldırabilmesi için önceki yeniden denemelerle aynı ackId geçirerek yeniden denemeye devam edebilirsiniz.

import { WebPubSubClient, SendMessageError } from "@azure/web-pubsub-client";

const client = new WebPubSubClient("<client-access-url>");
await client.start();

const groupName = "group1";

try {
  await client.joinGroup(groupName);
} catch (err) {
  let id: number | undefined;
  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 json.reliable.webpubsub.azure.v1kullanır. json.reliable.webpubsub.azure.v1 veya json.webpubsub.azure.v1kullanmayı seçebilirsiniz.

import { WebPubSubClient, WebPubSubJsonProtocol } from "@azure/web-pubsub-client";

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

import { WebPubSubClient, WebPubSubJsonReliableProtocol } from "@azure/web-pubsub-client";

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

Temel 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ğlandığında, Web PubSub tarafından bu bağlantıya benzersiz bir bağlantı kimliği atanır. Her WebPubSubClient kendi özel bağlantısını 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, hizmet bu iletileri istemciye gönderir. Hizmet WebSocket hata kodunu 1008 döndürürse veya kurtarma girişimi 30 saniyeden uzun sürerse kurtarma başarısız olur.

Yeniden bağlanma

yeniden bağlantı, istemci bağlantısı kesildiğinde ve kurtarılamadığında gerçekleşir. Yeniden bağlantı 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 istemciye yeni bir istemci bağlantısı olarak davranır. İstemci bağlantısının gruplara yeniden katılması gerekir. Varsayılan olarak, istemci kitaplığı yeniden bağlandıktan sonra gruplara yeniden katılır.

Göbek

Hub, bir dizi istemci bağlantısı için mantıksal bir kavramdır. Genellikle bir hub'ı sohbet hub'ı veya bildirim hub'ı gibi tek bir amaç için kullanırsınız. İstemci 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 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.

İstemci Ömrü

Web PubSub istemcilerinin her birinin önbelleğe alınması güvenlidir ve uygulamanın ömrü boyunca tekil olarak kullanılır. Kayıtlı olay geri çağırmaları istemciyle aynı ömrü paylaşır. Bu, istediğiniz zaman geri çağırma ekleyebileceğiniz veya kaldırabileceğiniz ve yeniden bağlantı veya istemci durdurulduktan sonra kayıt durumunun değişmeyeceği anlamına gelir.

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

Loglamayı etkinleştirmek, hatalarla ilgili yararlı bilgilerin ortaya çıkmasına yardımcı olabilir. HTTP isteklerinin ve yanıtlarının günlüğünü görmek için ortam değişkenini AZURE_LOG_LEVEL olarak infoayarlayın.

export AZURE_LOG_LEVEL=verbose

Alternatif olarak, çalışma zamanında setLogLevel@azure/logger çağrılarak günlük tutma etkinleştirilebilir.

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

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

Canlı İzleme

Canlı trafiği görüntülemek için Web PubSub portalından Canlı İzleme aracını kullanın.

Ek kaynaklar

İstemci izni hakkında daha fazla bilgi edinin, bkz. izinleri
Sunucu SDK'sı - JavaScript belgeleri
Ürün belgeleri
Örnekleri

Katkıda

Bu kitaplığa katkıda bulunmak istiyorsanız kodu oluşturma ve test etme hakkında daha fazla bilgi edinmek için lütfen katkıda bulunma kılavuzu okuyun.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-06-29

JavaScript için Web PubSub istemci kitaplığı

Başlarken

Şu anda desteklenen ortamlar

Önkoşullar

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

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

3. Gruplara katılma

4. Gruba ileti gönderme

5. Yukarı akış olaylarını çağırma (önizleme)

6. Mesajları bir gruba akış (önizleme)

Örnekler

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

programlı olarak İstemci Erişimi URL'si oluşturmak için anlaşma sunucusu kullanma

1. Uygulama sunucusu

2. İstemci tarafı

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

Yeniden katılma hatasını işleme

İşlem ve yeniden deneme

Altprotocol belirtme

Temel kavramlar

Bağlantı

Kurtarma

Yeniden bağlanma

Göbek

Grup

Kullanıcı

İstemci Ömrü

JavaScript Paketi

Sorun giderme

Günlükleri etkinleştirme

Canlı İzleme

Ek kaynaklar

Katkıda

Geri Bildirim

Ek kaynaklar

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