Wewnętrzne usługi Azure Web PubSub

Artykuł
08/21/2024

Usługa Azure Web PubSub Service umożliwia łatwe publikowanie/subskrybowanie komunikatów przy użyciu prostych połączeń protokołu WebSocket .

Klienci mogą być pisani w dowolnym języku, który obsługuje protokół Websocket.
Komunikaty tekstowe i binarne są obsługiwane w ramach jednego połączenia.
Prosty protokół umożliwia klientom publikowanie masaży bezpośrednio do siebie.
Usługa zarządza połączeniami protokołu WebSocket.

Terminy

Usługa: Usługa Azure Web PubSub.

Połączenie: połączenie, nazywane również klientem lub połączeniem klienta, jest to relacja logiczna między klientem a usługą Web PubSub. Za pośrednictwem połączenia klient i usługa angażują się w serię interakcji stanowych. Połączenia korzystające z różnych protokołów mogą zachowywać się inaczej, na przykład niektóre połączenia są ograniczone do czasu trwania połączenia sieciowego, podczas gdy inne mogą rozciągać się między wieloma kolejnymi połączeniami sieciowymi między klientem a usługą.
Koncentrator: Koncentrator jest logicznym pojęciem dla zestawu połączeń klienckich. Zazwyczaj używasz jednego centrum w jednym scenariuszu, na przykład centrum czatów lub centrum powiadomień . Gdy połączenie klienta nawiązuje połączenie, łączy się z koncentratorem i w okresie jego istnienia należy do tego centrum. Gdy połączenie klienta połączy się z koncentratorem, centrum istnieje. Różne aplikacje mogą udostępniać jedną usługę Azure Web PubSub przy użyciu różnych nazw centrów. Chociaż nie ma ścisłego limitu liczby centrów, centrum zużywa więcej obciążenia usługi w porównaniu z grupą. Zaleca się posiadanie wstępnie określonego zestawu koncentratorów, a nie dynamicznego generowania ich.
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. Grupa jest jak "sesja", sesja grupy jest tworzona, gdy ktoś dołączy do grupy, a sesja nie zostanie utworzona, gdy nikt nie znajduje się w grupie. Komunikaty wysyłane do grupy są dostarczane do wszystkich klientów połączonych z grupą.
Użytkownik: połączenia z internetowymi usługami 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. Komunikaty mogą być w formacie zwykłego tekstu, binarnego lub JSON i mają maksymalny rozmiar 1 MB.
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 połączeniu z usługą, message zdarzenie wysyłane do usługi i disconnected zdarzenie, gdy rozłącza się z usługą. Szczegółowe informacje o zdarzeniach klienta przedstawiono w sekcji Protokół klienta.
Procedura obsługi zdarzeń: program obsługi zdarzeń zawiera logikę do obsługi zdarzeń klienta. Zarejestruj i skonfiguruj programy obsługi zdarzeń w usłudze za pośrednictwem witryny Portal lub interfejsu wiersza polecenia platformy Azure wcześniej. Szczegóły opisano w sekcji Procedura obsługi zdarzeń.
Odbiornik zdarzeń (wersja zapoznawcza): odbiornik zdarzeń po prostu nasłuchuje zdarzeń klienta, ale nie może zakłócać okresu istnienia klientów przez ich odpowiedź. Szczegóły opisano w sekcji Odbiornik zdarzeń.
Serwer: serwer może obsługiwać zdarzenia klienta, zarządzać połączeniami klientów lub publikować komunikaty w grupach. Zarówno program obsługi zdarzeń, jak i odbiornik zdarzeń są uważane za po stronie serwera. Szczegółowe informacje o serwerze opisano w sekcji Protokół serwera.

Przepływ pracy

Diagram przedstawiający przepływ pracy usługi Web PubSub.

Przepływ pracy, jak pokazano na powyższym wykresie:

Klient łączy się z punktem końcowym usługi /client przy użyciu transportu protokołu WebSocket. Usługa przekazuje każdą ramkę protokołu WebSocket do skonfigurowanego nadrzędnego (serwera). Połączenie protokołu WebSocket może łączyć się z dowolnym niestandardowym podprotocolem dla serwera do obsługi lub może nawiązać połączenie z podprotocol json.webpubsub.azure.v1obsługiwanym przez usługę, co umożliwia klientom bezpośrednie wykonywanie pub/sub. Szczegóły opisano w protokole klienta.
W przypadku różnych zdarzeń klienta usługa wywołuje serwer przy użyciu protokołu CloudEvents. CloudEvents to ustandaryzowana i niezależna od protokołu definicja struktury i metadanych zdarzeń hostowanych przez Cloud Native Computing Foundation (CNCF). Szczegółowa implementacja protokołu CloudEvents opiera się na roli serwera opisanej w protokole serwera.
Serwer Web PubSub może wywołać usługę przy użyciu interfejsu API REST do wysyłania komunikatów do klientów lub zarządzania połączonymi klientami. Szczegóły opisano w protokole serwera

Protokół klienta

Połączenie klienta łączy się z /client punktem końcowym usługi przy użyciu protokołu WebSocket. Protokół WebSocket zapewnia kanały komunikacji pełnodupleksowej za pośrednictwem jednego połączenia TCP i został ustandaryzowany przez IETF jako RFC 6455 w 2011 roku. Większość języków ma natywną obsługę uruchamiania połączeń protokołu WebSocket.

Nasza usługa obsługuje dwa rodzaje klientów:

Jeden jest nazywany prostym klientem protokołu WebSocket
Drugi jest nazywany klientem PubSub WebSocket

Prosty klient protokołu WebSocket

Prosty klient protokołu WebSocket, jak wskazuje nazewnictwo, jest prostym połączeniem protokołu WebSocket. Może również mieć niestandardową podprotokolę.

Na przykład w języku JS można utworzyć prostego klienta protokołu WebSocket przy użyciu następującego kodu.

// simple WebSocket client1
var client1 = new WebSocket("wss://test.webpubsub.azure.com/client/hubs/hub1");

// simple WebSocket client2 with some custom subprotocol
var client2 = new WebSocket(
  "wss://test.webpubsub.azure.com/client/hubs/hub1",
  "custom.subprotocol"
);

Prosty klient protokołu WebSocket jest zgodny z architekturą klient-serwer<>, jak pokazano na poniższym diagramie sekwencji: Diagram przedstawiający sekwencję połączenia klienta.

Gdy klient uruchamia uzgadnianie protokołu WebSocket, usługa próbuje wywołać connect procedurę obsługi zdarzeń dla uzgadniania protokołu WebSocket. Deweloperzy mogą używać tej procedury obsługi do obsługi uzgadniania protokołu WebSocket, określania podprotocol do użycia, uwierzytelniania klienta i dołączania klienta do grup.
Po pomyślnym nawiązaniu połączenia klient wywołuje program obsługi zdarzeń connected . Działa jako powiadomienie i nie blokuje wysyłania komunikatów przez klienta. Deweloperzy mogą używać tej procedury obsługi do przechowywania danych i mogą odpowiadać za pomocą komunikatów do klienta. Usługa wypycha connected również zdarzenie do wszystkich odbiorników zdarzeń, jeśli istnieje.
Gdy klient wysyła komunikaty, usługa wyzwala message zdarzenie do programu obsługi zdarzeń. To zdarzenie zawiera komunikaty wysyłane w ramce protokołu WebSocket. Kod musi wysyłać komunikaty wewnątrz tej procedury obsługi zdarzeń. Jeśli program obsługi zdarzeń zwraca kod odpowiedzi nienagannej, usługa przerywa połączenie klienta. Usługa wypycha message również zdarzenie do wszystkich zainteresowanych odbiorników zdarzeń, jeśli istnieje. Jeśli usługa nie może znaleźć żadnych zarejestrowanych serwerów do odbierania komunikatów, usługa również przerywa połączenie klienta.
Po rozłączeniu klienta usługa próbuje wyzwolić disconnected zdarzenie do programu obsługi zdarzeń po wykryciu rozłączenia. Usługa wypycha disconnected również zdarzenie do wszystkich odbiorników zdarzeń, jeśli istnieje.

Scenariusze

Te połączenia mogą być używane w typowej architekturze klient-serwer, w której klient wysyła komunikaty do serwera, a serwer obsługuje komunikaty przychodzące przy użyciu programów obsługi zdarzeń. Może być również używany, gdy klienci stosują istniejące podprotokoli w swojej logice aplikacji.

Klient protokołu WebSocket PubSub

Usługa obsługuje również określoną podprotokolę o nazwie json.webpubsub.azure.v1, która umożliwia klientom bezpośrednie publikowanie/subskrybowanie zamiast rundy na serwerze nadrzędnym. Wywołujemy połączenie protokołu WebSocket z json.webpubsub.azure.v1 podprotocolem klienta Protokołu WebSocket PubSub. Aby uzyskać więcej informacji, zobacz specyfikację klienta Web PubSub w witrynie GitHub.

Na przykład w języku JS można utworzyć klienta Protokołu WebSocket PubSub przy użyciu następującego kodu.

// PubSub WebSocket client
var pubsub = new WebSocket(
  "wss://test.webpubsub.azure.com/client/hubs/hub1",
  "json.webpubsub.azure.v1"
);

Klient protokołu WebSocket PubSub może wykonywać następujące czynności:

Dołącz do grupy, na przykład:

{
  "type": "joinGroup",
  "group": "<group_name>"
}

Pozostaw grupę, na przykład:

{
  "type": "leaveGroup",
  "group": "<group_name>"
}

Publikowanie komunikatów w grupie, na przykład:

{
  "type": "sendToGroup",
  "group": "<group_name>",
  "data": { "hello": "world" }
}

Wysyłaj zdarzenia niestandardowe do nadrzędnego serwera, na przykład:

{
  "type": "event",
  "event": "<event_name>",
  "data": { "hello": "world" }
}

Kolumna podrzędna PubSub WebSocket zawiera szczegóły podprotokolujson.webpubsub.azure.v1.

Zauważyliśmy, że w przypadku prostego klienta protokołu WebSocket serwer musi mieć rolę do odbierania message zdarzeń od klientów. Proste połączenie protokołu WebSocket zawsze wyzwala message zdarzenie podczas wysyłania komunikatów i zawsze opiera się na stronie serwera w celu przetwarzania komunikatów i wykonywania innych operacji. Za pomocą json.webpubsub.azure.v1 podprotocol autoryzowanego klienta może dołączyć do grupy i opublikować komunikaty bezpośrednio w grupie. Może również kierować komunikaty do różnych programów obsługi zdarzeń/odbiorników zdarzeń, dostosowując zdarzenie , do którego należy komunikat.

Scenariusze

Takich klientów można używać, gdy klienci chcą komunikować się ze sobą. Komunikaty są wysyłane z client2 usługi do usługi, a usługa dostarcza komunikat bezpośrednio do client1 klienta, jeśli są autoryzowani do tego celu.

Klient1:

var client1 = new WebSocket(
  "wss://xxx.webpubsub.azure.com/client/hubs/hub1",
  "json.webpubsub.azure.v1"
);
client1.onmessage = (e) => {
  if (e.data) {
    var message = JSON.parse(e.data);
    if (message.type === "message" && message.group === "Group1") {
      // Only print messages from Group1
      console.log(message.data);
    }
  }
};

client1.onopen = (e) => {
  client1.send(
    JSON.stringify({
      type: "joinGroup",
      group: "Group1",
    })
  );
};

Klient2:

var client2 = new WebSocket("wss://xxx.webpubsub.azure.com/client/hubs/hub1", "json.webpubsub.azure.v1");
client2.onopen = e => {
    client2.send(JSON.stringify({
        type: "sendToGroup",
        group: "Group1",
        data: "Hello Client1"
    });
};

Jak pokazano w powyższym przykładzie, client2 wysyła dane bezpośrednio do client1 usługi, publikując komunikaty, do Group1 których client1 się znajdują.

Podsumowanie zdarzeń klienta

Zdarzenia klienta należą do dwóch kategorii:

Zdarzenia synchroniczne (blokujące) Synchroniczne blokują przepływ pracy klienta.
- connect: to zdarzenie dotyczy tylko programu obsługi zdarzeń. Po uruchomieniu uzgadniania protokołu WebSocket zdarzenie jest wyzwalane, a deweloperzy mogą użyć connect programu obsługi zdarzeń do obsługi uzgadniania protokołu WebSocket, określić podprotocol do użycia, uwierzytelnić klienta i dołączyć klienta do grup.
- message: to zdarzenie jest wyzwalane, gdy klient wysyła komunikat.
Zdarzenia asynchroniczne (nieblokacyjne) Zdarzenia asynchroniczne nie blokują przepływu pracy klienta. Zamiast tego wysyłają powiadomienie do serwera. Gdy taki wyzwalacz zdarzenia ulegnie awarii, usługa rejestruje szczegóły błędu.
- connected: to zdarzenie jest wyzwalane, gdy klient łączy się z usługą pomyślnie.
- disconnected: to zdarzenie jest wyzwalane po rozłączeniu klienta z usługą.

Limit komunikatów klienta

Maksymalny dozwolony rozmiar komunikatu dla jednej ramki protokołu WebSocket wynosi 1 MB.

Uwierzytelnianie klienta

Przepływ pracy uwierzytelniania

Klient używa podpisanego tokenu JWT w celu nawiązania połączenia z usługą. Nadrzędny element może również odrzucić klienta, gdy jest connect to program obsługi zdarzeń klienta przychodzącego. Program obsługi zdarzeń uwierzytelnia klienta, określając userId element i roleklienta w odpowiedzi elementu webhook lub odrzucić klienta z 401. Sekcja obsługi zdarzeń szczegółowo opisuje ją.

Na poniższym wykresie opisano przepływ pracy.

Diagram przedstawiający przepływ pracy uwierzytelniania klienta.

Klient może publikować na innych klientach tylko wtedy, gdy jest autoryzowany . S roleklienta określa początkowe uprawnienia, które klient ma:

Rola	Uprawnienie
Nieokreślona	Klient może wysyłać zdarzenia.
`webpubsub.joinLeaveGroup`	Klient może dołączyć/pozostawić dowolną grupę.
`webpubsub.sendToGroup`	Klient może publikować komunikaty w dowolnej grupie.
`webpubsub.joinLeaveGroup.<group>`	Klient może dołączyć/opuścić grupę `<group>`.
`webpubsub.sendToGroup.<group>`	Klient może publikować komunikaty w grupie `<group>`.

Po stronie serwera można również udzielić lub odwołać uprawnień klienta dynamicznie za pośrednictwem protokołu serwera, co można zilustrować w dalszej sekcji.

Protokół serwera

Protokół serwera udostępnia funkcje serwera do obsługi zdarzeń klienta i zarządzania połączeniami klienta i grupami.

Ogólnie rzecz biorąc, protokół serwera zawiera trzy role:

Procedura obsługi zdarzeń
Menedżer połączeń
Odbiornik zdarzeń

Procedura obsługi zdarzeń

Procedura obsługi zdarzeń obsługuje przychodzące zdarzenia klienta. Programy obsługi zdarzeń są rejestrowane i konfigurowane w usłudze za pośrednictwem portalu lub interfejsu wiersza polecenia platformy Azure. Po wyzwoleniu zdarzenia klienta usługa może określić, czy zdarzenie ma być obsługiwane, czy nie. Teraz używamy PUSH trybu do wywoływania programu obsługi zdarzeń. Procedura obsługi zdarzeń po stronie serwera uwidacznia publicznie dostępny punkt końcowy, który ma być wywoływany po wyzwoleniu zdarzenia. Działa jako element webhook.

Usługa Web PubSub dostarcza zdarzenia klienta do nadrzędnego elementu webhook przy użyciu protokołu HTTP CloudEvents.

Dla każdego zdarzenia usługa formułuje żądanie HTTP POST do zarejestrowanego nadrzędnego strumienia i oczekuje odpowiedzi HTTP.

Dane wysyłane z usługi do serwera są zawsze w formacie CloudEvents binary .

Diagram przedstawiający tryb wypychania zdarzeń usługi Web PubSub.

Nadrzędna i walidacja

Programy obsługi zdarzeń należy zarejestrować i skonfigurować w usłudze za pośrednictwem portalu lub interfejsu wiersza polecenia platformy Azure przed pierwszym użyciem. Po wyzwoleniu zdarzenia klienta usługa może określić, czy zdarzenie musi być obsługiwane, czy nie. W publicznej wersji zapoznawczej używamy PUSH trybu do wywoływania programu obsługi zdarzeń. Procedura obsługi zdarzeń po stronie serwera uwidacznia publicznie dostępny punkt końcowy dla usługi, który ma być wywoływany po wyzwoleniu zdarzenia. Działa jako element webhook nadrzędny.

Adres URL może użyć {event} parametru do zdefiniowania szablonu adresu URL dla procedury obsługi elementu webhook. Usługa oblicza wartość adresu URL elementu webhook dynamicznie po wystąpieniu żądania klienta. Na przykład gdy żądanie /client/hubs/chat zostanie dołączone, ze skonfigurowanym wzorcem http://host.com/api/{event} adresu URL procedury obsługi zdarzeń dla centrum chat, gdy klient nawiązuje połączenie, najpierw post do tego adresu URL: http://host.com/api/connect. To zachowanie może być przydatne, gdy klient protokołu WebSocket pubSub wysyła zdarzenia niestandardowe, które program obsługi zdarzeń pomaga wysyłać różne zdarzenia do innego nadrzędnego strumienia. Parametr {event} nie jest dozwolony w nazwie domeny adresu URL.

Podczas konfigurowania procedury obsługi zdarzeń nadrzędnej za pośrednictwem witryny Azure Portal lub interfejsu wiersza polecenia usługa jest zgodna z ochroną przed nadużyciami cloudEvents w celu zweryfikowania nadrzędnego elementu webhook. Nagłówek WebHook-Request-Origin żądania jest ustawiony na nazwę xxx.webpubsub.azure.comdomeny usługi i oczekuje, że odpowiedź z nagłówkiem WebHook-Allowed-Origin będzie zawierać tę nazwę domeny.

Podczas sprawdzania {event} poprawności parametr jest rozpoznawany jako validate. Na przykład podczas próby ustawienia adresu URL http://host.com/api/{event}na wartość usługa próbuje ustawić opcję OPCJE żądania http://host.com/api/validate i tylko wtedy, gdy odpowiedź jest prawidłowa, konfigurację można ustawić pomyślnie.

Na razie nie obsługujemy funkcji WebHook-Request-Rate i WebHook-Request-Callback.

Uwierzytelnianie/autoryzacja między usługą a elementem webhook

Aby ustanowić bezpieczne uwierzytelnianie i autoryzację między usługą a elementem webhook, rozważ następujące opcje i kroki:

Tryb anonimowy
Proste uwierzytelnianie udostępniane code za pośrednictwem skonfigurowanego adresu URL elementu webhook.
Użyj autoryzacji firmy Microsoft Entra. Aby uzyskać więcej informacji, zobacz , jak używać tożsamości zarządzanej , aby uzyskać szczegółowe informacje.

Włącz tożsamość dla usługi Web PubSub.
Wybierz z istniejącej aplikacji Microsoft Entra, która oznacza aplikację internetową elementu webhook.

Menedżer połączeń

Serwer jest z natury autoryzowanym użytkownikiem. Za pomocą roli procedury obsługi zdarzeń serwer zna metadane klientów, na przykład connectionId i userId, aby mógł:

Zamykanie połączenia klienta
Wysyłanie komunikatów do klienta
Wysyłanie komunikatów do klientów należących do tego samego użytkownika
Dodawanie klienta do grupy
Dodawanie klientów uwierzytelnionych jako ten sam użytkownik do grupy
Usuwanie klienta z grupy
Usuwanie klientów uwierzytelnionych jako ten sam użytkownik z grupy
Publikowanie komunikatów w grupie

Może również przyznać lub odwołać uprawnienia publikowania/dołączania dla klienta PubSub:

Udzielanie uprawnień publikowania/dołączania do określonej grupy lub do wszystkich grup
Odwoływanie uprawnień publikowania/dołączania dla określonej grupy lub dla wszystkich grup
Sprawdź, czy klient ma uprawnienia do dołączania lub publikowania w określonej grupie lub we wszystkich grupach

Usługa udostępnia interfejsy API REST dla serwera do zarządzania połączeniami.

Diagram przedstawiający przepływ pracy menedżera połączeń usługi Web PubSub.

Szczegółowy protokół interfejsu API REST jest zdefiniowany tutaj.

Odbiornik zdarzeń

Uwaga

Funkcja odbiornika zdarzeń jest dostępna w wersji zapoznawczej.

Odbiornik zdarzeń nasłuchuje przychodzących zdarzeń klienta. Każdy odbiornik zdarzeń zawiera filtr określający rodzaje zdarzeń, których dotyczy, punkt końcowy dotyczący miejsca wysyłania zdarzeń do.

Obecnie obsługujemy usługę Event Hubs jako punkt końcowy odbiornika zdarzeń.

Należy wcześniej zarejestrować odbiorniki zdarzeń, aby po wyzwoleniu zdarzenia klienta usługa mogła wypchnąć zdarzenie do odpowiednich odbiorników zdarzeń. Zobacz ten dokument , aby dowiedzieć się, jak skonfigurować odbiornik zdarzeń za pomocą punktu końcowego centrum zdarzeń.

Można skonfigurować wiele odbiorników zdarzeń. Kolejność ich konfigurowania nie ma wpływu na ich funkcjonalność. Jeśli zdarzenie pasuje do wielu odbiorników, zdarzenie jest wysyłane do wszystkich pasujących odbiorników. Zapoznaj się z poniższym diagramem, aby zapoznać się z przykładem. Jeśli na przykład skonfigurujesz jednocześnie cztery odbiorniki zdarzeń, każdy odbiornik odbierający dopasowanie przetwarza zdarzenie. Zdarzenie klienta zgodne z trzema z tych odbiorników jest wysyłane do trzech odbiorników, a pozostały odbiornik jest ignorowany.

Przykładowy diagram przepływu danych odbiornika zdarzeń

Można połączyć program obsługi zdarzeń i odbiorniki zdarzeń dla tego samego zdarzenia. W takim przypadku zarówno program obsługi zdarzeń, jak i odbiorniki zdarzeń odbierają zdarzenie.

Usługa Web PubSub dostarcza zdarzenia klienta do odbiorników zdarzeń przy użyciu rozszerzenia AMQP cloudEvents dla usługi Azure Web PubSub.

Podsumowanie

Rola programu obsługi zdarzeń obsługuje komunikację z usługi do serwera, podczas gdy rola menedżera obsługuje komunikację z serwera do usługi. Po połączeniu tych dwóch ról przepływ danych między usługą i serwerem wygląda podobnie do poniższego diagramu przy użyciu protokołu HTTP.

Diagram przedstawiający przepływ pracy dwukierunkowego usługi Web PubSub.