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

Artykuł
02/28/2024

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ć ją 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 adres URL usługi 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 tokenu JWT zwróconego z serwera aplikacji.

Obsługiwane oświadczenia

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 tokenu JWT:

opis	Typ oświadczenia	Wartość oświadczenia	Uwagi
Dla `userId` połączenia klienta	`sub`	identyfikator userId	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 przyłączone przez połączenie klienta po nawiązaniu połączenia z usługą Azure Web PubSub	`group`	grupa do dołączenia	Określ wiele `group` oświadczeń, 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')

Klient protokołu WebSocket PubSub

Klient protokołu WebSocket PubSub jest klientem protokołu WebSocket przy użyciu podprotocols zdefiniowanych przez usługę Azure Web PubSub:

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

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

Kolumna podrzędna `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łączanie grupy bezpośrednio z 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"
        }
    }));

Kolumna podrzędna `protobuf.webpubsub.azure.v1`

Bufory protokołu (protobuf) to neutralny dla języka protokół oparty na platformie, który upraszcza wysył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 protokołu WebSocket PubSub z podprotocol 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 Ack Response

Klient protokołu WebSocket PubSub obsługuje ackId właściwość dla joinGroupkomunikatów , leaveGroupsendToGroup i event . W przypadku korzystania z programu ackIdmożesz otrzymać komunikat odpowiedzi ack po przetworzeniu żądania. Możesz pominąć ackId scenariusze fire-and-forget. W artykule opisano różnice między określeniem ackId , czy nie.

Zachowanie, gdy nie `ackId` określono

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 komunikaty i z tym samymi ackId są traktowane jako ten sam komunikat. Usługa odmawia brokera tego samego komunikatu więcej niż raz, co jest przydatne podczas ponawiania próby, aby uniknąć zduplikowanych komunikatów. Jeśli na przykład klient wysyła komunikat z komunikatem ackId=5 i nie może odebrać odpowiedzi ack z ackId=5poleceniem , klient ponawia próbę i ponownie wysyła ten sam komunikat. W niektórych przypadkach komunikat jest już obsługiwany i z jakiegoś powodu odpowiedź ack zostanie utracona. Usługa odrzuca ponawianie próby i odpowiedź na odpowiedź z przyczyną Duplicate .

Odpowiedź Ack

Usługa Web PubSub wysyłacką odpowiedź dla każdego żądania za pomocą polecenia 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 falseto , klienci muszą sprawdzić element error.
error Istnieje tylko wtedy, gdy success jest i false 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 żądania. Należy dodać odpowiednie role klienta.
- 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ć, gdy jest połączony lub w okresie istnienia połączenia.

Rola	Uprawnienie
Nieokreślona	Klient może wysyłać żądania 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>`.

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 tokenu JWT. Ładunek tokenu może przenosić informacje, takie jak role klient. Podczas podpisywania tokenu JWT na kliencie można przyznać klientowi uprawnienia, udzielając określonych ról klienta.

Na przykład podpisać token 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ć handleConnect to zdarzenie, aby 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. Przypisywanie roli do klienta za pomocą interfejsów API REST lub zestawów SDK serwera podczas wykonywania

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