O subprotocolo WebSocket protobuf do Azure Web PubSub suportado

Artigo
10/26/2023

Este documento descreve o subprotocolo protobuf.webpubsub.azure.v1.

Quando um cliente está usando esse subprotocolo, espera-se que os quadros de dados de entrada e de saída sejam cargas úteis de buffers de protocolo (protobuf).

Descrição geral

O subprotocolo protobuf.webpubsub.azure.v1 permite que o cliente faça uma publicação-assinatura (PubSub) diretamente em vez de fazer uma viagem de ida e volta para o servidor upstream. A conexão WebSocket com o protobuf.webpubsub.azure.v1 subprotocolo é chamada de cliente PubSub WebSocket.

Por exemplo, em JavaScript, você pode criar um cliente PubSub WebSocket com o subprotocolo protobuf usando:

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

Para um cliente WebSocket simples, o servidor tem a função necessária de manipular eventos de clientes. Uma conexão WebSocket simples sempre dispara um message evento quando envia mensagens e sempre depende do lado do servidor para processar mensagens e fazer outras operações. Com a ajuda do subprotocolo, um cliente autorizado pode ingressar em um grupo usando solicitações de associação e publicar mensagens em um grupo usando solicitações de protobuf.webpubsub.azure.v1 publicação diretamente. O cliente também pode rotear mensagens para vários manipuladores de eventos upstream usando solicitações de evento para personalizar o evento ao qual a mensagem pertence.

Nota

Atualmente, o serviço Web PubSub suporta apenas proto3.

Permissões

Um cliente PubSub WebSocket só pode publicar para outros clientes quando é autorizado. Os roles atribuídos ao cliente determinam as permissões concedidas ao cliente:

Role	Permissão
Não especificado	O cliente pode enviar solicitações de eventos.
`webpubsub.joinLeaveGroup`	O cliente pode entrar/sair de qualquer grupo.
`webpubsub.sendToGroup`	O cliente pode publicar mensagens em qualquer grupo.
`webpubsub.joinLeaveGroup.<group>`	O cliente pode entrar/sair do grupo `<group>`.
`webpubsub.sendToGroup.<group>`	O cliente pode publicar mensagens no grupo `<group>`.

O servidor pode conceder ou revogar dinamicamente permissões de cliente por meio de APIs REST ou SDKs de servidor.

Pedidos do

Todas as mensagens de solicitação aderem ao seguinte formato 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;
    }
}

Junte-se a grupos

Formato:

Defina join_group_message.group como o nome do grupo.

ackId é a identidade de cada pedido e deve ser única. O serviço envia uma mensagem de resposta ack para notificar o resultado do processo da solicitação. Mais detalhes podem ser encontrados em AckId e Ack Response

Sair dos grupos

Formato:

Defina leave_group_message.group como o nome do grupo.

ackId é a identidade de cada pedido e deve ser única. O serviço envia uma mensagem de resposta ack para notificar o resultado do processo da solicitação. Mais detalhes podem ser encontrados em AckId e Ack Response

Publicar mensagens

Formato:

ackId: A identidade única de cada pedido. O serviço envia uma mensagem de resposta ack para notificar o resultado do processo da solicitação. Mais detalhes podem ser encontrados em AckId e Ack Response
dataType: O formato de dados, que pode ser protobuf, textou binary dependendo do data in MessageData. Os clientes recetores podem usar dataType para processar corretamente o conteúdo.
protobuf: Quando você define send_to_group_message.data.protobuf_data, o implícito dataType é protobuf. protobuf_data pode ser do tipo Qualquer mensagem. Todos os outros clientes recebem um binário codificado por protobuf, que pode ser desserializado pelo SDK do protobuf. Os clientes que suportam apenas conteúdo baseado em texto (por exemplo, json.webpubsub.azure.v1) recebem um binário codificado em Base64.
text: Quando você define send_to_group_message.data.text_data, o implícito dataType é text. text_data deve ser uma cadeia de caracteres. Todos os clientes com outros protocolos recebem uma cadeia de caracteres codificada em UTF-8.
binary: Quando você define send_to_group_message.data.binary_data, o implícito dataType é binary. binary_data deve ser uma matriz de bytes. Todos os clientes com outros protocolos recebem um binário bruto sem codificação protobuf. Os clientes que suportam apenas conteúdo baseado em texto (por exemplo, json.webpubsub.azure.v1) recebem um binário codificado em Base64.

Caso 1: Publicar dados de texto

Defina send_to_group_message.group como group, e defina send_to_group_message.data.text_data como "text data".

O cliente de subprotocolo protobuf em grupo group recebe o quadro binário e pode usar DownstreamMessage para desserializá-lo.

Os clientes do subprotocolo JSON recebem group :

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

Os clientes WebSocket simples na group cadeia de caracteres text datade recebimento .

Caso 2: Publicar dados protobuf

Vamos supor que você tenha uma mensagem personalizada:

message MyMessage {
    int32 value = 1;
}

Defina send_to_group_message.group como group e send_to_group_message.data.protobuf_data para Any.pack(MyMessage) com value = 1.

Os clientes do subprotocolo protobuf recebem group o quadro binário e podem usar DownstreamMessage para desserializá-lo.

O cliente de subprotocolo em group recebe:

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

Nota

Os dados são um binário protobuf desserializável codificado em Base64.

Você pode usar a seguinte definição de protobuf e usá-la Any.unpack() para desserializá-la:

syntax = "proto3";

message MyMessage {
    int32 value = 1;
}

Os clientes WebSocket simples em group receber o quadro binário:

# 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

Caso 3: Publicar dados binários

Defina send_to_group_message.group como group, e defina send_to_group_message.data.binary_data como [1, 2, 3].

O cliente de subprotocolo protobuf em grupo group recebe o quadro binário e pode usar DownstreamMessage para desserializá-lo.
O cliente de subprotocolo JSON no grupo group recebe:
```
{
    "type": "message",
    "from": "group",
    "group": "group",
    "dataType" : "binary",
    "data" : "AQID", // Base64-encoded [1,2,3]
}
```
Como o cliente de subprotocolo JSON suporta apenas mensagens baseadas em texto, o binário é sempre codificado em Base64.
Os clientes WebSocket simples em group receber os dados binários no quadro binário:
```
# Show in hexadecimal
01 02 03
```

Enviar eventos personalizados

Há um implícito dataType, que pode ser protobuf, text, ou binary, dependendo do dataType seu conjunto. Os clientes recetores podem usar dataType para lidar com o conteúdo corretamente.

protobuf: Quando você define event_message.data.protobuf_data, o implícito dataType é protobuf. O protobuf_data valor pode ser qualquer tipo de protobuf suportado. O manipulador de eventos recebe o binário codificado por protobuf, que pode ser desserializado por qualquer SDK de protobuf.
text: Quando você define event_message.data.text_data, o implícito dataType é text. O text_data valor deve ser uma cadeia de caracteres. O manipulador de eventos recebe uma cadeia de caracteres codificada em UTF-8.
binary: Quando você define event_message.data.binary_data, o implícito dataType é binary. O binary_data valor deve ser uma matriz de bytes. O manipulador de eventos recebe o quadro binário bruto.

Caso 1: Enviar um evento com dados de texto

Defina event_message.data.text_data como "text data".

O manipulador de eventos upstream recebe uma solicitação semelhante a:

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

O Content-Type para a solicitação HTTP do CloudEvents é text/plain, onde dataType=text.

Caso 2: Enviar um evento com dados protobuf

Suponha que você recebeu a seguinte mensagem de cliente:

message MyMessage {
    int32 value = 1;
}

Definir event_message.data.protobuf_data como any.pack(MyMessage) com value = 1

O manipulador de eventos upstream recebe uma solicitação semelhante a:

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

O Content-Type para a solicitação HTTP do CloudEvents é application/x-protobuf, onde dataType=protobuf.

Os dados são um binário protobuf válido. Você pode usar o seguinte proto e any.unpack() desserializá-lo:

syntax = "proto3";

message MyMessage {
    int32 value = 1;
}

Caso 3: Enviar um evento com dados binários

Defina send_to_group_message.binary_data como [1, 2, 3].

O manipulador de eventos upstream recebe uma solicitação semelhante a:

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

Para dataType=binary, a Content-Type solicitação HTTP do CloudEvents é application/octet-stream. O quadro WebSocket pode estar em formato para quadros de mensagem de texto ou binários codificados em text UTF-8 para binary quadros de mensagem.

O serviço recusa o cliente se a mensagem não corresponder ao formato prescrito.

Respostas

Todas as mensagens de resposta aderem ao seguinte formato 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;
        }
    }
}

As mensagens recebidas pelo cliente podem ser de três tipos: ack, message, ou system.

Resposta Ack

Se a solicitação contiver ackId, o serviço retornará uma resposta ack para essa solicitação. A implementação do cliente deve lidar com esse mecanismo, incluindo:

Aguardando a resposta ack para uma async await operação.
Ter uma verificação de tempo limite quando a resposta ack não é recebida durante um determinado período.

A implementação do cliente deve sempre verificar primeiro se o success status é true ou false. Quando o success status é false, o cliente pode ler a error partir da propriedade para obter detalhes do erro.

Resposta à mensagem

Os clientes podem receber mensagens publicadas de um grupo ao qual o cliente aderiu. Ou eles podem receber mensagens da função de gerenciamento de servidor quando o servidor envia mensagens para um cliente específico ou um usuário específico.

Você sempre receberá uma DownstreamMessage.DataMessage mensagem nos seguintes cenários:

Quando a mensagem é de um grupo, from é group. Quando a mensagem é do servidor, from é server.
Quando a mensagem é de um grupo, group é o nome do grupo.

O remetente dataType fará com que uma das seguintes mensagens seja enviada:

Se dataType for text, use message_response_message.data.text_data.
Se dataType for binary, use message_response_message.data.binary_data.
Se dataType for protobuf, use message_response_message.data.protobuf_data.
Se dataType for json, use message_response_message.data.text_data, e o conteúdo for uma cadeia de caracteres JSON serializada.