Mensagens, payloads e serialização

O Barramento de Serviço do Azure lida com mensagens. As mensagens carregam um conteúdo e metadados. Os metadados estão na forma de par chave-valor, descrevem o conteúdo e oferecem instruções de tratamento para o Barramento de Serviço e para aplicativos. Ocasionalmente, esses metadados sozinhos são suficientes para carregar as informações que o remetente deseja comunicar aos destinatários e o payload permanece vazio.

O modelo de objeto dos clientes oficiais do Barramento de Serviço para .NET e Java reflete a estrutura de mensagem do Barramento de Serviço abstrato, que é mapeada para e dos protocolos de transmissão compatíveis com o Barramento de Serviço.

Uma mensagem do Barramento de Serviço consiste em uma seção de payload binário que o Barramento de Serviço nunca manipula em nenhuma forma no lado do serviço e dois conjuntos de propriedade. As propriedades do agente são predefinidas pelo sistema. Essas propriedades predefinidas controlam a funcionalidade de nível de mensagem dentro do agente ou são mapeados para os itens de metadados comuns e padronizados. As propriedades do usuário são uma coleção de pares chave-valor que podem ser definidas pelo aplicativo.

As propriedades do agente predefinidas são listadas na tabela a seguir. Os nomes são usados ​​com todas as APIs oficiais do cliente e também no objeto JSON BrokerProperties do mapeamento do protocolo HTTP.

Os nomes equivalentes usados no nível do protocolo AMQP (Advanced Message Queuing Protocol) são listados entre parênteses. Embora os nomes a seguir usem o padrão Pascal, os clientes JavaScript e Python usariam os padrões Camel e Snake, respectivamente.

Nome da propriedade	Descrição
ContentType (content-type)	Descreve opcionalmente o payload da mensagem com um descritor seguindo o formato de RFC2045, Seção 5; por exemplo, application/json.
CorrelationId (correlation-id)	Permite que um aplicativo especifique um contexto para a mensagem para fins de correlação; por exemplo, refletindo o MessageId de uma mensagem que está sendo respondida.
DeadLetterSource	Definido apenas em mensagens mortas e posteriormente encaminhadas de forma automática da fila de mensagens mortas para outra entidade. Indica a entidade na qual a mensagem foi morta. Esta propriedade é somente para leitura.
DeliveryCount	Número de entregas que foram tentadas para essa mensagem. A contagem é incrementada quando um bloqueio de mensagem expira ou quando a mensagem é explicitamente abandonada pelo destinatário. Esta propriedade é somente para leitura. A contagem de entrega não é incrementada quando a conexão AMQP subjacente é fechada.
EnqueuedSequenceNumber	Para mensagens que foram encaminhadas automaticamente, essa propriedade reflete o número de sequência que tinha sido atribuído primeiro à mensagem no seu ponto de envio original. Esta propriedade é somente para leitura.
EnqueuedTimeUtc	O instante do UTC no qual a mensagem foi aceita e armazenada na entidade. Esse valor pode ser usado como um indicador de tempo de chegada autoritativo e neutro quando o receptor não deseja confiar no relógio do remetente. Esta propriedade é somente para leitura.
Expires​AtUtc (absolute-expiry-time)	O instante de UTC no qual a mensagem é marcada para remoção e não está mais disponível para recuperação da entidade devido à sua expiração. A expiração é controlada pela propriedade TimeToLive e essa propriedade é computada em EnqueuedTimeUtc+TimeToLive. Esta propriedade é somente para leitura.
Label ou Subject (subject)	Essa propriedade permite que o aplicativo indique a finalidade da mensagem para o destinatário de maneira padronizada, semelhante a uma linha do assunto de email.
Locked​Until​Utc	Para mensagens recuperadas com um bloqueio (modo de recebimento de bloqueio de pico, não previamente liquidadas) esta propriedade reflete o instante do UTC até que a mensagem seja mantida bloqueada na fila/assinatura. Quando o bloqueio expirar, o DeliveryCount será incrementado e a mensagem estará disponível novamente para recuperação. Esta propriedade é somente para leitura.
Lock​Token	O token de bloqueio é uma referência para o bloqueio que está sendo mantido pelo agente no modo de recebimento de bloqueio de pico. O token pode ser usado para fixar o bloqueio permanentemente por meio da API de adiamento e, com isso, tirar a mensagem fora do fluxo do estado de entrega regular. Esta propriedade é somente para leitura.
Message​Id (message-id)	O identificador da mensagem é um valor definido pelo aplicativo que identifica exclusivamente a mensagem e seu payload. O identificador é uma cadeia de caracteres de forma livre e pode refletir um GUID ou um identificador derivado do contexto do aplicativo. Se habilitado, o recurso detecção de duplicidades identifica e remove a segunda e os envios adicionais de mensagens com o mesmo MessageId.
Partition​Key	Para entidades particionadas, definir esse valor permite a atribuição de mensagens relacionadas à mesma partição interna para que a ordem de sequência de envio esteja registrada corretamente. A partição é escolhida por uma função de hash sobre esse valor e não pode ser escolhida diretamente. Para entidades com reconhecimento de sessão, a propriedade SessionId substitui esse valor.
Reply​To (reply-to)	Esse valor opcional e definido pelo aplicativo é uma maneira padrão de expressar um caminho de resposta para o receptor da mensagem. Quando um remetente espera uma resposta, ele define o valor como o caminho absoluto ou relativo da fila ou do tópico para o qual ele espera que a resposta seja enviada.
Reply​To​Session​Id (reply-to-group-id)	Esse valor aumenta a informação ReplyTo e especifica qual SessionId deve ser definido para a resposta quando enviada para a entidade de resposta.
Scheduled​Enqueue​Time​Utc	Para mensagens disponibilizadas apenas para recuperação após um atraso, essa propriedade define o instante do UTC no qual a mensagem será logicamente enfileirada, sequenciada e, portanto, disponibilizada para recuperação.
Sequence​Number	O número de sequência é um inteiro de 64 bits atribuído a uma mensagem conforme ela é aceita e armazenada pelo agente e por funções como seu identificador verdadeiro. Para entidades particionadas, os 16 bits de nível mais alto refletem o identificador da partição. Os números de sequência aumentam de forma monotônica e não têm intervalo. Eles passam para 0 quando o intervalo de 48 a 64 bits é esgotado. Esta propriedade é somente para leitura.
Session​Id (group-id)	Para entidades com reconhecimento de sessão, esse valor definido pelo aplicativo especifica a afiliação de sessão da mensagem. As mensagens com o mesmo identificador de sessão estão sujeitas ao bloqueio de resumo e permitem a demultiplexação e o processamento na ordem exata. Para entidades que não estejam cientes de sessão, esse valor é ignorado.
Time​To​Live	Esse valor é a duração relativa após a qual a mensagem expira, a partir do momento em que ela foi aceita e armazenada pelo agente, conforme capturada em EnqueueTimeUtc. Quando não definido explicitamente, o valor assumido será o DefaultTimeToLive para a respectiva fila ou tópico. Um valor TimeToLive no nível da mensagem não pode ser maior do que a configuração DefaultTimeToLive da entidade. Se for maior, ele será silenciosamente ajustado.
To (to)	Essa propriedade é reservada para uso futuro em cenários de roteamento e é atualmente ignorada pelo próprio agente. Os aplicativos podem usar esse valor em cenários de encadeamento de encaminhamento automático orientado à regra para indicar o destino lógico pretendido da mensagem.
Via​Partition​Key	Se uma mensagem é enviada por meio de uma fila de transferência no escopo de uma transação, esse valor seleciona a partição da fila de transferência.

O modelo de mensagem abstrata permite que uma mensagem seja postada em uma fila por meio de HTTP e possa ser recuperada por meio do AMQP. Em qualquer caso, a mensagem parece normal no contexto do respectivo protocolo. As propriedades do agente são convertidas conforme necessário e as propriedades do usuário são mapeadas para o local mais adequado no respectivo modelo de mensagem de protocolo. No HTTP, as propriedades do usuário são mapeadas diretamente de e para cabeçalhos HTTP; no AMQP, eles são mapeados de e para o mapa application-properties.

Roteamento e correlação de mensagens

Um subconjunto das propriedades do agente descritas anteriormente, especificamente To, ReplyTo, ReplyToSessionId, MessageId, CorrelationId e SessionId, é usado para ajudar os aplicativos a rotear mensagens para destinos específicos. Para ilustrar isso, considere alguns padrões:

• Solicitação/resposta simples: um editor envia uma mensagem em uma fila e espera uma resposta do consumidor da mensagem. Para receber a resposta, o editor tem uma fila para a qual ele espera que as respostas sejam entregues. O endereço dessa fila é expresso na propriedade ReplyTo da mensagem de saída. Quando o consumidor responde, ele copia o MessageId da mensagem tratada para a propriedade CorrelationId da mensagem de resposta e entrega a mensagem ao destino indicado pela propriedade ReplyTo. Uma mensagem pode render várias respostas, dependendo do contexto do aplicativo.
• Solicitação/resposta multicast: como uma variação do padrão anterior, um editor envia a mensagem para um tópico, e vários assinantes se tornam qualificados para consumir a mensagem. Cada um dos assinantes pode responder da maneira descrita anteriormente. Esse padrão é usado em cenários de descoberta ou de chamada de rolagem, e o participante normalmente identifica-se com uma propriedade de usuário ou dentro do payload. Se ReplyTo aponta para um tópico, esse conjunto de respostas de descoberta pode ser distribuído para um público-alvo.
• Multiplexação: este recurso de sessão permite a multiplexação de fluxos de mensagens relacionadas por meio de uma única fila ou da assinatura de modo que cada sessão (ou grupo) de mensagens relacionadas, identificadas pelos valores SessionId correspondentes, seja roteada para um destinatário específico enquanto o receptor mantém a sessão bloqueada. Leia mais sobre os detalhes das sessões aqui.
• Solicitação/resposta multiplexada: este recurso de sessão permite respostas multiplexadas, possibilitando que vários editores compartilhem uma fila de resposta. Ao definir ReplyToSessionId, o editor pode instruir os consumidores a copiar esse valor na propriedade SessionId da mensagem de resposta. A fila ou tópico de publicação não precisa ter reconhecimento de sessão. Assim que a mensagem é enviada, o editor pode aguardar especificamente uma sessão com o SessionId fornecido ser materializada na fila aceitando condicionalmente um receptor de sessão.

O roteamento dentro de um namespace do Barramento de Serviço pode ser obtido usando as regras de encadeamento de encaminhamento automático e de assinatura de tópico. O roteamento entre namespaces pode ser obtido usando o Azure LogicApps. Conforme indicado na lista anterior, a propriedade To é reservada para uso futuro e pode, eventualmente, ser interpretada pelo agente com um recurso especialmente habilitado. Os aplicativos que desejarem implementar o roteamento deverão fazer isso com base nas propriedades do usuário e não depender da propriedade To; no entanto, fazer isso não causará problemas de compatibilidade.

Serialização de payload

Quando estiver em trânsito ou armazenado dentro do Barramento de Serviço, o payload é sempre um bloco opaco e binário. A propriedade ContentType permite que os aplicativos descrevam o conteúdo com o formato sugerido para os valores de propriedade, sendo uma descrição de tipo de conteúdo MIME de acordo com a IETF RFC2045; por exemplo, application/json;charset=utf-8.

Diferentemente das variantes Java ou .NET Standard, a versão .NET Framework da API do Barramento de Serviço dá suporte à criação de instâncias BrokeredMessage passando objetos .NET arbitrários para o construtor.

Em 30 de setembro de 2026, desativaremos as bibliotecas do SDK do Barramento de Serviço do Azure WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus e com.microsoft.azure.servicebus, que não estão em conformidade com as diretrizes do SDK do Azure. Também encerraremos o suporte ao protocolo SBMP, portanto, ele não poderá mais ser usado após 30 de setembro de 2026. Antes dessa data, migre para as bibliotecas mais recentes do SDK do Azure, que oferecem atualizações de segurança críticas e funcionalidades aprimoradas.

Embora as bibliotecas mais antigas ainda poderão ser usadas após 30 de setembro de 2026, elas não receberão mais suporte e atualizações oficiais da Microsoft. Para obter mais informações, confira o anúncio de desativação do suporte.

Ao usar o protocolo SBMP herdado, esses objetos são serializados com o serializador binário padrão ou com um serializador fornecido externamente. O objeto é serializado em um objeto AMQP. O receptor pode recuperar esses objetos com o método GetBody\<T>(), fornecendo o tipo esperado. Com AMQP, os objetos são serializados em um gráfico AMQP dos objetos ArrayList e IDictionary<string,object>, e qualquer cliente do AMQP pode decodificá-los.

Em 30 de setembro de 2026, desativaremos o suporte do protocolo SBMP para o Barramento de Serviço do Azure, portanto, não será mais possível usar esse protocolo após essa data. Migre para as bibliotecas mais recentes do SDK do Barramento de Serviço do Azure usando o protocolo AMQP, que oferece atualizações de segurança críticas e funcionalidades aprimoradas, antes dessa data.

Para obter mais informações, confira o anúncio de desativação do suporte.

Embora essa mágica de serialização oculta seja conveniente, os aplicativos devem assumir o controle explícito da serialização do objeto e transformar os grafos dos seus objetos em fluxos antes de incluí-los em uma mensagem e fazer o contrário no lado do receptor. Isso produz resultados interoperáveis. Embora o AMQP tenha um avançado modelo de codificação binária, ele está vinculado ao ecossistema de mensagens AMQP e os clientes HTTP têm dificuldades para decodificar esses conteúdos.

As variantes de .NET Standard e Java API só aceitam matrizes de bytes, o que significa que o aplicativo deve lidar com o controle de serialização do objeto.

Ao lidar com a desserialização de objetos do conteúdo da mensagem, os desenvolvedores devem levar em consideração que as mensagens podem chegar de várias fontes usando diferentes métodos de serialização. Isso também pode acontecer ao evoluir um só aplicativo, em que as versões antigas podem continuar sendo executadas junto com versões mais recentes. Nesses casos, é recomendável ter métodos de desserialização adicionais para experimentar, em caso de falha da primeira tentativa de desserialização. Uma biblioteca que dá suporte a esse recurso é o NServiceBus. Em caso de falha de todos os métodos de desserialização, é recomendável colocar a mensagem na fila de mensagens mortas.

Próximas etapas

Para saber mais sobre as mensagens do Barramento de Serviço, consulte os seguintes tópicos:

• Filas, tópicos e assinaturas do Barramento de Serviço
• Introdução às filas do Barramento de Serviço
• Como usar tópicos e assinaturas do Barramento de Serviço