Klientské protokoly WebSocket pro Azure Web PubSub

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 to nastavit buď v cestě, nebo v parametru 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 JWT vráceného z aplikačního serveru.

Podporovaná tvrzení

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

Popis	Typ požadavku	Hodnota nároku	Poznámky
Připojení `userId` klienta	`sub`	id uživatele	Je povolen pouze jeden `sub` nárok.
Ž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 původně	`role`	hodnota role definovaná v oprávněních	Zadejte více `role` položek, pokud má klient více oprávnění.
Počáteční skupiny, ke kterým se připojení klienta připojí po připojení ke službě Azure Web PubSub	`webpubsub.group`	skupina, ke které se chcete připojit	Zadejte více `webpubsub.group` požadavků, 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ý WebSocket klient, jak naznačuje pojmenování, je jednoduché WebSocket připojení. 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')

Jednoduchý klient WebSocket má dva režimy: sendEvent a sendToGroup. Režim je určen po navázání připojení a nelze ho později změnit.

sendEvent je výchozí režim pro jednoduchého klienta WebSocket. V sendEvent režimu se každý rámec Protokolu WebSocket, který klient odeslal, považuje za message událost. Uživatelé mohou nakonfigurovat obslužné rutiny událostí nebo naslouchací procesy událostí pro zpracování těchto message událostí.

// 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');

V sendToGroup režimu se každý datový rámec WebSocket odeslaný klientem považuje za zprávu, která se má publikovat do konkrétní skupiny. group je povinný parametr dotazu v tomto režimu a je povolena pouze jedna hodnota. Připojení by také mělo mít odpovídající oprávnění k odesílání zpráv cílové skupině. Pro ni fungují obě role webpubsub.sendToGroup.<group> a webpubsub.sendToGroup.

V JavaScriptu můžete například vytvořit jednoduchého klienta WebSocket v sendToGroup režimu group=group1 pomocí následujícího kódu:

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

Klient PubSub WebSocket

PubSub WebSocket klient je WebSocket klient, který používá dílčí protokoly definované 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` protokol

Podrobnosti o subprotokolu JSON najdete zde.

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` subprotokol

Protocol buffers (protobuf) je jazykově neutrální, platformně neutrální, binární protokol, který zjednodušuje odesílání binárních dat. 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 protokolu protobuf.

Odpověď AckId a Ack

Klient PubSub WebSocket podporuje ackId vlastnost pro joinGroup, leaveGroup, sendToGroup a event zprávy. Při použití ackId můžete obdržet zprávu s potvrzením při zpracování vašeho požadavku. Můžete se rozhodnout vynechat ackId ve scénářích bez nutnosti dalšího zásahu. 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 zadání `ackId`

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á ackId, přičemž zprávy se stejným ackId jsou považovány za stejné. 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 s ackId=5 a neobdrží potvrzovací odpověď typu ack pomocí ackId=5, klient se pokusí znovu odeslat stejnou zprávu. V některých případech je zpráva zprostředkovaná a potvrzovací odpověď 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 odesílá potvrzující odpověď 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>"
    }
}

ackId přidruží žádost.
success je logická hodnota a označuje, jestli je požadavek úspěšně zpracován službou. Pokud je false, 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 může být více typů name.
- Forbidden: Klient nemá oprávnění k žádosti. Relevantní role musí být přidány klientovi.
- InternalServerError: Ve službě došlo k nějaké vnitřní chybě. Vyžaduje se opakování.
- Duplicate: Služba již zpracovala zprávu se stejnou ackId.

Oprávnění

Jak jste si pravděpodobně všimli v dřívějším popisu klienta WebSocket PubSub, klient může publikovat do jiných klientů pouze tehdy, když je k tomu autorizovaný. Oprávnění klientovi lze udělit, když je připojen, nebo v průběhu trvání 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í JWT. Datová část tokenu může obsahovat informace, jako role klienta. Při podepisování 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 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í událostní obslužné rutiny `connect`.

Role klientů lze také nastavit při registraci obslužné rutiny události connect a nadřazená obslužná rutina události může při zpracování událostí connect 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 serverového SDK za chodu.

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

Další kroky

Pomocí těchto prostředků můžete začít vytvářet vlastní aplikaci:

Kurz: Publikování a přihlášení k odběru zpráv ve službě Azure Web PubSub

Kurz: Vytvoření jednoduché chatovací místnosti pomocí azure Web PubSub

Kurz: Použití subprotokolu podporované služby pro streamování klientů

Kurz: Vytváření bezserverového chatu se službou Azure Functions a web pubSub

Návod: Konfigurace posluchače událostí

Přehrávání s živými ukázkami

Prozkoumání dalších ukázek Azure Web PubSub

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-04-10