Klientské protokoly WebSocket pro Azure Web PubSub

Článek
02/28/2024

Klienti se připojují k podsítě Azure Web PubSub pomocí standardního protokolu WebSocket .

Koncové body služby

Služba Web PubSub poskytuje klientům dva typy koncových bodů pro připojení k:

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

{hub} je povinný parametr, který funguje jako izolace pro různé aplikace. Můžete ho nastavit v cestě nebo dotazu.

Autorizace

Klienti se připojují ke službě pomocí webového tokenu JSON (JWT). Token může být buď v řetězci dotazu, jako /client/?hub={hub}&access_token={token}nebo v hlavičce Authorization , jako Authorization: Bearer {token}.

Tady je obecný pracovní postup autorizace:

Klient vyjedná s aplikačním serverem. Aplikační server obsahuje autorizační middleware, který zpracovává požadavek klienta a podepíše JWT, aby se klient připojil ke službě.
Aplikační server vrátí JWT a adresu URL služby klientovi.
Klient se pokusí připojit ke službě Web PubSub pomocí adresy URL a tokenu JWT vráceného z aplikačního serveru.

Podporované deklarace identity

Při generování přístupového tokenu můžete také nakonfigurovat vlastnosti pro připojení klienta zadáním speciálních deklarací identity v tokenu JWT:

Popis	Typ deklarace identity	Hodnota deklarace identity	Notes
Připojení `userId` klienta	`sub`	id uživatele	Je povolená pouze jedna `sub` deklarace identity.
Životnost tokenu	`exp`	čas vypršení platnosti	Deklarace `exp` identity (čas vypršení platnosti) identifikuje dobu vypršení platnosti, po které token nesmí být přijat ke zpracování.
Oprávnění, která má připojení klienta na začátku	`role`	hodnota role definovaná v oprávněních	Zadejte více `role` deklarací identity, pokud má klient více oprávnění.
Počáteční skupiny, ke kterým se připojení klienta připojí, jakmile se připojí k podsítě Azure Web PubSub	`group`	skupina, ke které se chcete připojit	Zadejte více `group` deklarací identity, pokud se klient připojí k více skupinám.

Do přístupového tokenu můžete také přidat vlastní deklarace identity a tyto hodnoty se zachovají jako claims vlastnost v textu upstreamového požadavku.

Sady SDK serveru poskytují rozhraní API pro generování přístupového tokenu pro klienty.

Jednoduchý klient WebSocket

Jednoduchý klient WebSocket, jak naznačuje pojmenování, je jednoduché připojení WebSocket. Může mít také vlastní dílčí podprotokol.

V JavaScriptu můžete například vytvořit jednoduchého klienta WebSocket pomocí následujícího kódu:

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

Klient PubSub WebSocket je klient WebSocket pomocí dílčích protokolů definovaných službou Azure Web PubSub:

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

S podprotokolem podporovaným službou může klientPubSub WebSocket přímo publikovat zprávy do skupin, když mají oprávnění.

Dílčí `json.webpubsub.azure.v1` souhrn

Podrobnosti najdete v dílčím souhrnu JSON.

Vytvoření klienta PubSub WebSocket

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

Přímé připojení ke skupině z klienta

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

Přímé odesílání zpráv do skupiny z klienta

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

Dílčí `protobuf.webpubsub.azure.v1` souhrn

Vyrovnávací paměti protokolu (protobuf) je binární protokol založený na jazykově neutrální platformě, který zjednodušuje odesílání binárníchdatch Protobuf poskytuje nástroje pro generování klientů pro mnoho jazyků, jako je Java, Python, Objective-C, C# a C++. Přečtěte si další informace o protobuf.

Například v JavaScriptu můžete vytvořit klienta PubSub WebSocket s protobuf subprotocol pomocí následujícího kódu:

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

Podrobnosti najdete v dílčím souhrnu protobuf.

Odpověď AckId a Ack

Klient PubSub WebSocket podporuje ackId vlastnost pro joinGroup, leaveGroupsendToGroup a event zprávy. Při použití ackIdmůžete při zpracování požadavku obdržet zprávu odpovědi ack. Můžete se rozhodnout vynechat ackId scénáře požáru a zapomenutí. V článku popisujeme rozdíly v chování mezi určením ackId nebo ne.

Chování v případě, že není zadáno `ackId`

Pokud ackId není zadaný, zapomeňte na to. I při zprostředkování zpráv existují chyby, nemáte způsob, jak dostávat oznámení.

Chování při `ackId` zadání

Idempotentní publikování

ackId je číslo uint64 a mělo by být jedinečné v rámci klienta se stejným ID připojení. Služba Web PubSub zaznamenává zprávy ackId a zprávy se stejnými ackId zprávami. Služba odmítá zprostředkovat stejnou zprávu více než jednou, což je užitečné při opakování, aby se zabránilo duplicitním zprávám. Pokud například klient odešle zprávu se ackId=5 zprávou a neobdrží odpověď typu ack, ackId=5klient se pokusí znovu odeslat stejnou zprávu. V některých případech je zpráva zprostředkovaná a odpověď ack se z nějakého důvodu ztratí. Služba odmítne opakování a odpoví na odpověď typu ack s odůvodněním Duplicate .

Odpověď Ack

Služba Web PubSub odešle odpověď ack pro každý požadavek s ackId.

Formát:

{
    "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>"
    }
}

Žádost ackId se přidruží.
success je logická hodnota a označuje, jestli je požadavek úspěšně zpracován službou. Pokud je falseto , klienti musí zkontrolovat error.
error existuje pouze tehdy, když success je false a klienti by měli mít jinou logiku pro různé name. Měli byste předpokládat, že v budoucnu name může existovat více typů.
- Forbidden: Klient nemá oprávnění k žádosti. Klient musí být přidán relevantní role.
- InternalServerError: Ve službě došlo k nějaké vnitřní chybě. Vyžaduje se opakování.
- Duplicate: Služba již zprávu se stejnou ackId zprávou zpracovala.

Oprávnění

Jak jste si pravděpodobně všimli v dřívějším popisu klienta PubSub WebSocket, klient může publikovat do jiných klientů pouze v případě, že je k tomu autorizovaný . Oprávnění klienta je možné udělit, když je připojená nebo během životnosti připojení.

Role	Oprávnění
Neurčeno	Klient může odesílat žádosti o události.
`webpubsub.joinLeaveGroup`	Klient se může připojit nebo opustit libovolnou skupinu.
`webpubsub.sendToGroup`	Klient může publikovat zprávy do libovolné skupiny.
`webpubsub.joinLeaveGroup.<group>`	Klient se může připojit nebo opustit skupinu `<group>`.
`webpubsub.sendToGroup.<group>`	Klient může publikovat zprávy do skupiny `<group>`.

Oprávnění klienta lze udělit několika způsoby:

1. Přiřaďte roli klientovi při generování přístupového tokenu.

Klient se může ke službě připojit pomocí tokenu JWT. Datová část tokenu může obsahovat informace, jako role je klient. Při podepisování tokenu JWT klientovi můžete udělit oprávnění klientovi tím, že klientovi udělíte konkrétní role.

Pojďme například podepsat token JWT, který má oprávnění odesílat zprávy do group1 a group2:

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

2. Přiřaďte roli klientovi pomocí obslužné rutiny `connect` události.

Role klientů lze také nastavit při connect registraci obslužné rutiny události a nadřazená obslužná rutina události může při zpracování connect událostí vrátit roles klienta do služby Web PubSub.

Například v JavaScriptu handleConnect můžete událost nakonfigurovat tak, aby:

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. Přiřaďte roli klientovi prostřednictvím rozhraní REST API nebo sad SDK serveru během běhu.

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