Protokoły klienta protokołu WebSocket dla usługi Azure Web PubSub

Klienci łączą się z usługą Azure Web PubSub przy użyciu standardowego protokołu WebSocket .

Punkty końcowe usługi

Usługa Web PubSub udostępnia dwa typy punktów końcowych dla klientów, z którymi można nawiązać połączenie:

/client/hubs/{hub}
/client/?hub={hub}

{hub} jest obowiązkowym parametrem, który działa jako izolacja dla różnych aplikacji. Można ustawić to w ścieżce lub zapytaniu.

Autoryzacja

Klienci łączą się z usługą przy użyciu tokenu internetowego JSON (JWT). Token może znajdować się w ciągu zapytania jako /client/?hub={hub}&access_token={token}, lub nagłówku Authorization jako Authorization: Bearer {token}.

Oto ogólny przepływ pracy autoryzacji:

Klient negocjuje z serwerem aplikacji. Serwer aplikacji zawiera oprogramowanie pośredniczące autoryzacji, które obsługuje żądanie klienta i podpisuje JWT, aby klient nawiązał połączenie z usługą.
Serwer aplikacji zwraca JWT i adres URL usługi do klienta.
Klient próbuje nawiązać połączenie z usługą Web PubSub przy użyciu adresu URL i JWT zwróconego z serwera aplikacji.

Obsługiwane roszczenia

Właściwości połączenia klienta można również skonfigurować podczas generowania tokenu dostępu, określając specjalne oświadczenia wewnątrz zestawu JWT:

Opis	Typ oświadczenia	Wartość oświadczenia	Notatki
Dla `userId` połączenia klienta	`sub`	identyfikator użytkownika	Dozwolone jest tylko jedno `sub` oświadczenie.
Okres istnienia tokenu	`exp`	czas wygaśnięcia	Oświadczenie `exp` (czas wygaśnięcia) identyfikuje czas wygaśnięcia w dniu lub po upływie którego token NIE MOŻE zostać zaakceptowany do przetwarzania.
Uprawnienia, które początkowo ma połączenie klienta	`role`	wartość roli zdefiniowana w uprawnieniach	Określ wiele `role` oświadczeń, jeśli klient ma wiele uprawnień.
Początkowe grupy, do których połączenie klienta dołącza po nawiązaniu połączenia z usługą Azure Web PubSub	`webpubsub.group`	grupa, do której można dołączyć	Określ wiele `webpubsub.group` żądań, jeśli klient dołącza do wielu grup.

Możesz również dodać oświadczenia niestandardowe do tokenu dostępu, a te wartości są zachowywane jako claims właściwość w treści połączenia nadrzędnego żądania.

Zestawy SDK serwera udostępniają interfejsy API do generowania tokenu dostępu dla klientów.

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ć własny niestandardowy podprotokol.

Na przykład w języku JavaScript 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 ma dwa tryby: sendEvent i sendToGroup. Tryb jest określany po nawiązaniu połączenia i nie można go zmienić później.

sendEvent jest trybem domyślnym dla prostego klienta protokołu WebSocket. W sendEvent trybie każda ramka protokołu WebSocket wysyłana przez klienta jest traktowana message jako zdarzenie. Użytkownicy mogą konfigurować programy obsługi zdarzeń lub odbiorniki zdarzeń w celu obsługi tych message zdarzeń.

// Every data frame is considered as a `message` event
var client3 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1');

// Or explicitly set the mode
var client4 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1?webpubsub_mode=sendEvent');

W sendToGroup trybie każda ramka protokołu WebSocket wysłana przez klienta jest traktowana jako komunikat do opublikowania w określonej grupie. group jest wymaganym parametrem zapytania w tym trybie, a dozwolona jest tylko pojedyncza wartość. Połączenie powinno również mieć odpowiednie uprawnienia do wysyłania komunikatów do grupy docelowej. Zarówno role webpubsub.sendToGroup.<group> i webpubsub.sendToGroup pasują do niego.

Na przykład w JavaScript można utworzyć prostego klienta WebSocket w trybie sendToGroup z group=group1 przy użyciu następującego kodu:

var client5 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1?webpubsub_mode=sendToGroup&group=group1');

Klient protokołu WebSocket PubSub

Klient protokołu WebSocket PubSub to klient protokołu WebSocket używający subprotokołów zdefiniowanych przez usługę Azure Web PubSub:

json.webpubsub.azure.v1
protobuf.webpubsub.azure.v1

Dzięki podprotokolowi obsługiwanemu przez usługę klient PubSub WebSocketmoże bezpośrednio publikować komunikaty w grupach, gdy mają uprawnienia.

Subprotokół `json.webpubsub.azure.v1`

Sprawdź tutaj, aby szczegółowo zapoznać się z podprotokolem JSON.

Tworzenie klienta protokołu WebSocket pubSub

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

Dołącz do grupy bezpośrednio z poziomu klienta

let ackId = 0;
pubsubClient.send(
    JSON.stringify({
        type: 'joinGroup',
        group: 'group1',
        ackId: ++ackId
    }));

Bezpośrednie wysyłanie komunikatów do grupy z klienta

let ackId = 0;
pubsubClient.send(
    JSON.stringify({
        type: 'sendToGroup',
        group: 'group1',
        ackId: ++ackId,
        dataType: "json",
        data: {
            "hello": "world"
        }
    }));

Podprotokół `protobuf.webpubsub.azure.v1`

Bufory protokołów (protobuf) to neutralny dla języka i platformy protokół oparty na binarnym formacie, który upraszcza przesyłanie danych binarnych. Protobuf udostępnia narzędzia do generowania klientów w wielu językach, takich jak Java, Python, Objective-C, C# i C++. Dowiedz się więcej o protobuf.

Na przykład w języku JavaScript można utworzyć klienta PubSub WebSocket z subprotokołem protobuf, przy użyciu następującego kodu:

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

Sprawdź tutaj, aby szczegółowo zapoznać się z podprotokolem protobuf.

AckId i Odpowiedź na Ack

Klient protokołu WebSocket PubSub obsługuje ackId właściwość dla joinGroupkomunikatów , leaveGroupsendToGroup i event . W przypadku korzystania z programu ackId, możesz otrzymać komunikat potwierdzenia po przetworzeniu żądania. Możesz zdecydować się na pominięcie ackId w scenariuszach typu fire-and-forget. W artykule opisujemy różnice w zachowaniu między określeniem ackId a jego brakiem.

Zachowanie, gdy nie określono `ackId`

Jeśli ackId nie zostanie określony, zostanie on wyzwolony i zapomniony. Nawet podczas brokerowania komunikatów występują błędy, nie masz możliwości otrzymywania powiadomień.

Zachowanie po określeniu `ackId`

Publikowanie idempotentne

ackId jest liczbą uint64 i powinna być unikatowa w obrębie klienta o tym samym identyfikatorze połączenia. Usługa Web PubSub rejestruje ackId, a komunikaty z tymi samymi ackId są traktowane jako ten sam komunikat. Usługa odmawia przekazywania tego samego komunikatu więcej niż raz, co jest przydatne przy ponawianiu operacji w celu uniknięcia zduplikowanych komunikatów. Jeśli na przykład klient wysyła wiadomość z ackId=5 i nie może odebrać odpowiedzi ack z ackId=5, klient ponawia próbę i ponownie wysyła tę samą wiadomość. W niektórych przypadkach komunikat jest już pośredniczony, a potwierdzenie odbioru zostaje utracone z nieznanego powodu. Usługa odrzuca ponowienie próby i wysyła odpowiedź potwierdzającą z powodem Duplicate.

Odpowiedź Ack

Usługa Web PubSub wysyła odpowiedź potwierdzającą dla każdego żądania z odpowiedzią ackId.

Format:

{
    "type": "ack",
    "ackId": 1, // The ack id for the request to ack
    "success": false, // true or false
    "error": {
        "name": "Forbidden|InternalServerError|Duplicate",
        "message": "<error_detail>"
    }
}

Element ackId kojarzy żądanie.
success jest wartością logiczną i wskazuje, czy żądanie zostało pomyślnie przetworzone przez usługę. Jeśli jest false, klienci muszą sprawdzić element error.
error istnieje tylko wtedy, gdy success jest false i klienci powinni mieć inną logikę dla różnych name. Załóżmy, że w przyszłości może być więcej typów name .
- Forbidden: klient nie ma uprawnień do wykonania żądania. Należy dodać klientowi odpowiednie role.
- InternalServerError: w usłudze wystąpił błąd wewnętrzny. Ponowna próba jest wymagana.
- Duplicate: Komunikat o tym samym ackId został już przetworzony przez usługę.

Uprawnienia

Jak najprawdopodobniej zauważono we wcześniejszym opisie klienta PubSub WebSocket, klient może publikować na innych klientach tylko wtedy, gdy jest autoryzowany do tego celu. Uprawnienia klienta można przyznać w momencie łączenia lub podczas trwania połączenia.

Role	Uprawnienie
Nieokreślona	Klient może wysyłać żądania dotyczące zdarzeń.
`webpubsub.joinLeaveGroup`	Klient może dołączyć lub pozostawić dowolną grupę.
`webpubsub.sendToGroup`	Klient może publikować komunikaty w dowolnej grupie.
`webpubsub.joinLeaveGroup.<group>`	Klient może dołączyć lub opuścić grupę `<group>`.
`webpubsub.sendToGroup.<group>`	Klient może publikować komunikaty w grupie `<group>`.
`webpubsub.joinLeaveGroups.<pattern>`	Klient może dołączyć lub opuścić dowolną grupę, której nazwa pasuje do `<pattern>` (zobacz Wzorce ról grup z symbolami wieloznacznymi).
`webpubsub.sendToGroups.<pattern>`	Klient może publikować komunikaty w jakiejkolwiek grupie, której nazwa jest zgodna z `<pattern>` (zobacz Wzorce ról grupy z użyciem symboli wieloznacznych).

Uprawnienie klienta można udzielić na kilka sposobów:

1. Przypisywanie roli do klienta podczas generowania tokenu dostępu

Klient może nawiązać połączenie z usługą przy użyciu JWT. Ładunek tokenu może przenosić informacje związane z klientem, takie jak role. Podczas podpisywania tokenu JWT dla klienta można nadać mu uprawnienia, przypisując określone role.

Podpiszmy na przykład JWT, który ma uprawnienia do wysyłania komunikatów do group1 i group2:

let token = await serviceClient.getClientAccessToken({
    roles: [ "webpubsub.sendToGroup.group1", "webpubsub.sendToGroup.group2" ]
});

2. Przypisz rolę do klienta za pomocą programu obsługi zdarzeń `connect`

Role klientów można również ustawić, gdy connect program obsługi zdarzeń jest zarejestrowany, a program obsługi zdarzeń nadrzędnych może zwrócić roles klienta do usługi Web PubSub podczas obsługi connect zdarzeń.

Na przykład w języku JavaScript można skonfigurować to zdarzenie handleConnect, żeby to zrobić.

let handler = new WebPubSubEventHandler("hub1", {
  handleConnect: (req, res) => {
    // auth the connection and set the userId of the connection
    res.success({
      roles: [ "webpubsub.sendToGroup.group1", "webpubsub.sendToGroup.group2" ]
    });
  },
});

3. Przypisz rolę klientowi za pomocą interfejsów API REST lub serwerowych zestawów SDK podczas wykonywania

let service = new WebPubSubServiceClient("<your_connection_string>", "test-hub");
await service.grantPermission("<connection_id>", "joinLeaveGroup", { targetName: "group1" });

Uwaga / Notatka

Przypisywanie ról wieloznacznych (np webpubsub.sendToGroups.<pattern>. ) za pośrednictwem interfejsów API REST lub zestawów SDK serwera nie jest jeszcze obsługiwane. Ta funkcja będzie obsługiwana w przyszłej aktualizacji.

Następne kroki

Użyj tych zasobów, aby rozpocząć tworzenie własnej aplikacji:

Samouczek: publikowanie i subskrybowanie komunikatów w usłudze Azure Web PubSub

Samouczek: tworzenie prostego czatroomu za pomocą usługi Azure Web PubSub

Samouczek: Użycie podprotokołu obsługiwanego przez usługę do strumieniowania klienta

Samouczek: tworzenie czatu bezserwerowego za pomocą usług Azure Functions i Web PubSub

Samouczek: konfigurowanie nasłuchiwacza zdarzeń

Zabawa z demonstracjami na żywo

Zapoznaj się z więcej przykładów usługi Azure Web PubSub

Opinia

Czy ta strona była pomocna?

Last updated on 2026-04-01