Het door Azure Web PubSub ondersteunde protobuf WebSocket-subprotocol

Artikel
10/26/2023

In dit document wordt het subprotocol protobuf.webpubsub.azure.v1beschreven.

Wanneer een client dit subprotocol gebruikt, worden zowel de uitgaande als de binnenkomende gegevensframes naar verwachting protocolbuffers (protobuf) nettoladingen.

Overzicht

Subprotocol protobuf.webpubsub.azure.v1 stelt de client in staat om rechtstreeks een publish-subscribe (PubSub) uit te voeren in plaats van een retour naar de upstream-server uit te voeren. De WebSocket-verbinding met het protobuf.webpubsub.azure.v1 subprotocol wordt een PubSub WebSocket-client genoemd.

In JavaScript kunt u bijvoorbeeld een PubSub WebSocket-client maken met het protobuf-subprotocol met behulp van:

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

Voor een eenvoudige WebSocket-client heeft de server de benodigde rol voor het verwerken van gebeurtenissen van clients. Een eenvoudige WebSocket-verbinding activeert altijd een message gebeurtenis wanneer berichten worden verzonden en is altijd afhankelijk van de serverzijde om berichten te verwerken en andere bewerkingen uit te voeren. Met behulp van het protobuf.webpubsub.azure.v1 subprotocol kan een geautoriseerde client lid worden van een groep door join-aanvragen te gebruiken en berichten rechtstreeks naar een groep te publiceren met behulp van publicatieaanvragen . De client kan ook berichten doorsturen naar verschillende upstream gebeurtenis-handlers met behulp van gebeurtenisaanvragen om de gebeurtenis waartoe het bericht behoort aan te passen.

Notitie

Momenteel ondersteunt de Web PubSub-service alleen proto3.

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

Alle aanvraagberichten voldoen aan de volgende protobuf-indeling:

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

Deelnemen aan groepen

Indeling:

Stel join_group_message.group deze in op de groepsnaam.

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. Meer informatie vindt u op AckId en Ack Response

Groepen verlaten

Indeling:

Stel leave_group_message.group deze in op de groepsnaam.

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. Meer informatie vindt u op AckId en Ack Response

Berichten publiceren

Indeling:

ackId: De unieke identiteit van elke aanvraag. De service verzendt een ack-antwoordbericht om het procesresultaat van de aanvraag op de hoogte te stellen. Meer informatie vindt u op AckId en Ack Response
dataType: De gegevensindeling, die kan zijn protobuf, textof binary afhankelijk van de data in MessageData. De ontvangende clients kunnen de dataType inhoud correct verwerken.
protobuf: Wanneer u insteltsend_to_group_message.data.protobuf_data, is de implicietedataType.protobuf protobuf_data kan van het type Willekeurig bericht zijn. Alle andere clients ontvangen een protobuf-gecodeerd binair bestand, dat kan worden gedeserialiseerd door de protobuf SDK. Clients die alleen inhoud op basis van tekst ondersteunen (bijvoorbeeld json.webpubsub.azure.v1) ontvangen een binair bestand met Base64-codering.
text: Wanneer u insteltsend_to_group_message.data.text_data, is de implicietedataType.text text_data moet een tekenreeks zijn. Alle clients met andere protocollen ontvangen een UTF-8-gecodeerde tekenreeks.
binary: Wanneer u insteltsend_to_group_message.data.binary_data, is de implicietedataType.binary binary_data moet een bytematrix zijn. Alle clients met andere protocollen ontvangen een onbewerkt binair bestand zonder protobuf-codering. Clients die alleen inhoud op basis van tekst ondersteunen (bijvoorbeeld json.webpubsub.azure.v1) ontvangen een binair bestand met Base64-codering.

Case 1: Tekstgegevens publiceren

Ingesteld send_to_group_message.group op group, en ingesteld op "text data"send_to_group_message.data.text_data .

De protobuf-subprotocolclient in groep group ontvangt het binaire frame en kan DownstreamMessage gebruiken om het te deserialiseren.

De JSON-subprotocolclients ontvangen group :

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

De eenvoudige WebSocket-clients in group de ontvangsttekenreeks text data.

Case 2: Protobuf-gegevens publiceren

Stel dat u een aangepast bericht hebt:

message MyMessage {
    int32 value = 1;
}

Ingesteld send_to_group_message.group op group en send_to_group_message.data.protobuf_data naar Any.pack(MyMessage) met value = 1.

De protobuf-subprotocolclients ontvangen group het binaire frame en kunnen DownstreamMessage gebruiken om het te deserialiseren.

De subprotocolclient ontvangt group :

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

Notitie

De gegevens zijn een met Base64 gecodeerde, deserializeable protobuf binary.

U kunt de volgende protobuf-definitie gebruiken en gebruiken Any.unpack() om deze te deserialiseren:

syntax = "proto3";

message MyMessage {
    int32 value = 1;
}

De eenvoudige WebSocket-clients ontvangen group het binaire frame:

# 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

Case 3: Binaire gegevens publiceren

Ingesteld send_to_group_message.group op group, en ingesteld op [1, 2, 3]send_to_group_message.data.binary_data .

De protobuf-subprotocolclient in groep group ontvangt het binaire frame en kan DownstreamMessage gebruiken om het te deserialiseren.
De JSON-subprotocolclient in de groep group ontvangt:
```
{
    "type": "message",
    "from": "group",
    "group": "group",
    "dataType" : "binary",
    "data" : "AQID", // Base64-encoded [1,2,3]
}
```
Omdat de JSON-subprotocolclient alleen op tekst gebaseerde berichten ondersteunt, wordt het binaire bestand altijd Base64-gecodeerd.
De eenvoudige WebSocket-clients ontvangen group de binaire gegevens in het binaire frame:
```
# Show in hexadecimal
01 02 03
```

Aangepaste gebeurtenissen verzenden

Er is een impliciete dataType, die kan zijn protobuf, textof binary, afhankelijk van de dataType door u ingestelde set. De ontvangerclients kunnen de dataType inhoud correct verwerken.

protobuf: Wanneer u insteltevent_message.data.protobuf_data, is de implicietedataType.protobuf De protobuf_data waarde kan elk ondersteund protobuf-type zijn. De gebeurtenis-handler ontvangt het protobuf-gecodeerde binaire bestand, dat kan worden gedeserialiseerd door elke protobuf SDK.
text: Wanneer u insteltevent_message.data.text_data, is de implicietedataType.text De text_data waarde moet een tekenreeks zijn. De gebeurtenis-handler ontvangt een UTF-8-gecodeerde tekenreeks.
binary: Wanneer u insteltevent_message.data.binary_data, is de implicietedataType.binary De binary_data waarde moet een bytematrix zijn. De gebeurtenishandler ontvangt het onbewerkte binaire frame.

Case 1: Een gebeurtenis met tekstgegevens verzenden

Stel event_message.data.text_data in op "text data".

De upstream-gebeurtenis-handler ontvangt een aanvraag die vergelijkbaar is 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 voor de CloudEvents HTTP-aanvraag is text/plain, waar=dataTypetext .

Case 2: Een gebeurtenis met protobuf-gegevens verzenden

Stel dat u het volgende klantbericht hebt ontvangen:

message MyMessage {
    int32 value = 1;
}

Ingesteld event_message.data.protobuf_data op any.pack(MyMessage) met value = 1

De upstream-gebeurtenis-handler ontvangt een aanvraag die vergelijkbaar is 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>

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

De Content-Type voor de CloudEvents HTTP-aanvraag is application/x-protobuf, waar=dataTypeprotobuf .

De gegevens zijn een geldig protobuf binair bestand. U kunt het volgende proto gebruiken en any.unpack() deze deserialiseren:

syntax = "proto3";

message MyMessage {
    int32 value = 1;
}

Case 3: Een gebeurtenis met binaire gegevens verzenden

Stel send_to_group_message.binary_data in op [1, 2, 3].

De upstream-gebeurtenis-handler ontvangt een aanvraag die vergelijkbaar is 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>

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

Voor dataType=binaryde HTTP-aanvraag van CloudEvents is application/octet-streamdatContent-Type. Het WebSocket-frame kan een text indeling hebben voor tekstberichtframes of UTF-8 gecodeerde binaire bestanden voor binary berichtframes.

De service weigert de client als het bericht niet overeenkomt met de voorgeschreven indeling.

Ping

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

Antwoorden

Alle antwoordberichten voldoen aan de volgende protobuf-indeling:

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

Berichten die door de client worden ontvangen, kunnen zich in een van de volgende drie typen bevinden: ack, messageof system pong.

Ack-antwoord

Als de aanvraag bevat ackId, retourneert de service een ack-antwoord voor deze aanvraag. De client-implementatie moet dit ack-mechanisme verwerken, waaronder:

Wachten op het ack-antwoord voor een async await bewerking.
Er is een time-outcontrole wanneer het ack-antwoord gedurende een bepaalde periode niet wordt ontvangen.

De client-implementatie moet altijd eerst controleren om te zien of de success status is true of false. Wanneer de success status is false, kan de client lezen uit de error eigenschap voor foutdetails.

Berichtantwoord

Clients kunnen berichten ontvangen die zijn gepubliceerd vanuit een groep waaraan de client is toegevoegd. Of ze kunnen berichten ontvangen van de serverbeheerfunctie wanneer de server berichten naar een specifieke client of een specifieke gebruiker verzendt.

In de volgende scenario's krijgt u altijd een DownstreamMessage.DataMessage bericht:

Wanneer het bericht afkomstig is van een groep, from is groupdit . Wanneer het bericht afkomstig is van de server, from is serverdit .
Wanneer het bericht afkomstig is van een groep, group is dit de groepsnaam.

De afzender dataType zorgt ervoor dat een van de volgende berichten wordt verzonden:

Als dataType dat het is text, gebruikt message_response_message.data.text_datau .
Als dataType dat het is binary, gebruikt message_response_message.data.binary_datau .
Als dataType dat het is protobuf, gebruikt message_response_message.data.protobuf_datau .
Als dataType dat het is json, gebruikt message_response_message.data.text_dataen de inhoud een geserialiseerde JSON-tekenreeks is.