O subprotocolo WebSocket protobuf com suporte no Azure Web PubSub

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

Quando um cliente está usando esse subprotocolo, os quadros de dados de saída e de entrada são esperados como conteúdo de buffer de protocolo (protobuf).

Visão geral

O subprotocolo protobuf.webpubsub.azure.v1 capacita o cliente a fazer uma publicação/assinatura (PubSub) diretamente, em vez de uma viagem de ida e volta para o servidor upstream. Chamamos a conexão WebSocket com o subprotocolo protobuf.webpubsub.azure.v1 de cliente WebSocket PubSub.

Por exemplo, no JavaScript, você pode criar um cliente WebSocket PubSub 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 lidar com eventos de clientes. Uma conexão WebSocket simples sempre dispara um evento message quando envia mensagens e sempre se baseia no lado do servidor para processar mensagens e realizar outras operações. Com a ajuda do subprotocolo protobuf.webpubsub.azure.v1, um cliente autorizado pode ingressar em um grupo usando solicitações de ingresso e publicar mensagens em um grupo usando publicar solicitações diretamente. O cliente também pode rotear mensagens para diversos manipuladores de eventos de upstream usando as solicitações de eventos a fim de personalizar o evento ao qual a mensagem pertence.

Permissões

Um cliente WebSocket PubSub só pode publicar em outros clientes quando estiver autorizado. O atribuído roles ao cliente determina as permissões concedidas ao cliente:

O servidor pode conceder ou revogar dinamicamente as permissões do cliente pelas APIs REST ou SDKs de servidor.

Requests

Todas as mensagens de solicitação seguem este formato de 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;
        SequenceAckMessage sequence_ack_message = 8;
        PingMessage ping_message = 9;
        StreamDataMessage stream_data_message = 13;
        StreamEndMessage stream_end_message = 14;
    }

    message SendToGroupMessage {
        string group = 1;
        optional uint64 ack_id = 2;
        MessageData data = 3;
        optional bool no_echo = 4;
        StreamStartInfo stream = 7;
    }

    message StreamStartInfo {
        string stream_id = 1;
        optional uint32 idle_timeout_ms = 2;
    }

    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 SequenceAckMessage {
        uint64 sequence_id = 1;
    }

    message PingMessage {
    }

    message StreamDataMessage {
        string stream_id = 1;
        optional uint64 stream_sequence_id = 2;
        MessageData data = 3;
    }

    message StreamEndMessage {
        string stream_id = 1;
        optional StreamEndError error = 2;

        message StreamEndError {
            optional string message = 1;
            optional string user_error_code = 2;
        }
    }
}

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

Ingressar grupos

Formato:

Defina join_group_message.group como o nome do grupo.

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

Sair dos grupos

Formato:

Defina leave_group_message.group como o nome do grupo.

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

Publicar mensagens

Formato:

• ackId: a identidade exclusiva de cada solicitação. O serviço envia uma mensagem de resposta ack para notificar o resultado do processo da solicitação. Mais detalhes podem ser encontrados em Resposta AckId e Ack

• dataType: o formato de dados, que pode ser protobuf, text ou binary dependendo do data em MessageData. Os clientes receptores podem usar dataType para processarem o conteúdo corretamente.

• protobuf: quando você define send_to_group_message.data.protobuf_data, o implícito dataType é protobuf. protobuf_data pode ser do tipo de mensagem Qualquer. Todos os outros clientes receberão um binário codificado em protobuf que pode ser desserializado pelo SDK do protobuf. Os clientes que dão suporte apenas ao 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 receberão 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 byte. Todos os clientes com outros protocolos receberão um binário bruto sem codificação de protobuf. Os clientes que dão suporte apenas ao 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 send_to_group_message.data.text_data como "text data".

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

• Os clientes do subprotocolo JSON em group recebem:

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

• Os clientes WebSocket simples em group recebem text data da cadeia de caracteres.

Caso 2: publicar dados de protobuf

Digamos 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 como Any.pack(MyMessage) com value = 1.

• Os clientes do subprotocolo protobuf em group recebem 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
  }
  

  Observação

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

Você pode usar a seguinte definição de protobuf e Any.unpack() para desserializar:

syntax = "proto3";

message MyMessage {
    int32 value = 1;
}

• Os clientes WebSocket simples em group recebem 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 send_to_group_message.data.binary_data como [1, 2, 3].

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

• O cliente do subprotocolo JSON do grupo group recebe:

  {
      "type": "message",
      "from": "group",
      "group": "group",
      "dataType" : "binary",
      "data" : "AQID", // Base64-encoded [1,2,3]
  }
  

  Como o cliente do subprotocolo JSON dá suporte apenas a mensagens baseadas em texto, o binário é sempre codificado em Base64.

• Os clientes WebSocket simples em group recebem os dados binários no quadro binário:

  # Show in hexadecimal
  01 02 03
  

Iniciar a transmissão de mensagens

Para iniciar uma transmissão em grupo, defina send_to_group_message.group para o grupo alvo e defina send_to_group_message.stream para uma StreamStartInfo mensagem. Uma solicitação de início de stream não configura send_to_group_message.data nem send_to_group_message.ack_id.

• send_to_group_message.stream.stream_id é o identificador do fluxo lógico. Deve ser uma string não vazia e deve ser única entre os fluxos ativos na mesma conexão cliente. Bibliotecas clientes são recomendadas para gerar um valor globalmente único, como um GUID ou UUID.
• send_to_group_message.stream.idle_timeout_ms é opcional. Se especificado, deve ser maior que 0. Se omitido, o padrão do serviço é 300000 milissegundos. O valor é um tempo de espera ocioso, não uma vida útil total do fluxo. Envie dados do fluxo, envie um keep epalive ou encerre o fluxo antes que esse timeout expire, quando o aplicativo precisa manter o stream aberto.
• send_to_group_message.no_echo é opcional. Se configurado como true, as mensagens do stream não são retornadas para a mesma conexão. Se não for definida, o valor padrão será falso.

Quando o fluxo é aceito, o cliente recebe uma resposta de ack do fluxo com expected_sequence_id definido para 1.

Enviar dados em streaming

Para enviar dados de fluxo, defina stream_data_message.stream_id, stream_data_message.stream_sequence_id, e stream_data_message.data.

• stream_data_message.stream_id identifica um fluxo ativo na mesma conexão do cliente.
• stream_data_message.stream_sequence_id é um número uint64 positivo. O primeiro fragmento de dados em um fluxo usa 1, e cada fragmento de dado seguinte para o mesmo stream_id aumenta exatamente 1em .
• stream_data_message.data usa as mesmas MessageData regras de codificação que publicar mensagens.

Para manter um fluxo ativo sem entregar dados aos assinantes, envie stream_data_message apenas stream_id com set.

Encerrar mensagens de streaming

Para encerrar uma transmissão, defina stream_end_message.stream_id.

Para encerrar um fluxo com um erro definido pela aplicação, defina stream_end_message.error.

• stream_end_message.error.message é uma mensagem de erro opcional legível por humanos.
• stream_end_message.error.user_error_code é um código de erro opcional definido pela aplicação.

Quando o fluxo é fechado, o editor recebe uma resposta de stream fechado.

Enviar eventos personalizados

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

• protobuf: quando você define event_message.data.protobuf_data, o implícito dataType é protobuf. O valor protobuf_data pode ser qualquer tipo de protobuf com suporte. O manipulador de eventos recebe um binário codificado em protobuf que pode ser desserializado por qualquer SDK do protobuf.

• text: quando você define event_message.data.text_data, o implícito dataType é text. O valor text_data 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 valor binary_data deve ser uma matriz de bytes. O manipulador de eventos recebe o quadro binário bruto.

Caso 1: enviar um evento com os dados de texto

Definir event_message.data.text_data para "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 da solicitação HTTP do CloudEvents é text/plain, em que dataType=text.

Caso 2: enviar um evento com os dados de 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 da solicitação HTTP do CloudEvents é application/x-protobuf, em que dataType=protobuf.

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

syntax = "proto3";

message MyMessage {
    int32 value = 1;
}

Caso 3: enviar evento com os dados binários

Definir send_to_group_message.binary_data para [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, o Content-Type para a solicitação HTTP CloudEvents é application/octet-stream. O quadro WebSocket pode estar no formato text para os quadros de mensagem de texto ou binários codificados em UTF-8 para quadros de mensagem binary.

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

Ping

O cliente pode enviar um PingMessage para o serviço para permitir que o serviço Web PubSub detecte a atividade do cliente.

Respostas

Todas as mensagens de resposta seguem este formato de protobuf:

message DownstreamMessage {
    oneof message {
        AckMessage ack_message = 1;
        DataMessage data_message = 2;
        SystemMessage system_message = 3;
        PongMessage pong_message = 4;
        StreamAckMessage stream_ack_message = 6;
        StreamNackMessage stream_nack_message = 7;
        StreamClosedMessage stream_closed_message = 8;
    }
    
    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;
        StreamInfo stream = 6;
    }

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

    message StreamAckMessage {
        string stream_id = 1;
        uint64 expected_sequence_id = 2;
    }

    message StreamNackMessage {
        string stream_id = 1;
        string name = 2;
        string message = 3;
        uint64 expected_sequence_id = 4;
    }

    message StreamClosedMessage {
        string stream_id = 1;
        optional StreamClosedError error = 2;

        message StreamClosedError {
            string name = 1;
            string message = 2;
        }
    }
}

message StreamInfo {
    string stream_id = 1;
    uint64 stream_sequence_id = 2;
    optional bool end_of_stream = 3;
    optional StreamError error = 4;

    message StreamError {
        string name = 1;
        string message = 2;
        string user_error_code = 3;
    }
}

Mensagens recebidas pelo cliente podem ser ack, message, system, pong, streamAck, streamNack, ou streamClosed.

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 ack, incluindo:

• Aguardar a resposta ack para uma operação asyncawait.
• Fazer uma verificação de tempo limite quando a resposta ack não é recebida durante determinado período.

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

Resposta da mensagem

Os clientes podem receber mensagens publicadas de um grupo em que o cliente ingressou. Ou podem receber mensagens da função de gerenciamento do servidor quando o servidor envia mensagens para um cliente ou usuário específico.

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

• Quando a mensagem for de um grupo, from será group. Quando a mensagem for do servidor, from será server.
• Quando a mensagem for de um grupo, group será o nome do grupo.

O dataType do remetente 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 será a cadeia de caracteres JSON serializada.

Quando uma mensagem de grupo pertence a um fluxo, DownstreamMessage.DataMessage.stream é definido.

• stream.stream_id é o identificador lógico do fluxo.
• stream.stream_sequence_id é o número de sequência da mensagem no fluxo.
• stream.end_of_stream é opcional. Quando definido para true, a mensagem é a mensagem terminal do fluxo.
• stream.error é opcional e está presente apenas quando o fluxo termina com um erro. user_error_code está presente apenas para UserError.

Resposta de fluxo de água

O serviço envia DownstreamMessage.StreamAckMessage para confirmar dados de fluxo aceitos e para reportar o próximo ID de sequência de fluxo que espera.

• stream_id é o identificador lógico do fluxo.
• expected_sequence_id é o próximo ID de sequência de fluxo que o serviço espera.

Resposta do nack do riacho

O serviço envia DownstreamMessage.StreamNackMessage um erro de fluxo retentável.

• stream_id é o identificador lógico do fluxo.
• expected_sequence_id é o próximo ID de sequência de fluxo que o serviço espera.
• name pode ser InvalidSequenceId ou TransientError.
• message contém detalhes de erro.

Resposta fechada por fluxo

O serviço envia DownstreamMessage.StreamClosedMessage quando o stream do lado da editora está fechado.

• stream_id é o identificador lógico do fluxo.
• error é omitido quando o fluxo está normalmente fechado.
• error.name pode ser StreamNotFound, Forbidden, BadRequest, InternalServerError, ou IdleTimeout.
• error.message contém detalhes de erro.

Resposta do sistema

O serviço Web PubSub também pode enviar respostas relacionadas ao sistema para o cliente.

Conectado

Quando o cliente se conecta ao serviço, você recebe uma mensagem DownstreamMessage.SystemMessage.ConnectedMessage.

Desconectado

Quando o servidor encerra a conexão ou o serviço recusa o cliente, você recebe uma mensagem DownstreamMessage.SystemMessage.DisconnectedMessage.

Resposta Pong

O serviço Web PubSub envia um PongMessage para o cliente quando recebe um PingMessage do cliente.

Próximas etapas

Use estes recursos para começar a criar seu aplicativo: