Aracılığıyla paylaş

JavaScript için Azure Web PubSub hizmeti istemci kitaplığı - sürüm 1.1.1

  • Makale

Azure Web PubSub hizmeti , geliştiricilerin gerçek zamanlı özellikler ve yayımla-abone ol düzeniyle kolayca web uygulamaları oluşturmalarına yardımcı olan, Azure tarafından yönetilen bir hizmettir. Sunucu ve istemciler arasında veya istemciler arasında gerçek zamanlı yayımlama-abone olma mesajlaşması gerektiren tüm senaryolar Azure Web PubSub hizmetini kullanabilir. Genellikle sunucudan yoklama veya HTTP istekleri gönderme gerektiren geleneksel gerçek zamanlı özellikler, Azure Web PubSub hizmetini de kullanabilir.

Aşağıdaki diyagramda gösterildiği gibi WebSocket istemci bağlantılarını yönetmek için uygulama sunucu tarafınızda bu kitaplığı kullanabilirsiniz:

taşma.

  • Hub'lara ve gruplara ileti gönderme.
  • Belirli kullanıcılara ve bağlantılara ileti gönderme.
  • Kullanıcıları ve bağlantıları gruplar halinde düzenleyin.
  • Bağlantıları kapatma
  • Var olan bir bağlantı için izin verme, iptal etme ve izinleri denetleme

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

Kaynak kodu | Paket (NPM) | API başvuru belgeleri | Ürün belgeleri | Örnekleri

Başlarken

Şu anda desteklenen ortamlar

Önkoşullar

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

npm install @azure/web-pubsub

2. WebPubSubServiceClient oluşturma ve kimliğini doğrulama

const { WebPubSubServiceClient } = require("@azure/web-pubsub");

const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");

Ayrıca bir uç nokta ve AzureKeyCredentialkullanarak kimliğini doğrulayabilirsinizWebPubSubServiceClient:

const { WebPubSubServiceClient, AzureKeyCredential } = require("@azure/web-pubsub");

const key = new AzureKeyCredential("<Key>");
const serviceClient = new WebPubSubServiceClient("<Endpoint>", key, "<hubName>");

Veya Azure Active Directory kullanarak kimlik doğrulaması WebPubSubServiceClient yapın

  1. @azure/identity Bağımlılığı yükleme
npm install @azure/identity
  1. kaynak kodunu kullanacak DefaultAzureCredentialşekilde güncelleştirin:
const { WebPubSubServiceClient, AzureKeyCredential } = require("@azure/web-pubsub");
const { DefaultAzureCredential } = require("@azure/identity");

const key = new DefaultAzureCredential();
const serviceClient = new WebPubSubServiceClient("<Endpoint>", key, "<hubName>");

Önemli kavramlar

Bağlantı

İstemci veya istemci bağlantısı olarak da bilinen bağlantı, Web PubSub hizmetine bağlı tek bir WebSocket bağlantısını temsil eder. Başarıyla bağlanıldığında, Web PubSub hizmeti tarafından bu bağlantıya benzersiz bir bağlantı kimliği atanır.

Hub

Hub, bir dizi istemci bağlantısı için mantıksal bir kavramdır. Genellikle sohbet hub'ı veya bildirim hub'ı gibi tek bir amaç için tek bir hub kullanırsınız. 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 Azure Web PubSub hizmetini 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 cihaz veya birden çok tarayıcı sekmesi arasında 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.

Örnekler

WebSocket bağlantısını başlatmak için istemcinin erişim belirtecini alma

const { WebPubSubServiceClient } = require("@azure/web-pubsub");

const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");

// Get the access token for the WebSocket client connection to use
let token = await serviceClient.getClientAccessToken();

// Or get the access token and assign the client a userId
token = await serviceClient.getClientAccessToken({ userId: "user1" });

// Or get the access token that the client will join group GroupA when it connects using the access token
token = await serviceClient.getClientAccessToken({ userId: "user1", groups: [ "GroupA" ] });

// return the token to the WebSocket client

Hub'daki tüm bağlantılara ileti yayınlama

const { WebPubSubServiceClient } = require("@azure/web-pubsub");

const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");

// Send a JSON message
await serviceClient.sendToAll({ message: "Hello world!" });

// Send a plain text message
await serviceClient.sendToAll("Hi there!", { contentType: "text/plain" });

// Send a binary message
const payload = new Uint8Array(10);
await serviceClient.sendToAll(payload.buffer);

OData filtre söz dizimi ile bir hub'daki tüm bağlantılara ileti gönderme

Söz dizimi hakkındaki filter ayrıntılar için bkz. Azure Web PubSub için OData filtresi söz dizimi.

const { WebPubSubServiceClient, odata } = require("@azure/web-pubsub");

const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");

// Send a JSON message to anonymous connections
await serviceClient.sendToAll(
  { message: "Hello world!" },
  { filter: "userId eq null" }
  );

// Send a text message to connections in groupA but not in groupB
const groupA = 'groupA';
const groupB = 'groupB';
await serviceClient.sendToAll(
  "Hello world!",
  { 
    contentType: "text/plain",
    // use plain text "'groupA' in groups and not('groupB' in groups)"
    // or use the odata helper method
    filter: odata`${groupA} in groups and not(${groupB} in groups)` 
  });

Gruptaki tüm bağlantılara ileti gönderme

const { WebPubSubServiceClient } = require("@azure/web-pubsub");

const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");

const groupClient = serviceClient.group("<groupName>");

// Add user to the group
await groupClient.addUser("user1");

// Send a JSON message
await groupClient.sendToAll({ message: "Hello world!" });

// Send a plain text message
await groupClient.sendToAll("Hi there!", { contentType: "text/plain" });

// Send a binary message
const payload = new Uint8Array(10);
await groupClient.sendToAll(payload.buffer);

Kullanıcının tüm bağlantılarına ileti gönderme

const { WebPubSubServiceClient } = require("@azure/web-pubsub");

const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");

// Send a JSON message
await serviceClient.sendToUser("user1", { message: "Hello world!" });

// Send a plain text message
await serviceClient.sendToUser("user1", "Hi there!", { contentType: "text/plain" });

// Send a binary message
const payload = new Uint8Array(10);
await serviceClient.sendToUser("user1", payload.buffer);

Grubun herhangi bir bağlantısı olup olmadığını denetleyin

const { WebPubSubServiceClient } = require("@azure/web-pubsub");
const WebSocket = require("ws");

const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");

const groupClient = serviceClient.group("<groupName>");

// close all the connections in the group
await groupClient.closeAllConnections({ reason: "<closeReason>" });

// check if the group has any connections
const hasConnections = await serviceClient.groupExists("<groupName>");

İşlem için ham HTTP yanıtına erişme

const { WebPubSubServiceClient } = require("@azure/web-pubsub");

function onResponse(rawResponse) {
  console.log(rawResponse);
}
const serviceClient = new WebPubSubServiceClient("<ConnectionString>", "<hubName>");
await serviceClient.sendToAll({ message: "Hello world!" }, { onResponse });

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.

  • SignalR istemci kitaplığından hata ayıklama günlüklerini alma
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

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

Sonraki adımlar

Bu kitaplığın nasıl kullanılacağına ilişkin ayrıntılı örnekler için lütfen samples dizinine göz atın.

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.