WebSocket-ügyfélprotokollok az Azure Web PubSubhoz

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:

1. 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.
2. Az alkalmazáskiszolgáló visszaadja a JWT-t és a szolgáltatás URL-címét az ügyfélnek.
3. 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:

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

Az Egyszerű WebSocket-ügyfélnek két módja van: sendEvent és sendToGroup. A mód a kapcsolat létrejötte után lesz meghatározva, és később nem módosítható.

sendEvent az egyszerű WebSocket-ügyfél alapértelmezett módja. Módban sendEvent az ügyfél által küldött összes WebSocket-keret eseménynek message minősül. A felhasználók eseménykezelőket vagy eseményfigyelőket konfigurálhatnak az message események kezelésére.

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

Módban sendToGroup az ügyfél által küldött összes WebSocket-keret egy adott csoport számára közzéteendő üzenetnek minősül. group egy kötelező lekérdezési paraméter ebben a módban, és csak egyetlen érték engedélyezett. A kapcsolatnak megfelelő engedélyekkel kell rendelkeznie ahhoz is, hogy üzeneteket küldjön a célcsoportnak. Mind a webpubsub.sendToGroup szerepkörök, mind webpubsub.sendToGroup.<group> a szerepkörök működnek.

A JavaScriptben például létrehozhat egy egyszerű WebSocket-ügyfelet sendToGroup módban a következő kód használatával group=group1 :

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

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.

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" });

Következő lépések

Használja ezeket az erőforrásokat a saját alkalmazás létrehozásához: