Mensagens, payloads e serialização

  • Artigo

O Barramento de Serviço do Azure lida com mensagens. As mensagens carregam uma carga útil e metadados. Os metadados estão na forma de pares chave-valor, descrevem a carga útil e fornecem instruções de manuseio para o Service Bus e aplicativos. Ocasionalmente, esses metadados por si só são suficientes para transportar as informações que o emissor deseja comunicar aos destinatários, e a carga útil permanece vazia.

O modelo de objeto dos clientes oficiais do Service Bus para .NET e Java reflete a estrutura abstrata de mensagens do Service Bus, que é mapeada de e para os protocolos de conexão suportados pelo Service Bus.

Uma mensagem do Service Bus consiste em uma seção de carga binária que o Service Bus nunca manipula de forma alguma no lado do serviço e dois conjuntos de propriedades. As propriedades do corretor são predefinidas pelo sistema. Essas propriedades predefinidas controlam a funcionalidade no nível da mensagem dentro do broker ou são mapeadas para itens de metadados comuns e padronizados. As propriedades do usuário são uma coleção de pares chave-valor que podem ser definidos e definidos pelo aplicativo.

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

Os nomes equivalentes usados no nível de protocolo AMQP (Advanced Message Queuing Protocol) são listados entre parênteses. Enquanto os nomes a seguir usam caixa pascal, os clientes JavaScript e Python usariam caixa camel e snake, respectivamente.

Nome de Propriedade Description
ContentType (content-type) Opcionalmente, descreve a carga útil 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 Defina apenas as mensagens que foram com letras mortas e, posteriormente, encaminhadas automaticamente da fila de mensagens mortas para outra entidade. Indica a entidade na qual a mensagem foi escrita mortamente. Esta propriedade é somente leitura.
DeliveryCount

Número de entregas que foram tentadas para esta mensagem. A contagem é incrementada quando um bloqueio de mensagem expira ou a mensagem é explicitamente abandonada pelo recetor. Esta propriedade é somente 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 foi atribuído pela primeira vez à mensagem em seu ponto de envio original. Esta propriedade é somente leitura.
EnqueuedTimeUtc O instante UTC no qual a mensagem foi aceita e armazenada na entidade. Este valor pode ser usado como um indicador de hora de chegada autorizado e neutro quando o recetor não quer confiar no relógio do remetente. Esta propriedade é somente leitura.
Expires​AtUtc (absolute-expiry-time) O instante 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 é calculada a partir de EnqueuedTimeUtc+TimeToLive. Esta propriedade é somente leitura.
Label ou Subject (subject) Esta propriedade permite que o aplicativo indique a finalidade da mensagem para o destinatário de forma padronizada, semelhante a uma linha de assunto de e-mail.
Locked​Until​Utc Para mensagens recuperadas sob um bloqueio (modo de recebimento peek-lock, não preestabelecido), essa propriedade reflete o instante UTC até o qual a mensagem é mantida bloqueada na fila/assinatura. Quando o bloqueio expira, o DeliveryCount é incrementado e a mensagem fica novamente disponível para recuperação. Esta propriedade é somente leitura.
Lock​Token O token de bloqueio é uma referência ao bloqueio que está sendo mantido pelo corretor no modo de recebimento peek-lock . O token pode ser usado para fixar o bloqueio permanentemente através da API de adiamento e, com isso, tirar a mensagem do fluxo de estado de entrega regular. Esta propriedade é somente leitura.
Message​Id (message-id) O identificador de mensagem é um valor definido pelo aplicativo que identifica exclusivamente a mensagem e sua carga útil. 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 de deteção de duplicados identifica e remove o segundo e outros envios de mensagens com o mesmo MessageId.
Partition​Key Para entidades particionadas, a definição desse valor permite atribuir mensagens relacionadas à mesma partição interna, para que a ordem da sequência de envio seja registrada corretamente. A partição é escolhida por uma função hash sobre este 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 recetor da mensagem. Quando um remetente espera uma resposta, ele define o valor para o caminho absoluto ou relativo da fila ou tópico para o qual espera que a resposta seja enviada.
Reply​To​Session​Id (reply-to-group-id) Esse valor aumenta as informações de ReplyTo e especifica qual SessionId deve ser definido para a resposta quando enviada para a entidade de resposta.
Scheduled​Enqueue​Time​Utc Para mensagens que só são disponibilizadas para recuperação após um atraso, essa propriedade define o instante 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 exclusivo de 64 bits atribuído a uma mensagem à medida que é aceite e armazenado pelo broker e funciona como o seu verdadeiro identificador. Para entidades particionadas, os 16 bits superiores refletem o identificador de partição. Os números de sequência aumentam monotonicamente e não têm intervalos. Eles rolam para 0 quando o intervalo de 48-64 bits está esgotado. Esta propriedade é somente 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 a bloqueio de resumo e permitem o processamento exato em ordem e a desmultiplexação. Para entidades que não reconhecem a sessão, esse valor é ignorado.
Time​To​Live Esse valor é a duração relativa após a qual a mensagem expira, a partir do instante em que foi aceita e armazenada pelo broker, conforme capturado em EnqueueTimeUtc. Quando não definido explicitamente, o valor assumido é o DefaultTimeToLive para a respetiva 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 mais longo, é ajustado silenciosamente.
To (to) Essa propriedade é reservada para uso futuro em cenários de roteamento e atualmente ignorada pelo próprio broker. Os aplicativos podem usar esse valor em cenários de encadeamento de encaminhamento automático controlados por regras para indicar o destino lógico pretendido da mensagem.
Via​Partition​Key Se uma mensagem for enviada através de uma fila de transferência no âmbito de uma transação, este valor selecionará a partição da fila de transferência.

O modelo de mensagem abstrata permite que uma mensagem seja postada em uma fila via HTTPS e pode ser recuperada via AMQP. Em ambos os casos, a mensagem parece normal no contexto do respetivo protocolo. As propriedades do broker são traduzidas conforme necessário, e as propriedades do usuário são mapeadas para o local mais apropriado no respetivo modelo de mensagem de protocolo. Em HTTP, as propriedades do usuário são mapeadas diretamente de e para cabeçalhos HTTP; no AMQP eles mapeiam de e para o application-properties mapa.

Roteamento e correlação de mensagens

Um subconjunto das propriedades do broker descritas anteriormente, especificamente To, , ReplyTo, ReplyToSessionId, MessageIdCorrelationId, e SessionId, são usadas para ajudar os aplicativos a rotear mensagens para destinos específicos. Para ilustrar esse recurso, considere alguns padrões:

  • Solicitação/resposta simples: um editor envia uma mensagem para uma fila e espera uma resposta do consumidor da mensagem. Para receber a resposta, o editor possui uma fila na qual espera que as respostas sejam entregues. O endereço da fila é expresso na propriedade ReplyTo da mensagem de saída. Quando o consumidor responde, ele copia o MessageId da mensagem manipulada na propriedade CorrelationId da mensagem de resposta e entrega a mensagem no destino indicado pela propriedade ReplyTo . Uma mensagem pode gerar várias respostas, dependendo do contexto do aplicativo.
  • Solicitação/resposta de multicast: como uma variação do padrão anterior, um editor envia a mensagem para um tópico e vários assinantes se tornam elegíveis para consumir a mensagem. Cada um dos subscritores pode responder da forma descrita anteriormente. Esse padrão é usado em cenários de descoberta ou roll-call e o respondente normalmente se identifica com uma propriedade de usuário ou dentro da carga útil. Se ReplyTo apontar para um tópico, esse conjunto de respostas de descoberta poderá ser distribuído para um público.
  • Multiplexação: Este recurso de sessão permite a multiplexação de fluxos de mensagens relacionadas através de uma única fila ou assinatura, de modo que cada sessão (ou grupo) de mensagens relacionadas, identificadas por valores SessionId correspondentes, sejam roteadas para um recetor específico enquanto o recetor mantém a sessão bloqueada. Leia mais sobre os detalhes das sessões aqui.
  • Solicitação/resposta multiplexada: esse recurso de sessão permite respostas multiplexadas, permitindo que vários editores compartilhem uma fila de respostas. Ao definir ReplyToSessionId, o editor pode instruir os consumidores a copiar esse valor para a propriedade SessionId da mensagem de resposta. A fila de publicação ou o tópico não precisa estar ciente da sessão. À medida que a mensagem é enviada, o editor pode então aguardar especificamente que uma sessão com o SessionId fornecido se materialize na fila aceitando condicionalmente um recetor de sessão.

O roteamento dentro de um namespace do Service Bus pode ser realizado usando encadeamento automático e regras de assinatura de tópico. O roteamento entre namespaces pode ser realizado usando o Azure LogicApps. Como indicado na lista anterior, a propriedade To é reservada para uso futuro e pode eventualmente ser interpretada pelo corretor com um recurso especialmente habilitado. Os aplicativos que desejam implementar o roteamento devem fazê-lo com base nas propriedades do usuário e não se apoiar na propriedade Para , no entanto, fazer isso agora não causará problemas de compatibilidade.

Serialização de carga útil

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

Ao contrário das variantes Java ou .NET Standard, a versão .NET Framework da API do Service Bus oferece 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, para que você não possa mais usar esse protocolo após 30 de setembro de 2026. Migre para as bibliotecas mais recentes do SDK do Azure, que oferecem atualizações de segurança críticas e recursos aprimorados, antes dessa data.

Embora as bibliotecas mais antigas ainda possam 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, consulte o anúncio de aposentadoria de suporte.

Quando você usa 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 recetor pode recuperar esses objetos com o GetBody\<T>() método, fornecendo o tipo esperado. Com AMQP, os objetos são serializados em um gráfico AMQP de ArrayList e IDictionary<string,object> objetos, e qualquer cliente AMQP pode decodificá-los.

Em 30 de setembro de 2026, desativaremos o suporte ao protocolo SBMP para o Barramento de Serviço do Azure, portanto, você não poderá mais usar esse protocolo após 30 de setembro de 2026. Migre para as bibliotecas mais recentes do SDK do Barramento de Serviço do Azure usando o protocolo AMQP, que oferecem atualizações de segurança críticas e recursos aprimorados, antes dessa data.

Para obter mais informações, consulte o anúncio de aposentadoria de suporte.

Embora essa magia de serialização oculta seja conveniente, os aplicativos devem assumir o controle explícito da serialização de objetos e transformar seus gráficos de objetos em fluxos antes de incluí-los em uma mensagem, e fazer o inverso no lado do recetor. Isto produz resultados interoperáveis. Embora o AMQP tenha um poderoso modelo de codificação binária, ele está vinculado ao ecossistema de mensagens AMQP, e os clientes HTTP têm problemas para decodificar essas cargas úteis.

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

Ao lidar com a desserialização de objetos da carga útil da mensagem, os desenvolvedores devem levar em consideração que as mensagens podem chegar de várias fontes usando métodos de serialização diferentes. Isso também pode acontecer ao evoluir um único aplicativo, onde as versões antigas podem continuar a ser executadas ao lado das versões mais recentes. Nesses casos, recomenda-se ter métodos de desserialização adicionais para tentar se a primeira tentativa de desserialização falhar. Uma biblioteca que suporta isso é o NServiceBus. Se todos os métodos de desserialização falharem, recomenda-se escrever a mensagem em letra morta.

Próximos passos

Para saber mais sobre as mensagens do Service Bus, consulte os seguintes tópicos: