Udostępnij za pośrednictwem

Internetowy zestaw SDK po stronie klienta PubSub dla języka JavaScript

  • Artykuł

Uwaga

Szczegółowe informacje na temat terminów używanych w tym miejscu opisano w artykule dotyczącym kluczowych pojęć.

Zestaw SDK po stronie klienta ma na celu przyspieszenie przepływu pracy dewelopera; w szczególności,

  • upraszcza zarządzanie połączeniami klientów
  • upraszcza wysyłanie komunikatów między klientami
  • automatyczne ponawianie próby po niezamierzonych spadkach połączenia klienta
  • niezawodne dostarczanie komunikatów o numerze i w kolejności po odzyskaniu po spadku połączenia

Jak pokazano na diagramie, klienci ustanawiają połączenia protokołu WebSocket z zasobem Web PubSub.

Screenshot showing clients establishing WebSocket connection with a Web PubSub resource

Wprowadzenie

Wymagania wstępne

1. Zainstaluj @azure/web-pubsub-client pakiet

npm install @azure/web-pubsub-client

2. Połączenie za pomocą zasobu Web PubSub

Klient używa Client Access URL polecenia do nawiązywania połączenia i uwierzytelniania z usługą, 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 Client Access URL. W tym przewodniku szybkim możesz skopiować i wkleić go z wyświetlonej witryny Azure Portal. (W przypadku środowiska produkcyjnego klienci zazwyczaj są Client Access URL generowane na serwerze aplikacji. Zobacz szczegóły )

Screenshot showing how to get Client Access Url on Azure portal

Jak pokazano na 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

Klient może odbierać komunikaty tylko z grup, do których dołączył. Możesz dodać wywołanie zwrotne, aby określić logikę tego, co należy zrobić 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

Obsługa connectedzdarzeń i disconnected stopped

Usługa Azure Web PubSub uruchamia zdarzenia systemowe, takie jak connected, disconnected i stopped. Możesz zarejestrować programy obsługi zdarzeń, aby zdecydować, co program powinien zrobić po wyzwoleniu zdarzeń.

  1. Po pomyślnym połączeniu klienta z zasobem connected Web PubSub zdarzenie jest wyzwalane. Ten fragment kodu po prostu wyświetla identyfikator połączenia
client.on("connected", (e) => {
  console.log(`Connection ${e.connectionId} is connected.`);
});
  1. Gdy klient jest odłączony i nie może odzyskać połączenia, disconnected zdarzenie jest wyzwalane. Ten fragment kodu po prostu wyświetla komunikat.
client.on("disconnected", (e) => {
  console.log(`Connection disconnected: ${e.message}`);
});
  1. Zdarzenie stopped jest wyzwalane po rozłączeniu klienta, a klient przestaje 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ć client.start() wywołanie zdarzenia zatrzymane.
// Registers an event handler for the "stopped" event
client.on("stopped", () => {
  console.log(`Client has stopped`);
});

Programowe generowanie Client Access URL przy użyciu serwera aplikacji

W środowisku produkcyjnym klienci zwykle pobierają Client Access URL z serwera aplikacji. Serwer przechowuje connection string element do zasobu Web PubSub i generuje element Client Access URL z pomocą biblioteki @azure/web-pubsubpo stronie serwera .

1. Serwer aplikacji

Fragment kodu jest przykładem serwera aplikacji, który uwidacznia /negotiate punkt końcowy i zwraca wartość Client Access URL.

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

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

Uwaga

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 dodawać wywołania zwrotne w celu korzystania z komunikatów z serwera aplikacji lub grup.

// Registers a listener for the "server-message". The callback is 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 is 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}`);
});

Uwaga

W przypadku group-message zdarzenia klient może odbierać komunikaty tylko z grup, do których dołączył.

Niepowodzenie ponownego dołączania

Gdy klient jest odłączony i nie można go odzyskać, wszystkie konteksty grupy są czyszczone w zasobie Web PubSub. Oznacza to, że po ponownym nawiązaniu połączenia klient musi ponownie połączyć się z grupami. 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 zostały przyłą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, na przykład klient nie ma uprawnień do dołączania do grup. W takich przypadkach należy dodać wywołanie zwrotne w celu obsługi tego błędu.
// 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}`);
})

Ponów próbę

Domyślnie operacja taka jak client.joinGroup(), client.leaveGroup(), client.sendToGroup()client.sendEvent() ma trzy ponawiania prób. Konfigurację można skonfigurować za pomocą .messageRetryOptions Jeśli wszystkie ponowne próby nie powiodły się, zostanie zgłoszony błąd. Ponów próbę można zachować, przekazując te same ackId próby co poprzednie ponawianie 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});
}

Pakiet JavaScript

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

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.

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 narzędzia Live Trace z witryny Azure Portal, aby sprawdzić ruch komunikatów na żywo za pośrednictwem zasobu Web PubSub.