Udostępnij za pośrednictwem

Azure Web PubSub CloudEvents handlers for Express

  • Artykuł

Usługa 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 czasu rzeczywistego, które często wymagają sondowania z serwera lub przesyłania żądań HTTP, mogą również używać usługi Azure Web PubSub.

Po nawiązaniu połączenia protokołu WebSocket usługa Web PubSub przekształca cykl życia połączenia i komunikaty na zdarzenia w formacie CloudEvents. Ta biblioteka udostępnia ekspresowe oprogramowanie pośredniczące do obsługi zdarzeń reprezentujących cykl życia i komunikaty połączenia Protokołu WebSocket, jak pokazano na poniższym diagramie:

cloudevents

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

Kod | źródłowyPakiet (NPM) | Dokumentacja referencyjna interfejsu | APIDokumentacja | produktuPróbki

Wprowadzenie

Obecnie obsługiwane środowiska

Wymagania wstępne

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

npm install @azure/web-pubsub-express

2. Utwórz WebPubSubEventHandler

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat");

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(`Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`)
);

Kluczowe pojęcia

Połączenie

Połączenie, znane również jako klient lub połączenie 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 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ę Azure 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

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 na wielu urządzeniach lub na wielu kartach przeglądarki.

Zdarzenia klienta

Zdarzenia są tworzone podczas cyklu życia połączenia klienta. Na przykład proste połączenie klienta protokołu WebSocket tworzy connect zdarzenie, gdy próbuje nawiązać połączenie z usługą, connected zdarzenie po pomyślnym nawiązaniu połączenia z usługą, message zdarzenie podczas wysyłania komunikatów do usługi i disconnected zdarzenie, gdy rozłącza się z usługą.

Program obsługi zdarzeń

Procedura obsługi zdarzeń zawiera logikę obsługi zdarzeń klienta. Program obsługi zdarzeń musi być wcześniej zarejestrowany i skonfigurowany w usłudze za pośrednictwem portalu lub interfejsu wiersza polecenia platformy Azure. Miejsce do hostowania logiki obsługi zdarzeń jest zwykle uznawane za po stronie serwera.

Przykłady

Obsługa connect żądania i przypisywanie <userId>

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat", {
  handleConnect: (req, res) => {
    // auth the connection and set the userId of the connection
    res.success({
      userId: "<userId>"
    });
  },
  allowedEndpoints: ["https://<yourAllowedService>.webpubsub.azure.com"]
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(`Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`)
);

Zezwalaj tylko na określone punkty końcowe

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat", {
  allowedEndpoints: [
    "https://<yourAllowedService1>.webpubsub.azure.com",
    "https://<yourAllowedService2>.webpubsub.azure.com"
  ]
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(`Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`)
);

Ustawianie niestandardowej ścieżki procedury obsługi zdarzeń

const express = require("express");

const { WebPubSubEventHandler } = require("@azure/web-pubsub-express");
const handler = new WebPubSubEventHandler("chat", {
  path: "customPath1"
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  // Azure WebPubSub Upstream ready at http://localhost:3000/customPath1
  console.log(`Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`)
);

Ustawianie i odczytywanie stanu połączenia

const express = require("express");

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

const handler = new WebPubSubEventHandler("chat", {
  handleConnect(req, res) {
    // You can set the state for the connection, it lasts throughout the lifetime of the connection
    res.setState("calledTime", 1);
    res.success();
  },
  handleUserEvent(req, res) {
    var calledTime = req.context.states.calledTime++;
    console.log(calledTime);
    // You can also set the state here
    res.setState("calledTime", calledTime);
    res.success();
  }
});

const app = express();

app.use(handler.getMiddleware());

app.listen(3000, () =>
  console.log(`Azure WebPubSub Upstream ready at http://localhost:3000${handler.path}`)
);

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 Live Trace z portalu usługi Web PubSub, aby wyświetlić ruch na żywo.

Następne kroki

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

Współtworzenie

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