Megosztás a következőn keresztül:

Az Azure Web PubSub által támogatott JSON WebSocket-alprotocol

  • Cikk

A JSON WebSocket alprotocolja lehetővé teszi a közzétételi/előfizetési üzenetek cseréjét az ügyfelek között a szolgáltatáson keresztül anélkül, json.webpubsub.azure.v1hogy a felsőbb rétegbeli kiszolgálóra utazik. Az alprojektet használó json.webpubsub.azure.v1 WebSocket-kapcsolatot PubSub WebSocket-ügyfélnek nevezzük.

Áttekintés

Egy egyszerű WebSocket-kapcsolat eseményt message aktivál, amikor üzeneteket küld, és a kiszolgálóoldalra támaszkodik az üzenetek feldolgozásához és más műveletek végrehajtásához.

json.webpubsub.azure.v1 Az alprotocol segítségével létrehozhat PubSub WebSocket-ügyfeleket, amelyek a következőre képesek:

Létrehozhat például egy PubSub WebSocket-ügyfelet a következő JavaScript-kóddal:

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

Ez a dokumentum a részprotocol-kérelmeket json.webpubsub.azure.v1 és a válaszokat ismerteti. Mind a bejövő, mind a kimenő adatkeretnek JSON hasznos adatokat kell tartalmaznia.

Engedélyek

A PubSub WebSocket-ügyfél csak akkor tehet közzé más ügyfeleket, ha az engedélyezett. Az roles ügyfélhez rendeltek határozzák meg az ügyfélnek adott engedélyeket:

Szerepkör Engedély
Nincs megadva Az ügyfél eseménykérelmeket küldhet.
webpubsub.joinLeaveGroup Az ügyfél bármilyen 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 csoportban <group>.

A kiszolgáló dinamikusan adhat meg vagy vonhat vissza ügyfélengedélyeket REST API-k vagy kiszolgálói SDK-k használatával.

maximális száma

Csoportok csatlakoztatása

Formátum:

{
    "type": "joinGroup",
    "group": "<group_name>",
    "ackId" : 1
}

Csoportok elhagyása

Formátum:

{
    "type": "leaveGroup",
    "group": "<group_name>",
    "ackId" : 1
}

Üzenetek közzététele

Formátum:

{
    "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 az egyes kérések identitása, és egyedinek kell lenniük. A szolgáltatás egy sikertelen válaszüzenetet küld, amely értesíti a kérés folyamateredményét. Részletekért lásd: AckId és Ack Response
  • A(z) noEcho nem kötelező. Ha igaz értékre van állítva, ez az üzenet nem lesz ugyanahhoz a kapcsolathoz visszahangosulva. Ha nincs beállítva, az alapértelmezett érték hamis.
  • dataType a következőre jsonállítható be: , textvagy binary:
    • json: data bármilyen típusú lehet, amelyet a JSON támogat, és közzé lesz téve, mint amilyen; Ha dataType nincs megadva, az alapértelmezés szerint a .json
    • text: data sztringformátumban kell lennie, és a sztringadatok közzé lesznek téve;
    • binary: data alap64 formátumban kell lennie, és a bináris adatok közzé lesznek téve;

1. eset: szöveges adatok közzététele:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "text",
    "data": "text data",
    "ackId": 1
}
  • A kapott alprotocol-ügyfelek <group_name> :
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "text",
    "data" : "text data"
}
  • Az egyszerű WebSocket-ügyfelek <group_name> megkapják a sztringet text data.

2. eset: JSON-adatok közzététele:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "json",
    "data": {
        "hello": "world"
    }
}
  • A kapott alprotocol-ügyfelek <group_name> :
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "json",
    "data" : {
        "hello": "world"
    }
}
  • Az egyszerű WebSocket-ügyfelek <group_name> a szerializált sztringet {"hello": "world"}kapják.

3. eset: bináris adatok közzététele:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "binary",
    "data": "<base64_binary>",
    "ackId": 1
}
  • A kapott alprotocol-ügyfelek <group_name> :
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "binary",
    "data" : "<base64_binary>", 
}
  • Az egyszerű WebSocket-ügyfelek <group_name> a bináris keretben kapják meg a bináris adatokat.

Egyéni események küldése

Formátum:

{
    "type": "event",
    "event": "<event_name>",
    "ackId": 1,
    "dataType" : "json|text|binary",
    "data": {}, // data can be string or valid json token depending on the dataType 
}

dataType lehet az textegyik, binaryvagy jsona következő:

  • json: az adatok bármilyen típusú json-támogatottak lehetnek, és közzé lesznek téve, mint amilyenek; Az alapértelmezett érték a következő json: .
  • text: az adatok sztring formátumúak, és a sztringadatok közzé lesznek téve;
  • binary: az adatok base64 formátumban jelennek meg, és a bináris adatok közzé lesznek téve;

1. eset: esemény küldése szöveges adatokkal:

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

A felsőbb rétegbeli eseménykezelő a következőhöz hasonló adatokat fogad:

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

A Content-Type CloudEvents HTTP-kérésének az az oka, text/plain hogy mikor dataType van text.

2. eset: esemény küldése JSON-adatokkal:

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

A felsőbb rétegbeli eseménykezelő a következőhöz hasonló adatokat fogad:

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

A Content-Type CloudEvents HTTP-kérésének az az okaapplication/json, hogy dataTypejson

3. eset: esemény küldése bináris adatokkal:

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

A felsőbb rétegbeli eseménykezelő a következőhöz hasonló adatokat fogad:

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

A Content-Type CloudEvents HTTP-kérésének az az oka, application/octet-stream hogy mikor dataType van binary. A WebSocket-keret formátuma lehet text szöveges üzenetkeretekhez vagy UTF8 kódolású bináris fájlokhoz az üzenetkeretekhez binary .

A Web PubSub szolgáltatás elutasítja az ügyfelet, ha az üzenet nem felel meg a leírt formátumnak.

Válaszok

Az ügyfél által fogadott üzenettípusok a következőek lehetnek:

  • ack - A válasz egy kérelmet tartalmazó ackId.
  • üzenet – A csoport vagy a kiszolgáló üzenetei.
  • system – A Web PubSub szolgáltatás üzenetei.

Ack-válasz

Ha az ügyfélkérés tartalmaz ackId, a szolgáltatás a kérésre adott válaszát adja vissza. Az ügyfélnek kezelnie kell az ack mechanizmust úgy, hogy egy async await művelettel megvárja az ack választ, és időtúllépési műveletet használ, ha az ack-válasz nem érkezik meg egy adott időszakban.

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

Az ügyfél implementációjának mindig ellenőriznie kell, hogy az-e success true vagy false az első, majd csak akkor olvassa el a hibát, ha success van false.

Üzenet válasza

Az ügyfelek fogadhatnak üzeneteket egy olyan csoportból, amelyhez az ügyfél csatlakozott, vagy a kiszolgálóról, amely kiszolgálófelügyeleti szerepkörben működik, üzeneteket küld adott ügyfeleknek vagy felhasználóknak.

  1. Ha az üzenet egy csoportból származik

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

  2. Amikor az üzenet a kiszolgálóról származik.

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

1. eset: Adatok Hello World küldése a kapcsolatra a REST API-val Content-Type=text/plain

  • Egy egyszerű WebSocket-ügyfél szöveges WebSocket-keretet kap adatokkal: Hello World;

  • A PubSub WebSocket-ügyfél a következőt kapja:

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

2. eset: Adatok { "Hello" : "World"} küldése a kapcsolatra a REST API-val Content-Type=application/json

  • Egy egyszerű WebSocket-ügyfél szöveges WebSocket-keretet kap sztringezett adatokkal: { "Hello" : "World"}.

  • A PubSub WebSocket-ügyfél a következőt kapja:

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

Ha a REST API tartalomtípussal küld sztringetHello World, az egyszerű WebSocket-ügyfél egy JSON-sztringet kap, amely dupla idézőjelekkel (") van "Hello World" becsomagolva.application/json

3. eset: Bináris adatok küldése a kapcsolatra a REST API-val Content-Type=application/octet-stream

  • Egy egyszerű WebSocket-ügyfél bináris WebSocket-keretet kap a bináris adatokkal.

  • A PubSub WebSocket-ügyfél a következőt kapja:

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

Rendszer válasza

A Web PubSub szolgáltatás rendszerhez kapcsolódó üzeneteket küld az ügyfeleknek.

Csatlakoztatva

Az ügyfélnek küldött üzenet, amikor az ügyfél sikeresen csatlakozik:

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

Leválasztva

Az ügyfélnek küldött üzenet, amikor a kiszolgáló bezárja a kapcsolatot, vagy amikor a szolgáltatás elutasítja az ügyfelet.

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

Következő lépések

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

Oktatóanyag: Üzenetek közzététele és feliratkozás az Azure Web PubSubban

Oktatóanyag: Egyszerű csevegőszoba létrehozása az Azure Web PubSub használatával

Oktatóanyag: Szolgáltatás által támogatott alprotocol használata az ügyfélstreameléshez

Oktatóanyag: Kiszolgáló nélküli csevegés létrehozása az Azure Functions és a Web PubSub használatával

Oktatóanyag: Eseményfigyelő konfigurálása

Élő bemutatók lejátszása

További Azure Web PubSub-minták felfedezése