Aracılığıyla paylaş

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

Azure Web PubSub hizmeti, geliştiricilerin gerçek zamanlı özellikler ve yayımlama-abone olma 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 sunucusu tarafınızda bu kitaplığı kullanabilirsiniz:

taşması .

  • 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
  • Mevcut bağlantı için izin verme, iptal etme ve denetleme

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

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

Başlarken

Şu anda desteklenen ortamlar

  • Node.js LTS sürümleri

Önkoşullar

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

npm install @azure/web-pubsub

2. WebPubSubServiceClient oluşturma ve kimlik doğrulaması

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

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

Ayrıca bir uç nokta ve WebPubSubServiceClientkullanarak AzureKeyCredential kimliğini doğrulayabilirsiniz:

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

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

WebPubSubServiceClient kullanarak kimliğini doğrulama

  1. @azure/identity bağımlılığını yükleme
npm install @azure/identity
  1. kaynak kodunu DefaultAzureCredentialkullanacak şekilde güncelleştirin:
import { DefaultAzureCredential } from "@azure/identity";
import { WebPubSubServiceClient } from "@azure/web-pubsub";

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

Temel 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ğlandığında, Web PubSub hizmeti tarafından bu bağlantıya benzersiz bir bağlantı kimliği atanır.

Göbek

Hub, bir dizi istemci bağlantısı için mantıksal bir kavramdır. Genellikle bir hub'ı, örneğin 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 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 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.

Örnekler

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

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

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<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"] });

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

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

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<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

filter söz dizimi hakkındaki ayrıntılar için bkz. Azure Web PubSub içinOData filtre söz dizimi.

import { WebPubSubServiceClient, odata } from "@azure/web-pubsub";
import { DefaultAzureCredential } from "@azure/identity";

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<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

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

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<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);

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

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

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<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

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

const serviceClient = new WebPubSubServiceClient(
  "<Endpoint>",
  new DefaultAzureCredential(),
  "<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

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

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

function onResponse(rawResponse) {
  console.log(rawResponse);
}

await serviceClient.sendToAll({ message: "Hello world!" }, { onResponse });

Sorun giderme

Günlükleri etkinleştirme

Günlüğe kaydetmeyi 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 AZURE_LOG_LEVEL ortam değişkenini infoolarak ayarlayın.

export AZURE_LOG_LEVEL=verbose

Alternatif olarak, setLogLevel@azure/logger çağrılarak günlükler çalışma zamanında 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 hizmet portalından Canlı İzleme kullanın.

Sonraki adımlar

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

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.

  • Last updated on