Az Azure Web PubSub által támogatott protobuf WebSocket subprotocol

Cikk
2025. 01. 03.

Ez a dokumentum az alprotocolt protobuf.webpubsub.azure.v1ismerteti.

Ha egy ügyfél ezt az alprotocolt használja, a kimenő és a bejövő adatkeretek várhatóan protokollpufferek (protobuf) hasznos adattartalmak lesznek.

Áttekintés

Az alprojekt protobuf.webpubsub.azure.v1 lehetővé teszi az ügyfél számára, hogy közvetlenül tegye közzé-előfizetet (PubSub) ahelyett, hogy a felsőbb rétegbeli kiszolgálóra utazik. A WebSocket és az protobuf.webpubsub.azure.v1 alprojekt közötti kapcsolatot PubSub WebSocket-ügyfélnek nevezzük.

A JavaScriptben például létrehozhat egy PubSub WebSocket-ügyfelet a protobuf subprotocol használatával:

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

Egyszerű WebSocket-ügyfél esetén a kiszolgáló rendelkezik az ügyfelek eseményeinek kezeléséhez szükséges szerepkörrel. Egy egyszerű WebSocket-kapcsolat mindig aktivál egy message eseményt, amikor üzeneteket küld, és mindig a kiszolgáló oldalára támaszkodik az üzenetek feldolgozásához és más műveletek végrehajtásához. Az alprotocol segítségével egy protobuf.webpubsub.azure.v1 jogosult ügyfél csatlakozhat egy csoporthoz a csatlakozási kérelmek használatával, és közvetlenül közzétételi kérések használatával közzéteheti az üzeneteket egy csoportban. Az ügyfél különböző felsőbb rétegbeli eseménykezelőkhöz is irányíthat üzeneteket az eseménykérések használatával annak az eseménynek az testreszabásához, amelyhez az üzenet tartozik.

Megjegyzés

A Web PubSub szolgáltatás jelenleg csak a proto3-at támogatja.

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.

Kérelmek

Minden kérésüzenet a következő protobuf formátumnak felel meg:

syntax = "proto3";

import "google/protobuf/any.proto";

message UpstreamMessage {
    oneof message {
        SendToGroupMessage send_to_group_message = 1;
        EventMessage event_message = 5;
        JoinGroupMessage join_group_message = 6;
        LeaveGroupMessage leave_group_message = 7;
        SequenceAckMessage sequence_ack_message = 8;
        PingMessage ping_message = 9;
    }

    message SendToGroupMessage {
        string group = 1;
        optional uint64 ack_id = 2;
        MessageData data = 3;
    }

    message EventMessage {
        string event = 1;
        MessageData data = 2;
        optional uint64 ack_id = 3;
    }
    
    message JoinGroupMessage {
        string group = 1;
        optional uint64 ack_id = 2;
    }

    message LeaveGroupMessage {
        string group = 1;
        optional uint64 ack_id = 2;
    }

    message PingMessage {
    }
}

message MessageData {
    oneof data {
        string text_data = 1;
        bytes binary_data = 2;
        google.protobuf.Any protobuf_data = 3;
    }
}

Csoportok csatlakoztatása

Formátum:

Állítsa be join_group_message.group a csoport nevét.

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. További részletek az AckId és az Ack Response címen találhatók

Csoportok elhagyása

Formátum:

Állítsa be leave_group_message.group a csoport nevét.

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. További részletek az AckId és az Ack Response címen találhatók

Üzenetek közzététele

Formátum:

ackId: Az egyes kérések egyedi identitása. A szolgáltatás egy nem megfelelő válaszüzenetet küld, amely értesíti a kérés folyamateredményét. További részletek az AckId és az Ack Response címen találhatók
dataType: Az adatformátum, amely lehet protobuf, textvagy binary attól függően, hogy a data be MessageData. A fogadó ügyfelek megfelelően dolgozhatják dataType fel a tartalmat.
protobuf: Ha be van állítva send_to_group_message.data.protobuf_data, az implicit dataType az protobuf. protobuf_databármilyen típusú üzenet lehet. Minden más ügyfél kap egy protobuf kódolású bináris fájlt, amelyet a protobuf SDK deszerializálhat. A csak szöveges tartalmakat támogató ügyfelek (például json.webpubsub.azure.v1) Base64 kódolású bináris fájlokat kapnak.
text: Ha be van állítva send_to_group_message.data.text_data, az implicit dataType az text. text_data sztringnek kell lennie. Minden más protokollt tartalmazó ügyfél kap egy UTF-8 kódolású sztringet.
binary: Ha be van állítva send_to_group_message.data.binary_data, az implicit dataType az binary. binary_data bájttömbnek kell lennie. Minden más protokollal rendelkező ügyfél kap egy nyers bináris fájlt protobuf kódolás nélkül. A csak szöveges tartalmakat támogató ügyfelek (például json.webpubsub.azure.v1) Base64 kódolású bináris fájlokat kapnak.

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

Állítsa be send_to_group_message.group a következőre group, és állítsa be a következőre send_to_group_message.data.text_data"text data": .

A csoport group protobuf subprotocol-ügyfele megkapja a bináris keretet, és a DownstreamMessage használatával deszerializálhatja azt.

A kapott JSON-alprotocol-ügyfelek group :

{
    "type": "message",
    "from": "group",
    "group": "group",
    "dataType" : "text",
    "data" : "text data"
}

Az egyszerű WebSocket-ügyfelek sztringet grouptext datakapnak.

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

Tegyük fel, hogy egyéni üzenete van:

message MyMessage {
    int32 value = 1;
}

Beállítva send_to_group_message.group a következőre value = 1groupAny.pack(MyMessage): send_to_group_message.data.protobuf_data .

A protobuf subprotocol-ügyfelek group megkapják a bináris keretet, és a DownstreamMessage használatával deszerializálhatják azt.

A beosztott alprojekt-ügyfél group a következőt kapja:

{
    "type": "message",
    "from": "group",
    "group": "G",
    "dataType" : "protobuf",
    "data" : "Ci90eXBlLmdvb2dsZWFwaXMuY29tL2F6dXJlLndlYnB1YnN1Yi5UZXN0TWVzc2FnZRICCAE=" // Base64-encoded bytes
}

Megjegyzés

Az adatok base64 kódolású, deszerializálható protobuf binárisak.

Az alábbi protobuf definíciót használhatja, és deszerializálhatja Any.unpack() :

syntax = "proto3";

message MyMessage {
    int32 value = 1;
}

Az egyszerű WebSocket-ügyfelek group a bináris keretet kapják:

# Show in hexadecimal
0A 2F 74 79 70 65 2E 67 6F 6F 67 6C 65 61 70 69 73 2E 63 6F 6D 2F 61 7A 75 72 65 2E 77 65 62 70 75 62 73 75 62 2E 54 65 73 74 4D 65 73 73 61 67 65 12 02 08 01

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

Állítsa be send_to_group_message.group a következőre group, és állítsa be a következőre send_to_group_message.data.binary_data[1, 2, 3]: .

A csoport group protobuf subprotocol-ügyfele megkapja a bináris keretet, és a DownstreamMessage használatával deszerializálhatja azt.
A csoport group JSON-alprotocol-ügyfele a következőt kapja:
```
{
    "type": "message",
    "from": "group",
    "group": "group",
    "dataType" : "binary",
    "data" : "AQID", // Base64-encoded [1,2,3]
}
```
Mivel a JSON-alprotocol-ügyfél csak a szöveges üzeneteket támogatja, a bináris fájl mindig Base64 kódolású.
Az egyszerű WebSocket-ügyfelek a bináris keretben group kapják meg a bináris adatokat:
```
# Show in hexadecimal
01 02 03
```

Egyéni események küldése

A beállított értéktől függően van egy implicit dataType, amely lehet protobuf, textvagy binary.dataType A fogadó ügyfelek megfelelően kezelhetik dataType a tartalmat.

protobuf: Ha be van állítva event_message.data.protobuf_data, az implicit dataType az protobuf. Az protobuf_data érték bármilyen támogatott protobuf típus lehet. Az eseménykezelő megkapja a protobuf kódolású bináris fájlt, amelyet bármely protobuf SDK deszerializálhat.
text: Ha be van állítva event_message.data.text_data, az implicit dataType az text. Az text_data értéknek sztringnek kell lennie. Az eseménykezelő egy UTF-8 kódolású sztringet kap.
binary: Ha be van állítva event_message.data.binary_data, az implicit dataType az binary. Az binary_data értéknek bájttömbnek kell lennie. Az eseménykezelő megkapja a nyers bináris keretet.

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

Állítsa a event_message.data.text_data elemet "text data" értékre.

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

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 helyetext/plaindataType=text.

2. eset: Protobuf-adatokkal rendelkező esemény küldése

Tegyük fel, hogy a következő ügyfélüzenetet kapta:

message MyMessage {
    int32 value = 1;
}

Beállítás a következőre:event_message.data.protobuf_dataany.pack(MyMessage)value = 1

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

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>

// Just show in hexadecimal; read it as binary
0A 2F 74 79 70 65 2E 67 6F 6F 67 6C 65 61 70 69 73 2E 63 6F 6D 2F 61 7A 75 72 65 2E 77 65 62 70 75 62 73 75 62 2E 54 65 73 74 4D 65 73 73 61 67 65 12 02 08 01

A Content-Type CloudEvents HTTP-kérésének helyeapplication/x-protobufdataType=protobuf.

Az adatok érvényes protobuf bináris fájlok. Az alábbiakat proto használhatja, és any.unpack() deszerializálhatja:

syntax = "proto3";

message MyMessage {
    int32 value = 1;
}

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

Állítsa a send_to_group_message.binary_data elemet [1, 2, 3] értékre.

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

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>

// Just show in hexadecimal; you need to read it as binary
01 02 03

Ehhez dataType=binarya Content-Type CloudEvents HTTP-kérése a következő application/octet-stream. A WebSocket-keret text lehet szöveges üzenetkeretek vagy UTF-8 kódolású bináris fájlok az üzenetkeretekhez binary .

A szolgáltatás elutasítja az ügyfelet, ha az üzenet nem felel meg az előírt formátumnak.

Ping

Az ügyfél küldhet egy üzenetet PingMessage a szolgáltatásnak, amely lehetővé teszi, hogy a Web PubSub szolgáltatás észlelje az ügyfél élettartamát.

Válaszok

Minden válaszüzenet a következő protobuf formátumot követi:

message DownstreamMessage {
    oneof message {
        AckMessage ack_message = 1;
        DataMessage data_message = 2;
        SystemMessage system_message = 3;
        PongMessage pong_message = 4;
    }
    
    message AckMessage {
        uint64 ack_id = 1;
        bool success = 2;
        optional ErrorMessage error = 3;
    
        message ErrorMessage {
            string name = 1;
            string message = 2;
        }
    }

    message DataMessage {
        string from = 1;
        optional string group = 2;
        MessageData data = 3;
    }

    message SystemMessage {
        oneof message {
            ConnectedMessage connected_message = 1;
            DisconnectedMessage disconnected_message = 2;
        }
    
        message ConnectedMessage {
            string connection_id = 1;
            string user_id = 2;
        }

        message DisconnectedMessage {
            string reason = 2;
        }
    }

    message PongMessage {
    }
}

Az ügyfél által fogadott üzenetek a következő három típus bármelyikében lehetnek: ack, messagesystem vagy pong.

Ack-válasz

Ha a kérés tartalmaz ackId, a szolgáltatás a kérésre adott válaszát adja vissza. Az ügyfél-implementációnak kezelnie kell ezt a nem megfelelő mechanizmust, beleértve a következőket:

Várakozás a műveletre adott válaszra asyncawait .
Időtúllépéses ellenőrzés, ha a válasz nem érkezik meg egy adott időszakban.

Az ügyfél implementációjának mindig először ellenőriznie kell, hogy az állapot vagy falsea successtrue . Ha az success állapot az false, az ügyfél beolvashatja a tulajdonságból a error hiba részleteit.

Üzenet válasza

Az ügyfelek fogadhatnak olyan csoportból közzétett üzeneteket, amelyekhez az ügyfél csatlakozott. Vagy fogadhatnak üzeneteket a kiszolgálófelügyeleti szerepkörből, amikor a kiszolgáló üzeneteket küld egy adott ügyfélnek vagy egy adott felhasználónak.

A következő forgatókönyvekben mindig megjelenik egy DownstreamMessage.DataMessage üzenet:

Ha az üzenet egy csoportból származik, from akkor a következő: group. Ha az üzenet a kiszolgálóról származik, from akkor a következő: server.
Ha az üzenet egy csoportból származik, group az a csoport neve.

A feladó dataType a következő üzenetek egyikét fogja küldeni:

Ha dataType igen text, használja a következőt message_response_message.data.text_data:
Ha dataType igen binary, használja a következőt message_response_message.data.binary_data:
Ha dataType igen protobuf, használja a következőt message_response_message.data.protobuf_data:
Ha dataType igen json, használja message_response_message.data.text_data, és a tartalom szerializált JSON-sztring.

Rendszer válasza

A Web PubSub szolgáltatás rendszerfüggő válaszokat is küldhet az ügyfélnek.

Csatlakoztatva

Amikor az ügyfél csatlakozik a szolgáltatáshoz, egy DownstreamMessage.SystemMessage.ConnectedMessage üzenet érkezik.

Leválasztva

Amikor a kiszolgáló bezárja a kapcsolatot, vagy a szolgáltatás elutasítja az ügyfelet DownstreamMessage.SystemMessage.DisconnectedMessage , üzenetet kap.