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

  • Artigo

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

Os ouvintes de eventos do serviço ouvem eventos do cliente. Os Hubs de Eventos são atualmente o único ponto de extremidade de ouvinte de eventos suportado, cujo protocolo principal é AMQP (Advanced Message Queueing Protocol). O serviço Web PubSub usa a vinculação do protocolo AMQP do CloudEvents para mapear o CloudEvents para mensagens AMQP.

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

Extensão do atributo Web PubSub CloudEvents

Esta extensão define os atributos usados pelo Web PubSub para cada evento que produz.

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

Name Descrição Exemplo
content-type O tipo MIME RFC-2046 para o corpo da mensagem application/json
message-id Define exclusivamente uma mensagem em um serviço 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 do CloudEvents mapeados para a seção de propriedades do aplicativo de uma mensagem AMQP. Cada nome de atributo é prefixado com cloudEvents:.

Name Descrição Exemplo
specversion Versão de especificação de eventos na nuvem, é sempre 1.0 1.0
source Indica o hub e o ID de conexão de onde vem o evento, no formato "/hubs/{hub}/client/{connectionId}" /hubs/chat/cliente/0bd83792-2a0c-48d3-9fbd-df63aa2ed9db
id Um inteiro gerado pelo serviço, exclusivo nos eventos da mesma conexão de cliente 1
awpsversion Eventos na nuvem A versão da especificação do Azure Web PubSub é sempre 1.0 1.0
hub O nome do hub de onde vem o evento chat
eventname O nome do evento ligado
type O tipo de evento azure.webpubsub.sys.connect
connectionid A ID da conexão do cliente 0bd83792-2a0c-48d3-9fbd-df63aa2ed9db
time A hora em que o serviço envia o evento, no formato "aaaa-MM-ddTHH:mm:ssZ" 2021-01-01T00:00:00Z
userid* O ID do usuário utilizador1
subprotocol* O nome do subprotocolo json.webpubsub.azure.v1
connectionstate* Define o estado da conexão. Você pode redefinir o valor no cabeçalho de resposta dos manipuladores de eventos. Para obter mais informações sobre o estado da conexão, consulte Web PubSub CloudEvents attributes. anystring

O "*" após o nome do atributo indica que o atributo está presente somente quando o valor não é nulo ou 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 do sistema connected

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

O corpo da mensagem é sempre JSON vazio.

{}

Evento do sistema disconnected

  • 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 de usuário para clientes WebSocket simples

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

Corpo da mensagem é o que o cliente envia.

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

  • content-type: application/octet-stream para quadro binário; para quadro JSON; para quadro de texto; para quadro Protobuf; application/json text/plain application/x-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 mensagem AMQP recebidos.

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>