Udostępnij za pośrednictwem

Biblioteka klienta usługi Azure Web PubSub dla języka JavaScript — wersja 1.1.3

  • Artykuł

usługi Azure Web PubSub to usługa zarządzana przez platformę Azure, która ułatwia deweloperom łatwe tworzenie aplikacji internetowych za pomocą funkcji w czasie rzeczywistym i wzorca publikowania-subskrybowania. Każdy scenariusz, który wymaga komunikatów publikowania i subskrybowania w czasie rzeczywistym między serwerem a klientami lub między klientami, może korzystać z usługi Azure Web PubSub. Tradycyjne funkcje w czasie rzeczywistym, które często wymagają sondowania z serwera lub przesyłania żądań HTTP, mogą również używać usługi Azure Web PubSub.

Tej biblioteki można używać po stronie serwera aplikacji do zarządzania połączeniami klienta protokołu WebSocket, jak pokazano na poniższym diagramie:

przepełnienie .

  • Wysyłanie komunikatów do centrów i grup.
  • Wysyłanie komunikatów do konkretnych użytkowników i połączeń.
  • Organizowanie użytkowników i połączeń w grupy.
  • Zamykanie połączeń
  • Udzielanie, odwoływanie i sprawdzanie uprawnień dla istniejącego połączenia

Szczegółowe informacje na temat terminów używanych w tym miejscu opisano w sekcji Kluczowe pojęcia.

Dokumentacja interfejsu API Code sourcePackage (NPM)Dokumentacja produktuPrzykłady

Wprowadzenie

Obecnie obsługiwane środowiska

Warunki wstępne

  • Subskrypcja platformy Azure .
  • Istniejące wystąpienie usługi Azure Web PubSub.

1. Instalowanie pakietu @azure/web-pubsub

npm install @azure/web-pubsub

2. Tworzenie i uwierzytelnianie elementu WebPubSubServiceClient

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

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

Możesz również uwierzytelnić WebPubSubServiceClient przy użyciu punktu końcowego i AzureKeyCredential:

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

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

Lub uwierzytelnianie WebPubSubServiceClient przy użyciu usługi Azure Active Directory

  1. Instalowanie zależności @azure/identity
npm install @azure/identity
  1. Zaktualizuj kod źródłowy, aby używał DefaultAzureCredential:
const { WebPubSubServiceClient, AzureKeyCredential } = require("@azure/web-pubsub");
const { DefaultAzureCredential } = require("@azure/identity");

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

Kluczowe pojęcia

Połączenie

Połączenie, nazywane również klientem lub połączeniem klienta, reprezentuje pojedyncze połączenie protokołu WebSocket połączone z usługą Web PubSub. Po pomyślnym nawiązaniu połączenia unikatowy identyfikator połączenia jest przypisywany do tego połączenia przez usługę Web PubSub.

Koncentrator

Koncentrator to logiczne pojęcie dla zestawu połączeń klientów. Zazwyczaj używasz jednego centrum do jednego celu, na przykład centrum czatów lub centrum powiadomień. Po utworzeniu połączenia klienta łączy się z koncentratorem i w okresie jego istnienia należy do tego centrum. Różne aplikacje mogą udostępniać jedną usługę Azure Web PubSub przy użyciu różnych nazw centrów.

Grupa

Grupa jest podzbiorem połączeń z koncentratorem. Możesz dodać połączenie klienta do grupy lub usunąć połączenie klienta z grupy w dowolnym momencie. Na przykład gdy klient dołącza do pokoju rozmów lub gdy klient opuszcza pokój rozmów, ten pokój rozmów może być uważany za grupę. Klient może dołączyć do wielu grup, a grupa może zawierać wielu klientów.

Użytkownik

Połączenia z usługą Web PubSub mogą należeć do jednego użytkownika. Użytkownik może mieć wiele połączeń, na przykład gdy jeden użytkownik jest połączony z wieloma urządzeniami lub wieloma kartami przeglądarki.

Komunikat

Po nawiązaniu połączenia klient może wysyłać komunikaty do aplikacji nadrzędnej lub odbierać komunikaty z aplikacji nadrzędnej za pośrednictwem połączenia protokołu WebSocket.

Przykłady

Uzyskiwanie tokenu dostępu dla klienta w celu uruchomienia połączenia protokołu WebSocket

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

Emisja komunikatów do wszystkich połączeń w centrum

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

Wysyłanie komunikatów do wszystkich połączeń w centrum przy użyciu składni filtru OData

Szczegółowe informacje o składni filter można znaleźć w składni filtru OData dla usługi Azure Web PubSub.

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

Wysyłanie komunikatów do wszystkich połączeń w grupie

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

Wysyłanie komunikatów do wszystkich połączeń użytkownika

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

Sprawdź, czy grupa ma jakiekolwiek połączenie

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

Uzyskiwanie dostępu do nieprzetworzonej odpowiedzi HTTP dla operacji

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

Rozwiązywanie problemów

Włączanie dzienników

Możesz ustawić następującą zmienną środowiskową, aby pobrać dzienniki debugowania podczas korzystania z tej biblioteki.

  • Pobieranie dzienników debugowania z biblioteki klienta usługi SignalR
export AZURE_LOG_LEVEL=verbose

Aby uzyskać bardziej szczegółowe instrukcje dotyczące włączania dzienników, zapoznaj się z dokumentami dotyczącymi pakietów @azure/rejestratora.

Śledzenie na żywo

Użyj funkcji śledzenia na żywo z portalu usługi Web PubSub, aby wyświetlić ruch na żywo.

Następne kroki

Zapoznaj się z przykładami katalogu, aby zapoznać się ze szczegółowymi przykładami dotyczącymi korzystania z tej biblioteki.

Przyczyniając się

Jeśli chcesz współtworzyć tę bibliotekę, przeczytaj przewodnik dotyczący współtworzenia , aby dowiedzieć się więcej na temat tworzenia i testowania kodu.