Delen via

Azure Web PubSub ondersteunde JSON WebSocket-subprotocol

  • Artikel

Met het JSON WebSocket-subprotocol kunnen json.webpubsub.azure.v1berichten worden uitgewisseld tussen clients via de service zonder een retour naar de upstream-server. Een WebSocket-verbinding met behulp van het json.webpubsub.azure.v1 subprotocol wordt een PubSub WebSocket-client genoemd.

Overzicht

Een eenvoudige WebSocket-verbinding activeert een message gebeurtenis wanneer berichten worden verzonden en is afhankelijk van de serverzijde om berichten te verwerken en andere bewerkingen uit te voeren.

Met het json.webpubsub.azure.v1 subprotocol kunt u PubSub WebSocket-clients maken die het volgende kunnen doen:

U kunt bijvoorbeeld een PubSub WebSocket-client maken met de volgende JavaScript-code:

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

In dit document worden de subprotocolaanvragen json.webpubsub.azure.v1 en -antwoorden beschreven. Zowel binnenkomende als uitgaande gegevensframes moeten JSON-nettoladingen bevatten.

Machtigingen

Een PubSub WebSocket-client kan alleen publiceren naar andere clients wanneer deze is geautoriseerd. De roles toegewezen aan de client bepaalt de machtigingen die aan de client zijn verleend:

Role Machtiging
Niet opgegeven De client kan gebeurtenisaanvragen verzenden.
webpubsub.joinLeaveGroup De client kan lid worden van elke groep of elke groep verlaten.
webpubsub.sendToGroup De client kan berichten publiceren naar elke groep.
webpubsub.joinLeaveGroup.<group> De client kan deelnemen aan/verlaten van de groep <group>.
webpubsub.sendToGroup.<group> De client kan berichten naar de groep <group>publiceren.

De server kan clientmachtigingen dynamisch verlenen of intrekken via REST API's of server-SDK's.

Verzoeken

Deelnemen aan groepen

Indeling:

{
    "type": "joinGroup",
    "group": "<group_name>",
    "ackId" : 1
}
  • ackId is de identiteit van elke aanvraag en moet uniek zijn. De service verzendt een ack-antwoordbericht om het procesresultaat van de aanvraag te melden. Zie AckId en Ack Response voor meer informatie

Groepen verlaten

Indeling:

{
    "type": "leaveGroup",
    "group": "<group_name>",
    "ackId" : 1
}
  • ackId is de identiteit van elke aanvraag en moet uniek zijn. De service verzendt een ack-antwoordbericht om het procesresultaat van de aanvraag te melden. Zie AckId en Ack Response voor meer informatie

Berichten publiceren

Indeling:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "ackId" : 1,
    "noEcho": true|false,
    "dataType" : "json|text|binary",
    "data": {}, // data can be string or valid json token depending on the dataType 
}
  • ackId is de identiteit van elke aanvraag en moet uniek zijn. De service verzendt een ack-antwoordbericht om het procesresultaat van de aanvraag te melden. Zie AckId en Ack Response voor meer informatie
  • noEcho is optioneel. Als deze optie is ingesteld op true, wordt dit bericht niet teruggeklinkt naar dezelfde verbinding. Als deze niet is ingesteld, is de standaardwaarde onwaar.
  • dataType kan worden ingesteld op json, textof binary:
    • json: data kan elk type zijn dat JSON ondersteunt en wordt gepubliceerd zoals het is; Als dataType dit niet is opgegeven, wordt deze standaard ingesteld op json.
    • text: data moet de tekenreeksindeling hebben en de tekenreeksgegevens worden gepubliceerd;
    • binary: data moet de base64-indeling hebben en de binaire gegevens worden gepubliceerd;

Case 1: tekstgegevens publiceren:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "text",
    "data": "text data",
    "ackId": 1
}
  • De subprotocolclients die worden <group_name> ontvangen:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "text",
    "data" : "text data"
}
  • De eenvoudige WebSocket-clients ontvangen <group_name> de tekenreeks text data.

Case 2: JSON-gegevens publiceren:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "json",
    "data": {
        "hello": "world"
    }
}
  • De subprotocolclients die worden <group_name> ontvangen:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "json",
    "data" : {
        "hello": "world"
    }
}
  • De eenvoudige WebSocket-clients ontvangen <group_name> de geserialiseerde tekenreeks {"hello": "world"}.

Case 3: binaire gegevens publiceren:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "binary",
    "data": "<base64_binary>",
    "ackId": 1
}
  • De subprotocolclients die worden <group_name> ontvangen:
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "binary",
    "data" : "<base64_binary>", 
}
  • De eenvoudige WebSocket-clients ontvangen <group_name> de binaire gegevens in het binaire frame.

Aangepaste gebeurtenissen verzenden

Indeling:

{
    "type": "event",
    "event": "<event_name>",
    "ackId": 1,
    "dataType" : "json|text|binary",
    "data": {}, // data can be string or valid json token depending on the dataType 
}
  • ackId is de identiteit van elke aanvraag en moet uniek zijn. De service verzendt een ack-antwoordbericht om het procesresultaat van de aanvraag te melden. Zie AckId en Ack Response voor meer informatie

dataType kan een van text, binaryof json:

  • json: gegevens kunnen elk type json worden ondersteund en worden als zodanig gepubliceerd; De standaardwaarde is json.
  • text: gegevens hebben de tekenreeksindeling en de tekenreeksgegevens worden gepubliceerd;
  • binary: gegevens hebben de base64-indeling en de binaire gegevens worden gepubliceerd;

Case 1: gebeurtenis met tekstgegevens verzenden:

{
    "type": "event",
    "event": "<event_name>",
    "ackId": 1,
    "dataType" : "text",
    "data": "text data", 
}

De upstream-gebeurtenishandler ontvangt gegevens die vergelijkbaar zijn met:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: text/plain
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>

text data

De Content-Type HTTP-aanvraag voor CloudEvents is text/plain wanneerdataType.text

Case 2: gebeurtenis verzenden met JSON-gegevens:

{
    "type": "event",
    "event": "<event_name>",
    "ackId": 1,
    "dataType" : "json",
    "data": {
        "hello": "world"
    }, 
}

De upstream-gebeurtenishandler ontvangt gegevens die vergelijkbaar zijn met:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>

{
    "hello": "world"
}

De Content-Type HTTP-aanvraag voor CloudEvents is application/json wanneer dataTypejson

Case 3: gebeurtenis verzenden met binaire gegevens:

{
    "type": "event",
    "event": "<event_name>",
    "ackId": 1,
    "dataType" : "binary",
    "data": "base64_binary", 
}

De upstream-gebeurtenishandler ontvangt gegevens die vergelijkbaar zijn met:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/octet-stream
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>

binary

De Content-Type HTTP-aanvraag voor CloudEvents is application/octet-stream wanneerdataType.binary Het WebSocket-frame kan worden text opgemaakt voor tekstberichtframes of UTF8 gecodeerde binaire bestanden voor binary berichtframes.

De Web PubSub-service weigert de client als het bericht niet overeenkomt met de beschreven indeling.

Ping

Indeling:

{
    "type": "ping",
}

De client kan een ping bericht naar de service verzenden om de Web PubSub-service in staat te stellen de liveness van de client te detecteren.

Antwoorden

Berichttypen die door de client worden ontvangen, kunnen het volgende zijn:

  • ack : het antwoord op een aanvraag met een ackId.
  • bericht - Berichten van de groep of server.
  • systeem - Berichten van de Web PubSub-service.
  • pong - Het antwoord op een ping bericht.

Ack-antwoord

Wanneer de clientaanvraag bevat ackId, retourneert de service een ack-antwoord voor de aanvraag. De client moet het ack-mechanisme verwerken door te wachten op het ack-antwoord met een asyncawait bewerking en een time-outbewerking te gebruiken wanneer het ack-antwoord in een bepaalde periode niet wordt ontvangen.

Indeling:

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

De implementatie van de client moet altijd controleren of de success is true of false eerst, en dan alleen de fout lezen wanneer success dat is false.

Berichtantwoord

Clients kunnen berichten ontvangen die zijn gepubliceerd vanuit een groep die de client heeft toegevoegd of van de server, die werkt in een serverbeheerfunctie, berichten verzendt naar specifieke clients of gebruikers.

  1. Wanneer het bericht afkomstig is van een groep

    {
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType": "json|text|binary",
    "data" : {} // The data format is based on the dataType
    "fromUserId": "abc"
}

  2. Wanneer het bericht afkomstig is van de server.

    {
    "type": "message",
    "from": "server",
    "dataType": "json|text|binary",
    "data" : {} // The data format is based on the dataType
}

Case 1: Gegevens Hello World verzenden naar de verbinding via REST API met Content-Type=text/plain

  • Een eenvoudige WebSocket-client ontvangt een webSocket-tekstframe met gegevens: Hello World

  • Een PubSub WebSocket-client ontvangt:

    {
    "type": "message",
    "from": "server",
    "dataType" : "text",
    "data": "Hello World", 
}

Case 2: Gegevens { "Hello" : "World"} verzenden naar de verbinding via REST API met Content-Type=application/json

  • Een eenvoudige WebSocket-client ontvangt een websocket-frame met tekenreeksgegevens: { "Hello" : "World"}.

  • Een PubSub WebSocket-client ontvangt:

    {
    "type": "message",
    "from": "server",
    "dataType" : "json",
    "data": {
        "Hello": "World"
    }
}

Als de REST API een tekenreeks Hello World verzendt met behulp van application/json het inhoudstype, ontvangt de eenvoudige WebSocket-client een JSON-tekenreeks, die is "Hello World" verpakt met dubbele aanhalingstekens (").

Case 3: Binaire gegevens verzenden naar de verbinding via REST API met Content-Type=application/octet-stream

  • Een eenvoudige WebSocket-client ontvangt een binair WebSocket-frame met de binaire gegevens.

  • Een PubSub WebSocket-client ontvangt:

    {
    "type": "message",
    "from": "server",
    "dataType" : "binary",
    "data": "<base64_binary>"
}

Systeemantwoord

De Web PubSub-service verzendt systeemgerelateerde berichten naar clients.

Pong-antwoord

De Web PubSub-service verzendt een pong bericht naar de client wanneer er een ping bericht van de client wordt ontvangen.

Indeling:

{
    "type": "pong",
}

Connected

Het bericht dat naar de client wordt verzonden wanneer de client verbinding maakt:

{
    "type": "system",
    "event": "connected",
    "userId": "user1",
    "connectionId": "abcdefghijklmnop",
}

Ontkoppeld

Het bericht dat naar de client wordt verzonden wanneer de server de verbinding sluit of wanneer de service de client weigert.

{
    "type": "system",
    "event": "disconnected",
    "message": "reason"
}

Volgende stappen

Gebruik deze resources om te beginnen met het bouwen van uw eigen toepassing:

Zelfstudie: Berichten publiceren en abonneren op berichten in Azure Web PubSub

Zelfstudie: Een eenvoudige chatroom maken met Azure Web PubSub

Zelfstudie: Een door de service ondersteund subprotocol gebruiken voor clientstreaming

Zelfstudie: Serverloze chat bouwen met Azure Functions en Web PubSub

Zelfstudie: Een gebeurtenislistener configureren

Spelen met live demo's

Meer Voorbeelden van Azure Web PubSub verkennen