Podsložka protobuf WebSocket podporovaná podsítě Azure Web PubSub

Článek
10/26/2023

Tento dokument popisuje dílčí souhrn protobuf.webpubsub.azure.v1.

Pokud klient používá tento dílčíprotokol, očekává se, že odchozí i příchozí datové rámce budou datové části vyrovnávací paměti protokolu (protobuf).

Přehled

Subprotocol protobuf.webpubsub.azure.v1 umožňuje klientovi provést publikování-odběr (PubSub) přímo místo toho, aby se do upstreamového serveru zaokrouhlil. Připojení WebSocket s dílčím protokolem protobuf.webpubsub.azure.v1 se nazývá klient PubSub WebSocket.

Například v JavaScriptu můžete vytvořit klienta PubSub WebSocket s parametrem protobuf subprotocol pomocí:

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

Pro jednoduchého klienta WebSocket má server nezbytnou roli zpracování událostí z klientů. Jednoduché připojení WebSocket vždy aktivuje message událost při odesílání zpráv a vždy spoléhá na serverovou stranu ke zpracování zpráv a provádění dalších operací. S pomocí protobuf.webpubsub.azure.v1 subprotocolu se autorizovaný klient může připojit ke skupině pomocí žádostí o připojení a publikovat zprávy do skupiny přímo pomocí žádostí o publikování. Klient může také směrovat zprávy do různých upstreamových obslužných rutin událostí pomocí žádostí o události k přizpůsobení události , do které zpráva patří.

Poznámka:

Služba Web PubSub v současné době podporuje pouze proto3.

Oprávnění

Klient PubSub WebSocket může publikovat pouze do jiných klientů, pokud je autorizovaný. Přiřazené roles klientovi určují oprávnění udělená klientovi:

Role	Oprávnění
Neurčeno	Klient může odesílat žádosti o události.
`webpubsub.joinLeaveGroup`	Klient se může připojit nebo opustit libovolnou skupinu.
`webpubsub.sendToGroup`	Klient může publikovat zprávy do libovolné skupiny.
`webpubsub.joinLeaveGroup.<group>`	Klient se může ke skupině `<group>`připojit nebo ji opustit .
`webpubsub.sendToGroup.<group>`	Klient může publikovat zprávy do skupiny `<group>`.

Server může dynamicky udělovat nebo odvolávat klientská oprávnění prostřednictvím rozhraní REST API nebo sad SDK serveru.

Žádosti

Všechny zprávy požadavku odpovídají následujícímu formátu protobuf:

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

    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 MessageData {
    oneof data {
        string text_data = 1;
        bytes binary_data = 2;
        google.protobuf.Any protobuf_data = 3;
    }
}

Připojení ke skupinám

Formát:

Nastavte join_group_message.group název skupiny.

ackId je identita každého požadavku a měla by být jedinečná. Služba odešle zprávu odpovědi ack, která oznámí výsledek procesu požadavku. Další podrobnosti najdete v AckId a odpovědi Ack

Opustit skupiny

Formát:

Nastavte leave_group_message.group název skupiny.

ackId je identita každého požadavku a měla by být jedinečná. Služba odešle zprávu odpovědi ack, která oznámí výsledek procesu požadavku. Další podrobnosti najdete v AckId a odpovědi Ack

Publikování zpráv

Formát:

ackId: Jedinečná identita každého požadavku. Služba odešle zprávu odpovědi ack, která oznámí výsledek procesu požadavku. Další podrobnosti najdete v AckId a odpovědi Ack
dataType: Formát dat, který může být , nebo v závislosti na in data MessageData.binary textprotobuf Přijímající klienti můžou obsah dataType správně zpracovat.
protobuf: Když nastavíte send_to_group_message.data.protobuf_data, implicitní dataType je protobuf. protobuf_data může být typu Libovolná zpráva. Všichni ostatní klienti obdrží binární soubor s kódováním protobuf, který může být deserializován sadou PROTObuf SDK. Klienti, kteří podporují pouze textový obsah (například json.webpubsub.azure.v1) obdrží binární soubor s kódováním Base64.
text: Když nastavíte send_to_group_message.data.text_data, implicitní dataType je text. text_data by měl být řetězec. Všichni klienti s jinými protokoly přijímají řetězec s kódováním UTF-8.
binary: Když nastavíte send_to_group_message.data.binary_data, implicitní dataType je binary. binary_data by měla být bajtová matice. Všichni klienti s jinými protokoly přijímají nezpracovaný binární soubor bez kódování protobuf. Klienti, kteří podporují pouze textový obsah (například json.webpubsub.azure.v1) obdrží binární soubor s kódováním Base64.

Případ 1: Publikování textových dat

Nastavte send_to_group_message.group na grouphodnotu a nastavte send_to_group_message.data.text_data na "text data"hodnotu .

Protobuf subprotocol klient ve skupině group obdrží binární rámec a může použít DownstreamMessage k deserializaci.

Klienti subprotocol JSON v group příjmu:

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

Jednoduché klienty WebSocket v group příjmovém řetězci text data.

Případ 2: Publikování dat protobuf

Předpokládejme, že máte vlastní zprávu:

message MyMessage {
    int32 value = 1;
}

Nastavte send_to_group_message.group na hodnotu a send_to_group_message.data.protobuf_data na hodnotu Any.pack(MyMessage) s parametrem value = 1group .

Protobuf subprotocol klienti v group příjmu binární rámec a mohou použít DownstreamMessage k deserializaci.

Klient subprotocol přijímá group :

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

Poznámka:

Data jsou binární soubor protobuf s kódováním Base64, deserializovatelný.

Můžete použít následující definici protobuf a použít Any.unpack() ji k deserializaci:

syntax = "proto3";

message MyMessage {
    int32 value = 1;
}

Jednoduché klienty Protokolu WebSocket obdrží group binární rámec:

# 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

Případ 3: Publikování binárních dat

Nastavte send_to_group_message.group na grouphodnotu a nastavte send_to_group_message.data.binary_data na [1, 2, 3]hodnotu .

Protobuf subprotocol klient ve skupině group obdrží binární rámec a může použít DownstreamMessage k deserializaci.
Klient subprotocol JSON ve skupině group přijímá:
```
{
    "type": "message",
    "from": "group",
    "group": "group",
    "dataType" : "binary",
    "data" : "AQID", // Base64-encoded [1,2,3]
}
```
Vzhledem k tomu, že klient subprotocol JSON podporuje pouze zasílání textových zpráv, binární soubor je vždy kódován kódováním Base64.
Jednoduché klienty Protokolu WebSocket obdrží group binární data v binárním rámci:
```
# Show in hexadecimal
01 02 03
```

Odesílání vlastních událostí

V závislosti na vámi nastaveném objektu je implicitní dataType, který může být protobuftext, nebo binary.dataType Klienti příjemce můžou použít dataType ke správnému zpracování obsahu.

protobuf: Když nastavíte event_message.data.protobuf_data, implicitní dataType je protobuf. Hodnota protobuf_data může být libovolný podporovaný typ protobuf. Obslužná rutina události obdrží binární soubor s kódováním protobuf, který může být deserializován libovolnou sadou PROTObuf SDK.
text: Když nastavíte event_message.data.text_data, implicitní dataType je text. Hodnota text_data by měla být řetězec. Obslužná rutina události obdrží řetězec s kódováním UTF-8.
binary: Když nastavíte event_message.data.binary_data, implicitní dataType je binary. Hodnota binary_data by měla být pole bajtů. Obslužná rutina události obdrží nezpracovaný binární rámec.

Případ 1: Odeslání události s textovými daty

Nastavte event_message.data.text_data na hodnotu "text data".

Obslužná rutina upstreamové události obdrží požadavek podobný následujícímu:

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

Požadavek Content-Type HTTP CloudEvents je text/plain, kde=dataTypetext .

Případ 2: Odeslání události s daty protobuf

Předpokládejme, že jste obdrželi následující zprávu zákazníka:

message MyMessage {
    int32 value = 1;
}

Nastavit event_message.data.protobuf_data na any.pack(MyMessage)value = 1

Obslužná rutina upstreamové události obdrží požadavek podobný hledanému:

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

Požadavek Content-Type HTTP CloudEvents je application/x-protobuf, kde=dataTypeprotobuf .

Data jsou platným binárním souborem protobuf. Můžete použít následující proto a any.unpack() deserializovat:

syntax = "proto3";

message MyMessage {
    int32 value = 1;
}

Případ 3: Odeslání události s binárními daty

Nastavte send_to_group_message.binary_data na hodnotu [1, 2, 3].

Obslužná rutina upstreamové události obdrží požadavek podobný následujícímu:

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

V dataType=binarypřípadě požadavku Content-Type HTTP CloudEvents je application/octet-stream. Rámeček WebSocket může být ve text formátu pro rámečky textových zpráv nebo binární soubory s kódováním UTF-8 pro binary rámečky zpráv.

Služba odmítne klienta, pokud zpráva neodpovídá předepsanému formátu.

Odpovědi

Všechny zprávy odpovědi odpovídají následujícímu formátu protobuf:

message DownstreamMessage {
    oneof message {
        AckMessage ack_message = 1;
        DataMessage data_message = 2;
        SystemMessage system_message = 3;
    }
    
    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;
        }
    }
}

Zprávy přijaté klientem mohou být v libovolném ze tří typů: ack, messagenebo system.

Odpověď Ack

Pokud požadavek obsahuje ackId, služba vrátí odpověď ack pro tento požadavek. Implementace klienta by měla tento mechanismus ack zpracovat, včetně následujících:

Čeká se na odpověď ack na async await operaci.
Kontrola časového limitu, kdy se odpověď ack během určitého období nepřijala.

Implementace klienta by měla vždy zkontrolovat, zda success je true stav nebo false. success Pokud je falsestav , klient může číst z error vlastnosti podrobnosti o chybě.

Odpověď na zprávu

Klienti mohou přijímat zprávy publikované ze skupiny, ke které se klient připojil. Nebo můžou přijímat zprávy z role správy serveru, když server odesílá zprávy konkrétnímu klientovi nebo konkrétnímu uživateli.

Vždy dostanete DownstreamMessage.DataMessage zprávu v následujících scénářích:

Když je zpráva ze skupiny, from je group. Když je zpráva ze serveru, from je server.
Když je zpráva ze skupiny, group je název skupiny.

Odesílateli dataType se odešle jedna z následujících zpráv:

Pokud dataType je text, použijte message_response_message.data.text_data.
Pokud dataType je binary, použijte message_response_message.data.binary_data.
Pokud dataType je protobuf, použijte message_response_message.data.protobuf_data.
Pokud dataType je json, použití message_response_message.data.text_dataa obsah je serializovaný řetězec JSON.