Compartilhar via

Extensão do CloudEvents para o ouvinte de eventos do Azure Web PubSub com o protocolo AMQP

  • Artigo

O serviço do Azure Web PubSub descreve eventos de cliente como CloudEvents. CloudEvents é uma especificação para descrever dados de eventos em formatos comuns a fim de fornecer interoperabilidade entre serviços, plataformas e sistemas.

Os ouvintes de eventos do serviço escutam eventos do cliente. Atualmente, os Hubs de Eventos são o único ponto de extremidade de ouvinte de eventos com suporte, e o protocolo primário associado é o AMQP (Advanced Message Queueing Protocol). O serviço do Web PubSub usa a associação do protocolo AMQP de CloudEvents para mapear CloudEvents para mensagens AMQP.

Os dados enviados do serviço para o servidor estão sempre no formato de CloudEvents binary.

Extensão de atributo CloudEvents da Web PubSub

Essa extensão define os atributos usados pelo Web PubSub para cada evento produzido.

A tabela a seguir contém o mapeamento de atributos para a seção de propriedades padrão de uma mensagem AMQP.

Nome Descrição Exemplo
content-type O tipo MIME RFC-2046 para o corpo da mensagem aplicativo/json
message-id Define exclusivamente uma mensagem em um serviço do Web PubSub, no formato "{connection-id}/{an integer generated by service}" 0bd83792-2a0c-48d3-9fbd-df63aa2ed9db/1

A tabela a seguir contém todos os atributos de CloudEvents que são mapeados para a seção de propriedades do aplicativo de uma mensagem AMQP. Cada nome de atributo é prefixado com cloudEvents:.

Nome Descrição Exemplo
specversion A versão de especificação de eventos de nuvem é sempre 1.0 1.0
source Indica o hub e a ID de conexão de onde o evento vem, no formato "/hubs/{hub}/client/{connectionId}" /hubs/chat/client/0bd83792-2a0c-48d3-9fbd-df63aa2ed9db
id Um inteiro gerado pelo serviço, exclusivo nos eventos da mesma conexão de cliente 1
awpsversion A versão da especificação do Azure Web PubSub para eventos de nuvem é sempre 1.0 1.0
hub O nome do hub de onde o evento vem chat
eventname O nome do evento connected
type O tipo de evento azure.webpubsub.sys.connect
connectionid A ID da conexão de cliente 0bd83792-2a0c-48d3-9fbd-df63aa2ed9db
time A hora em que o serviço envia o evento, no formato "yyyy-MM-ddTHH:mm:ssZ" 2021-01-01T00:00:00Z
userid* A ID do usuário user1
subprotocol* O nome do subprotocolo json.webpubsub.azure.v1
connectionstate* Define o estado da conexão. É possível redefinir o valor no cabeçalho de resposta dos manipuladores de eventos. Para saber mais sobre o estado da conexão, confira Atributos de CloudEvents do Web PubSub. anystring

O "*" após o nome do atributo indica que ele está presente somente quando o valor não é nulo ou está vazio.

Eventos

Esta seção mostra o corpo da mensagem AMQP com os valores de atributo que dependem de um tipo de evento de cliente específico. Os valores de atributo que não dependem de um tipo de evento de cliente são omitidos.

Evento connected do sistema

  • content-type: application/json
  • cloudEvents:type: azure.webpubsub.sys.connected
  • cloudEvents:eventname: connected

O corpo da mensagem é sempre um JSON vazio.

{}

Evento disconnected do sistema

  • content-type: application/json
  • cloudEvents:type: azure.webpubsub.sys.disconnected
  • cloudEvents:eventname: disconnected

O corpo da mensagem contém o motivo pelo qual o cliente se desconectou.

{"reason":"{Reason}"}

Eventos message do usuário para os clientes simples do WebSocket

  • content-type: application/octet-stream para quadro binário; text/plain para quadro de texto;
  • cloudEvents:type: azure.webpubsub.user.message

O corpo da mensagem é o que o cliente envia.

Evento personalizado do usuário {custom_event} para clientes PubSub WebSocket

  • content-type: application/octet-stream para quadro binário; application/json para quadro JSON; text/plain para quadro de texto; application/x-protobuf para quadro Protobuf;
  • cloudEvents:type: azure.webpubsub.user.<event_name>

Os casos a seguir mostram como enviar eventos com diferentes tipos de conteúdo de dados e os corpos de mensagens AMQP recebidas.

Caso 1: enviar evento com dados de texto:

{
    "type": "event",
    "event": "<event_name>",
    "dataType": "text",
    "data": "text data"
}

Corpo da mensagem AMQP recebida:

text data

Caso 2: enviar evento com dados JSON:

{
    "type": "event",
    "event": "<event_name>",
    "dataType": "json",
    "data": {
        "hello": "world"
     }
}

Corpo da mensagem AMQP recebida:

{
    "hello": "world"
}

Caso 3: enviar evento com dados binários:

{
    "type": "event",
    "event": "<event_name>",
    "dataType": "binary",
    "data": "aGVsbG8gd29ybGQ=" // base64 encoded binary
}

Corpo da mensagem AMQP recebida:

<binary data>