Dela via

WebSocket-klientprotokoll för Azure Web PubSub

  • Artikel

Klienter ansluter till Azure Web PubSub med hjälp av standardprotokollet WebSocket .

Tjänstslutpunkter

Tjänsten Web PubSub innehåller två typer av slutpunkter som klienter kan ansluta till:

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

{hub} är en obligatorisk parameter som fungerar som isolering för olika program. Du kan ange den i antingen sökvägen eller frågan.

Auktorisering

Klienter ansluter till tjänsten med en JSON-webbtoken (JWT). Token kan finnas i antingen frågesträngen, som /client/?hub={hub}&access_token={token}, eller Authorization rubriken, som Authorization: Bearer {token}.

Här är ett allmänt auktoriseringsarbetsflöde:

  1. Klienten förhandlar med programservern. Programservern innehåller mellanprogrammet för auktorisering, som hanterar klientbegäran och signerar en JWT för att klienten ska ansluta till tjänsten.
  2. Programservern returnerar JWT och tjänst-URL:en till klienten.
  3. Klienten försöker ansluta till Web PubSub-tjänsten med hjälp av URL:en och JWT-token som returneras från programservern.

Anspråk som stöds

Du kan också konfigurera egenskaper för klientanslutningen när du genererar åtkomsttoken genom att ange särskilda anspråk i JWT-token:

beskrivning Anspråkstyp Anspråksvärde Kommentar
userId För klientanslutningen sub userId Endast ett sub anspråk tillåts.
Livslängden för token exp förfallotiden Anspråket exp (förfallotid) identifierar förfallotiden på eller efter vilken token INTE får accepteras för bearbetning.
De behörigheter som klientanslutningen ursprungligen har role rollvärdet som definierats i behörigheter Ange flera role anspråk om klienten har flera behörigheter.
De första grupperna som klientanslutningen ansluter till när den ansluter till Azure Web PubSub webpubsub.group gruppen som ska anslutas Ange flera webpubsub.group anspråk om klienten ansluter till flera grupper.

Du kan också lägga till anpassade anspråk i åtkomsttoken, och dessa värden bevaras som claims egenskapen i ansluta uppströms begärandetexten.

Server-SDK:er tillhandahåller API:er för att generera åtkomsttoken för klienterna.

Den enkla WebSocket-klienten

En enkel WebSocket-klient, som namngivningen anger, är en enkel WebSocket-anslutning. Den kan också ha en egen anpassad underprotokol.

I JavaScript kan du till exempel skapa en enkel WebSocket-klient med hjälp av följande kod:

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

Simple WebSocket-klienten har två lägen: sendEvent och sendToGroup. Läget bestäms när anslutningen har upprättats och kan inte ändras senare.

sendEvent är standardläget för den enkla WebSocket-klienten. I sendEvent läge betraktas varje WebSocket-ram som klienten skickade som en message händelse. Användare kan konfigurera händelsehanterare eller händelselyssnare för att hantera dessa message händelser.

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

I sendToGroup läget betraktas varje WebSocket-ram som klienten skickade som ett meddelande som ska publiceras till en specifik grupp. group är en obligatorisk frågeparameter i det här läget och endast ett enda värde tillåts. Anslutningen bör också ha motsvarande behörighet att skicka meddelanden till målgruppen. Både webpubsub.sendToGroup.<group> och webpubsub.sendToGroup roller fungerar för det.

I JavaScript kan du till exempel skapa en enkel WebSocket-klient i sendToGroup läge med group=group1 hjälp av följande kod:

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

PubSub WebSocket-klienten

En PubSub WebSocket-klient är WebSocket-klienten med hjälp av underprotokoler som definierats av Azure Web PubSub-tjänsten:

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

Med den underprotokol som stöds av tjänsten kan PubSub WebSocket-klientenpublicera meddelanden direkt till grupper när de har behörigheterna.

Delprotokolen json.webpubsub.azure.v1

Kontrollera JSON-underprotokolen här i detalj.

Skapa en PubSub WebSocket-klient

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

Anslut en grupp från klienten direkt

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

Skicka meddelanden till en grupp från klienten direkt

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

Delprotokolen protobuf.webpubsub.azure.v1

Protokollbuffertar (protobuf) är ett språkneutralt, plattformsneutralt, binärt baserat protokoll som förenklar sändning av binära data. Protobuf innehåller verktyg för att generera klienter för många språk, till exempel Java, Python, Objective-C, C# och C++. Läs mer om protobuf.

I JavaScript kan du till exempel skapa en PubSub WebSocket-klient med en protobuf-subprotocol med hjälp av följande kod:

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

Kontrollera här för protobuf subprotocol i detalj.

AckId- och Ack-svar

PubSub WebSocket Client stöder ackId egenskapen för joinGroup, leaveGroupsendToGroup och event meddelanden. När du använder ackIdkan du få ett ack-svarsmeddelande när din begäran bearbetas. Du kan välja att utelämna ackId i scenarier med eld och glöm. I artikeln beskriver vi beteendeskillnaderna mellan att ackId ange eller inte.

Beteende när Nej ackId har angetts

Om ackId inte anges är det eld och glöm. Även om det finns fel när du asynkronisera meddelanden kan du inte få något meddelande.

Beteende när ackId det anges

Publicera idempotent

ackId är ett uint64-nummer och bör vara unikt inom en klient med samma anslutnings-ID. Web PubSub Service registrerar ackId och meddelanden med samma ackId behandlas som samma meddelande. Tjänsten vägrar att asynkrona samma meddelande mer än en gång, vilket är användbart vid återförsök för att undvika duplicerade meddelanden. Om en klient till exempel skickar ett meddelande med ackId=5 och inte kan ta emot ett ack-svar med ackId=5, försöker klienten igen och skickar samma meddelande igen. I vissa fall är meddelandet redan asynkront och ack-svaret går förlorat av någon anledning. Tjänsten avvisar återförsöket och svarar ett ack-svar med Duplicate orsak.

Ack-svar

Web PubSub Service skickar ack-svar för varje begäran med 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>"
    }
}

  • Associerar ackId begäran.

  • success är en bool och anger om begäran har bearbetats av tjänsten. Om det är falsemåste klienterna errorkontrollera .

  • error finns bara när success är false och klienter ska ha olika logik för olika name. Du bör anta att det kan finnas mer typ av name i framtiden.

    • Forbidden: Klienten har inte behörighet till begäran. Klienten måste läggas till relevanta roller.
    • InternalServerError: Ett internt fel inträffade i tjänsten. Återförsök krävs.
    • Duplicate: Meddelandet med samma ackId har redan bearbetats av tjänsten.

Behörigheter

Som du förmodligen märkte i den tidigare klientbeskrivningen för PubSub WebSocket kan en klient endast publicera till andra klienter när den har behörighet att göra det. En klients behörigheter kan beviljas när den är ansluten eller under anslutningens livslängd.

Roll Behörighet
Har inte angetts Klienten kan skicka händelsebegäranden.
webpubsub.joinLeaveGroup Klienten kan ansluta till eller lämna valfri grupp.
webpubsub.sendToGroup Klienten kan publicera meddelanden till valfri grupp.
webpubsub.joinLeaveGroup.<group> Klienten kan ansluta till eller lämna gruppen <group>.
webpubsub.sendToGroup.<group> Klienten kan publicera meddelanden för att gruppera <group>.

Behörigheten för en klient kan beviljas på flera sätt:

1. Tilldela rollen till klienten när du genererar åtkomsttoken

Klienten kan ansluta till tjänsten med hjälp av en JWT-token. Tokennyttolasten kan innehålla information som role klientens. När du signerar JWT-token till klienten kan du bevilja behörigheter till klienten genom att ge klienten specifika roller.

Vi ska till exempel signera en JWT-token som har behörighet att skicka meddelanden till group1 och group2:

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

2. Tilldela rollen till klienten med connect händelsehanteraren

Klienternas roller kan också anges när connect händelsehanteraren är registrerad och den överordnade händelsehanteraren kan returnera roles klientens till Web PubSub-tjänsten vid hantering av connect händelserna.

I JavaScript kan du till exempel konfigurera händelsen så att den handleConnect gör det:

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. Tilldela rollen till klienten via REST-API:er eller server-SDK:er under körning

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

Nästa steg

Använd dessa resurser för att börja skapa ett eget program:

Självstudie: Publicera och prenumerera på meddelanden i Azure Web PubSub

Självstudie: Skapa ett enkelt chattrum med Azure Web PubSub

Självstudie: Använda en underprotokol som stöds av tjänsten för klientströmning

Självstudie: Skapa serverlös chatt med Azure Functions och Web PubSub

Självstudie: Konfigurera en händelselyssnare

Spela upp med livedemonstrationer

Utforska fler Azure Web PubSub-exempel