Udostępnij za pośrednictwem

Biblioteka klienta Web PubSub dla języka JavaScript

  • Artykuł

Azure Web PubSub to usługa w chmurze, która ułatwia deweloperom łatwe tworzenie funkcji w czasie rzeczywistym w aplikacjach internetowych z wzorcami publikowania i subskrybowania na dużą skalę.

Każdy scenariusz, który wymaga obsługi komunikatów w czasie rzeczywistym między serwerem a klientami lub wśród klientów po wzorcach publikowania-subskrybowania, może skorzystać z korzystania z usługi Web PubSub. Deweloperzy nie muszą już sondować serwera, wysyłając powtarzające się żądania HTTP w odstępach czasu, co jest marne i trudne do skalowania.

Jak pokazano na poniższym diagramie, klienci ustanawiają połączenia protokołu WebSocket z zasobem Web PubSub. Ta biblioteka klienta:

  • upraszcza zarządzanie połączeniami klienta
  • upraszcza wysyłanie komunikatów między klientami
  • automatycznie ponawia próbę po niezamierzonych spadkach połączenia klienta
  • niezawodne dostarczanie komunikatów w numerze i w kolejności po odzyskaniu po upuszczeniu połączenia

Przepełnienie

Szczegółowe informacje o terminach używanych w tym miejscu opisano w sekcji kluczowych pojęć .

Ta biblioteka jest hostowana w programie NPM.

Wprowadzenie

Obecnie obsługiwane środowiska

Wymagania wstępne

1. Instalowanie @azure/web-pubsub-client pakietu

npm install @azure/web-pubsub-client

2. Nawiązywanie połączenia z zasobem Web PubSub

Klient używa adresu URL dostępu klienta do nawiązywania połączenia i uwierzytelniania za pomocą usługi, która jest zgodna ze wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>wzorcem . Klient może mieć kilka sposobów uzyskania adresu URL dostępu klienta. W tym przewodniku Szybki start możesz skopiować i wkleić go z witryny Azure Portal pokazanej poniżej. (W przypadku środowiska produkcyjnego klienci zwykle uzyskują gengrated adres URL dostępu klienta na serwerze aplikacji. Zobacz szczegóły poniżej )

get_client_url

Jak pokazano na powyższym diagramie, klient ma uprawnienia do wysyłania komunikatów do określonej grupy o nazwie "group1".

// Imports the client libray
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. Dołącz do grup

Należy pamiętać, że klient może odbierać tylko komunikaty z grup, które zostały dołączone, i należy dodać wywołanie zwrotne, aby określić logikę podczas odbierania komunikatów.

// ...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. Wysyłanie komunikatów do grupy

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

Przykłady

Dodawanie wywołań zwrotnych dla połączonych, rozłączonych i zatrzymanych zdarzeń

  1. Gdy klient jest pomyślnie połączony z zasobem Web PubSub, connected zdarzenie jest wyzwalane.
client.on("connected", (e) => {
  console.log(`Connection ${e.connectionId} is connected.`);
});
  1. Gdy klient zostanie rozłączony i nie odzyska połączenia, disconnected zdarzenie zostanie wyzwolone.
client.on("disconnected", (e) => {
  console.log(`Connection disconnected: ${e.message}`);
});
  1. Zdarzenie stopped zostanie wyzwolone, gdy klient zostanie rozłączony , a klient przestanie próbować ponownie nawiązać połączenie. Zwykle dzieje się tak po wywołaniu client.stop() metody lub autoReconnect jest wyłączona lub osiągnięto określony limit próby ponownego nawiązania połączenia. Jeśli chcesz ponownie uruchomić klienta, możesz wywołać zdarzenie client.start() zatrzymane.
// Registers a listener for the "stopped" event
client.on("stopped", () => {
  console.log(`Client has stopped`);
});

Programowe generowanie adresu URL dostępu klienta za pomocą serwera negocjacyjnego

W środowisku produkcyjnym klienci zwykle pobierają adres URL dostępu klienta z serwera aplikacji. Serwer przechowuje parametry połączenia do zasobu Web PubSub i generuje adres URL dostępu klienta z pomocą biblioteki serwerów @azure/web-pubsub.

1. Serwer aplikacji

Poniższy fragment kodu jest przykładem serwera aplikacji uwidacznia ścieżkę /negotiate i zwraca adres URL dostępu klienta.

// 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. Po stronie klienta

Poniższy fragment kodu jest przykładem strony klienta.

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

Aby wyświetlić pełny kod tego przykładu, zapoznaj się z tematem samples-browser.

Klient korzysta z komunikatów z serwera aplikacji lub grup przyłączonych

Klient może dodać wywołania zwrotne w celu korzystania z komunikatów z serwera aplikacji lub grup. Należy pamiętać, że w przypadku group-message zdarzenia klient może odbierać tylko komunikaty grupy, które zostały dołączone.

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

Obsługa niepowodzenia ponownego dołączania

Po rozłączeniu klienta i niepomyślnym odzyskaniu wszystkie konteksty grupy zostaną wyczyszczone w zasobie Web PubSub. Oznacza to, że po ponownym połączeniu klienta musi ponownie dołączyć grupy. Domyślnie klient ma autoRejoinGroup włączoną opcję.

Należy jednak pamiętać o autoRejoinGroupograniczeniach.

  • Klient może ponownie dołączyć tylko grupy, które pierwotnie zostały dołączone przez kod klienta , a nie przez kod po stronie serwera.
  • Operacje ponownego dołączania grupy mogą zakończyć się niepowodzeniem z różnych powodów, np. klient nie ma uprawnień do dołączania do grup. W takich przypadkach należy dodać wywołanie zwrotne, aby obsłużyć ten błąd.
// 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}`);
})

Operacja i ponów próbę

Domyślnie operacja taka jak client.joinGroup(), client.leaveGroup(), client.sendToGroup()client.sendEvent() ma trzy ponowne próby. Konfigurację można skonfigurować za pomocą programu messageRetryOptions. Jeśli wszystkie ponawianie prób nie powiodło się, zostanie zgłoszony błąd. Ponów próbę można zachować, przekazując tę samą ackId liczbę ponownych prób, aby usługa Web PubSub mogła deduplikować operację.

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

Określ podprotokol

Możesz zmienić podprotocol, aby był używany przez klienta. Domyślnie klient używa polecenia json.reliable.webpubsub.azure.v1. Możesz użyć polecenia json.reliable.webpubsub.azure.v1 lub json.webpubsub.azure.v1.

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

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

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. Każda z nich WebPubSubClient tworzy własne wyłączne połączenie.

Odzyskiwania

Jeśli klient korzystający z niezawodnych protokołów rozłącza się, nowy zestaw WebSocket próbuje ustanowić przy użyciu identyfikatora połączenia utraconego połączenia. Jeśli nowe połączenie protokołu WebSocket zostanie pomyślnie połączone, połączenie zostanie odzyskane. Przez cały czas rozłączenia klienta usługa zachowuje kontekst klienta, a także wszystkie komunikaty subskrybowane przez klienta, a po odzyskaniu klienta usługa wyśle te komunikaty do klienta. Jeśli usługa zwróci kod 1008 błędu protokołu WebSocket lub próba odzyskiwania trwa dłużej niż 30 sekund, odzyskiwanie zakończy się niepowodzeniem.

Ponowne łączenie

Ponowne nawiązywanie połączenia występuje, gdy połączenie klienta spadnie i nie można odzyskać. Ponowne nawiązywanie połączenia powoduje uruchomienie nowego połączenia, a nowe połączenie ma nowy identyfikator połączenia. W przeciwieństwie do odzyskiwania usługa traktuje ponownie połączonego klienta jako nowe połączenie klienta. Połączenie klienta musi ponownie dołączyć grupy. Domyślnie biblioteka klienta ponownie dołącza grupy po ponownym połączeniu.

Koncentrator

Koncentrator jest logicznym pojęciem dla zestawu połączeń klienckich. Zwykle 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ę Web PubSub przy użyciu różnych nazw centrów.

Group (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

Connections do usługi Web PubSub może 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.

Okres istnienia klienta

Każdy z klientów Web PubSub jest bezpieczny do buforowania i używany jako jedenton przez cały okres istnienia aplikacji. Zarejestrowane wywołania zwrotne zdarzeń współużytkują ten sam okres istnienia z klientem. Oznacza to, że w dowolnym momencie można dodawać lub usuwać wywołania zwrotne, a stan rejestracji nie zmieni się po ponownym połączeniu lub zatrzymaniu klienta.

Pakiet JavaScript

Aby użyć tej biblioteki klienta w przeglądarce, najpierw należy użyć pakietu. Aby uzyskać szczegółowe informacje na temat tego, jak to zrobić, zapoznaj się z naszą dokumentacją dotyczącą tworzenia pakietów.

Rozwiązywanie problemów

  • Włączanie dzienników

    W przypadku korzystania z tej biblioteki można ustawić następującą zmienną środowiskową, aby pobrać dzienniki debugowania.

export AZURE_LOG_LEVEL=verbose

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

Dodatkowe zasoby

Współtworzenie

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