WebSocket-ügyfélprotokollok az Azure Web PubSubhoz

Cikk
03/05/2024

Az ügyfelek a standard WebSocket protokollal csatlakoznak az Azure Web PubSubhoz.

Szolgáltatásvégpontok

A Web PubSub szolgáltatás két végponttípust biztosít az ügyfelek számára a csatlakozáshoz:

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

{hub} egy kötelező paraméter, amely elkülöníti a különböző alkalmazásokat. Beállíthatja az elérési úton vagy a lekérdezésben.

Engedélyezés

Az ügyfelek JSON webes jogkivonattal (JWT) csatlakoznak a szolgáltatáshoz. A jogkivonat a lekérdezési sztringben vagy /client/?hub={hub}&access_token={token}a Authorization fejlécben Authorization: Bearer {token}is szerepelhet.

Íme egy általános engedélyezési munkafolyamat:

Az ügyfél egyeztet az alkalmazáskiszolgálóval. Az alkalmazáskiszolgáló tartalmazza az engedélyezési köztes szoftvert, amely kezeli az ügyfélkérést, és aláír egy JWT-t az ügyfél számára a szolgáltatáshoz való csatlakozáshoz.
Az alkalmazáskiszolgáló visszaadja a JWT-t és a szolgáltatás URL-címét az ügyfélnek.
Az ügyfél az alkalmazáskiszolgálóról visszaadott URL-cím és JWT-jogkivonat használatával próbál csatlakozni a Web PubSub szolgáltatáshoz.

Támogatott jogcímek

A hozzáférési jogkivonat létrehozásakor az ügyfélkapcsolat tulajdonságait is konfigurálhatja a JWT-jogkivonaton belüli speciális jogcímek megadásával:

Leírás	Jogcím típusa	Jogcím értéke	Jegyzetek
Az `userId` ügyfélkapcsolat	`sub`	a userId	Csak egy `sub` jogcím engedélyezett.
A jogkivonat élettartama	`exp`	a lejárati idő	A `exp` (lejárati idő) jogcím azt a lejárati időt azonosítja, amelyen vagy azt követően a jogkivonat NEM fogadható el feldolgozásra.
Az ügyfélkapcsolat kezdetben érvényes engedélyei	`role`	az engedélyekben definiált szerepkör-érték	Adjon meg több `role` jogcímet, ha az ügyfél több engedéllyel rendelkezik.
Azok a kezdeti csoportok, amelyekhez az ügyfélkapcsolat csatlakozik, miután csatlakozott az Azure Web PubSubhoz	`group`	a csatlakozni kívánt csoport	Több `group` jogcím megadása, ha az ügyfél több csoporthoz csatlakozik.

Egyéni jogcímeket is hozzáadhat a hozzáférési jogkivonathoz, és ezek az értékek megmaradnak a claims kapcsolati felsőbb rétegbeli kérelem törzsében lévő tulajdonságként.

A kiszolgálói SDK-k API-kat biztosítanak az ügyfelek hozzáférési jogkivonatának létrehozásához.

Az egyszerű WebSocket-ügyfél

Az egyszerű WebSocket-ügyfél, ahogy az elnevezés is mutatja, egy egyszerű WebSocket-kapcsolat. Saját egyéni alprotocolja is lehet.

A JavaScriptben például létrehozhat egy egyszerű WebSocket-ügyfelet a következő kóddal:

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

A PubSub WebSocket-ügyfél

A PubSub WebSocket-ügyfél az Azure Web PubSub szolgáltatás által meghatározott alprojekteket használó WebSocket-ügyfél:

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

A szolgáltatás által támogatott alprotocol segítségével a PubSub WebSocket-ügyféloldalakközvetlenül közzétehetnek üzeneteket a csoportoknak, ha rendelkeznek az engedélyekkel.

Az `json.webpubsub.azure.v1` alprotocol

A JSON-alprotocol részletes ismertetését itt találja.

PubSub WebSocket-ügyfél létrehozása

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

Csoport közvetlen csatlakoztatása az ügyfélből

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

Üzenetek küldése közvetlenül egy csoportnak az ügyféltől

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

Az `protobuf.webpubsub.azure.v1` alprotocol

A protokollpufferek (protobuf) egy nyelvsemleges, platformsemleges, bináris alapú protokoll, amely leegyszerűsíti a bináris adatok küldését. A Protobuf eszközökkel számos nyelvhez hozhat létre ügyfeleket, például Java, Python, Objective-C, C# és C++ nyelven. További információ a protobufról.

A JavaScriptben például létrehozhat egy PubSub WebSocket-ügyfelet protobuf subprotocol használatával a következő kóddal:

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

Itt találja a protobuf subprotocol részletes leírását.

AckId és Ack-válasz

A PubSub WebSocket-ügyfél támogatja ackId az joinGroup, sendToGroupleaveGroupés event az üzenetek tulajdonságát. Ha ezt használja ackId, a kérés feldolgozásakor kap egy nem megfelelő válaszüzenetet. Választhat, hogy kihagyja ackId a tűz és a felejtés forgatókönyveket. A cikkben ismertetjük a viselkedésbeli különbségeket a definiálás vagy a nem megadása ackId között.

Viselkedés, ha nincs `ackId` megadva

Ha ackId nincs megadva, akkor a tűz és a felejtés. Még az üzenetek közvetítése során is vannak hibák, nem tud értesítést kapni.

Viselkedés megadásakor `ackId`

Idempotens közzététel

ackId egy uint64-szám, és egyedinek kell lennie egy azonos kapcsolatazonosítóval rendelkező ügyfélen belül. A Web PubSub Service rögzíti az ackId azonos ackId üzeneteket, és a rendszer ugyanazt az üzenetet kezeli. A szolgáltatás nem hajlandó többször is elküldeni ugyanazt az üzenetet, ami hasznos lehet az ismétlődő üzenetek elkerülése érdekében. Ha például egy ügyfél egy üzenetet küld a következővel ackId=5 , és nem kap meg egy nem megfelelő választ ackId=5, akkor az ügyfél újra próbálkozik, és ismét ugyanazt az üzenetet küldi. Bizonyos esetekben az üzenet már közvetítve van, és a válasz valamilyen okból elvész. A szolgáltatás elutasítja az újrapróbálkozási műveletet, és ok nélkül válaszol a válaszra Duplicate .

Ack-válasz

A Web PubSub Service a következővel küldi el az egyes kérésekre ackIdadott válaszokat: .

Formátum:

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

A ackId kérés társítása.
success egy bool, és jelzi, hogy a kérést sikeresen feldolgozta-e a szolgáltatás. Ha így van false, az ügyfeleknek ellenőriznie kell a error.
error csak akkor létezik, ha success van, és az false ügyfeleknek eltérő logikával kell rendelkezniük a különböző name. Tegyük fel, hogy a jövőben több típus name is lehet.
- Forbidden: Az ügyfél nem rendelkezik a kéréshez szükséges engedéllyel. Az ügyfelet hozzá kell adni a megfelelő szerepkörökhöz.
- InternalServerError: Belső hiba történt a szolgáltatásban. Újrapróbálkozás szükséges.
- Duplicate: Az azonos ackId üzenetet már feldolgozta a szolgáltatás.

Engedélyek

Ahogy azt a Korábbi PubSub WebSocket ügyfélleírásban is észrevette, az ügyfél csak akkor tehet közzé közzétételt más ügyfeleken, ha erre jogosult . Az ügyfél engedélyei a csatlakozáskor vagy a kapcsolat élettartama alatt adhatóak meg.

Szerepkör	Engedély
Nincs megadva	Az ügyfél eseménykérelmeket küldhet.
`webpubsub.joinLeaveGroup`	Az ügyfél bármelyik csoporthoz csatlakozhat vagy kiléphet.
`webpubsub.sendToGroup`	Az ügyfél bármilyen csoportban közzétehet üzeneteket.
`webpubsub.joinLeaveGroup.<group>`	Az ügyfél csatlakozhat vagy kiléphet a csoportból `<group>`.
`webpubsub.sendToGroup.<group>`	Az ügyfél közzéteheti az üzeneteket a csoport `<group>`számára.

Az ügyfél engedélye többféleképpen adható meg:

1. A szerepkör hozzárendelése az ügyfélhez a hozzáférési jogkivonat létrehozásakor

Az ügyfél JWT-jogkivonat használatával tud csatlakozni a szolgáltatáshoz. A jogkivonat hasznos adatai olyan információkat tartalmazhatnak, mint role az ügyfél. Amikor aláírja a JWT-jogkivonatot az ügyfélnek, engedélyeket adhat az ügyfélnek az ügyfélspecifikus szerepkörök megadásával.

Például írjunk alá egy JWT-jogkivonatot, amely rendelkezik engedéllyel az üzenetek küldésére a következő címregroup1:group2

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

2. A szerepkör hozzárendelése az ügyfélhez az `connect` eseménykezelővel

Az ügyfelek szerepkörei akkor is beállíthatók, ha az connect eseménykezelő regisztrálva van, és a felsőbb rétegbeli eseménykezelő vissza tudja adni az roles ügyfélét a Web PubSub szolgáltatásnak az connect események kezelésekor.

A JavaScriptben például a következő módon konfigurálhatja az handleConnect eseményt:

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. A szerepkör hozzárendelése az ügyfélhez REST API-k vagy kiszolgálói SDK-k használatával futásidőben

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