Сообщения, полезные данные и сериализация

  • Статья

Служебная шина Azure обрабатывает сообщения. Сообщения содержат полезные данные и метаданные. Метаданные представлены в виде пар "ключ-значение" и описывают полезные данные и предоставляют инструкции по обработке служебная шина и приложений. Иногда для хранения информации, которую отправитель хочет донести до получателей, достаточно одних метаданных, и полезные данные остаются пустыми.

Объектная модель официальных клиентов служебной шины для .NET и Java отражает абстрактную структуру сообщений служебной шины, сопоставленную с сетевыми протоколами передачи, которые поддерживает служебная шина.

Сообщение служебной шины состоит из раздела полезных данных в двоичном формате, который служебная шина никак не обрабатывает на стороне службы, и двух наборов свойств. Свойства брокера предопределяются системой. Эти свойства управляют функциональными возможностями (на уровне сообщения) внутри брокера либо сопоставляются с общими и стандартизированными элементами метаданных. Свойства пользователя представляют собой коллекцию пар "ключ — значение", которая может быть определена и установлена приложением.

В таблице ниже содержится список предопределенных свойств брокера. Имена используются со всеми API официальных клиентов, а также в объекте JSON BrokerProperties сопоставления протокола HTTP.

В скобках указаны эквивалентные имена, используемые на уровне протокола AMQP. Хотя в следующих именах используется регистр pascal, обратите внимание, что клиенты JavaScript и Python будут использовать верблюдю и змея регистр соответственно.

Имя свойства Description
ContentType (content-type) При необходимости описывает полезные данные сообщения с помощью дескриптора, используя формат RFC2045 раздела 5, например application/json.
CorrelationId (correlation-id) Позволяет приложению указать контекст сообщения для корреляции, например MessageId сообщения, для которого предоставляется ответ.
DeadLetterSource Задается только в сообщениях, которые не были доставлены и позже были автоматически пересланы из очереди недоставленных сообщений в другую сущность. Указывает сущность, в которой сообщения перешли в состояние недоставленных. Это свойство доступно только для чтения.
DeliveryCount

Количество попыток доставки этого сообщения. Значение счетчика увеличивается, когда заканчивается период блокировки сообщения или сообщение явно отклоняется получателем. Это свойство доступно только для чтения.

Число доставок не увеличивается при закрытии базового подключения AMQP.
EnqueuedSequenceNumber Для автоматически пересланных сообщений это свойство отражает порядковый номер, который был присвоен сообщению в исходной точке отправки. Это свойство доступно только для чтения.
EnqueuedTimeUtc Время в формате UTC, когда сообщение было принято и сохранено в сущности. Это значение может использоваться в качестве достоверного и нейтрального индикатора времени прихода сообщения, если получатель не доверяет времени на стороне отправителя. Это свойство доступно только для чтения.
Expires​AtUtc (absolute-expiry-time) Время в формате UTC, когда сообщение было помечено для удаления и стало недоступным для извлечения из сущности из-за истечения срока действия. Срок действия контролируется свойством TimeToLive, которое вычисляется по формуле EnqueuedTimeUtc+TimeToLive. Это свойство доступно только для чтения.
Label или Subject (subject) Это свойство позволяет приложению указать цель сообщения для получателя в обычном виде, аналогично строке темы сообщения электронной почты.
Locked​Until​Utc Для сообщений, полученных под блокировкой (режим получения блокировки, а не предустановленный), это свойство отражает момент UTC, пока сообщение не заблокировано в очереди или подписке. По истечении срока действия блокировки DeliveryCount увеличивается, и сообщение снова доступно для извлечения. Это свойство доступно только для чтения.
Lock​Token Маркер блокировки является ссылкой на блокировку, удерживаемую брокером в режиме блокировки для просмотра. Маркер можно использовать для окончательного закрепления блокировки через API отсрочки и, таким образом, принимать сообщения из потока состояния обычной доставки. Это свойство доступно только для чтения.
Message​Id (message-id) Идентификатор сообщения — это определяемое приложением значение, позволяющее уникально идентифицировать сообщение и его полезные данные. Идентификатор — это строка в свободной форме, которая может отразить глобальный уникальный идентификатор или идентификатор, производный от контекста приложения. Если включена, функция обнаружения дубликатов определяет и удаляет вторые и последующие отправки сообщений с тем же MessageId.
Partition​Key Для секционированных сущностей установка этого значения позволяет назначить связанные сообщения тому же внутреннему разделу, чтобы порядок последовательности отправки был правильно записан. Секция выбирается с помощью хэш-функции этого значения. Ее нельзя выбрать напрямую. Для сущностей, учитывающих сеансы, свойство SessionId переопределяет это значение.
Reply​To (reply-to) Это необязательное значение, определяемое приложением, является стандартным способом выражения пути ответа для получателя сообщения. Когда отправитель ожидает ответа, он присваивает значение абсолютному или относительному пути очереди или раздела, куда будет отправлен ответ.
Reply​To​Session​Id (reply-to-group-id) Это значение расширяет сведения ReplyTo и указывает, какой SessionId должен быть задан для ответа при отправке в сущность ответа.
Scheduled​Enqueue​Time​Utc Для сообщений, которые доступны для извлечения после задержки, это свойство определяет время в формате UTC, когда сообщение будет логически поставлено в очередь, упорядочено и, следовательно, станет доступно для извлечения.
Sequence​Number Порядковый номер — это уникальное 64-битное целое число, присваиваемое сообщению, когда его принимает и сохраняет брокер, которое выступает в качестве правильного идентификатора. Для секционированных сущностей верхние 16 бит отражают идентификатор раздела. Порядковые номера монотонно увеличиваются и не имеют промежутков. Когда диапазон 48–64 бит исчерпан, используется значение 0. Это свойство доступно только для чтения.
Session​Id (group-id) Для сущностей, учитывающих сеансы, это значение, определяемое приложением, указывает принадлежность сеанса сообщения. В сообщениях с одинаковым идентификатором сеанса может быть заблокирована сводка и включена точная порядковая обработка и демультиплексирование. Для сущностей, которые не поддерживают сеансы, это значение игнорируется.
Time​To​Live Это относительная длительность, после которой истекает срок действия сообщения, начиная с момента, когда его принял и сохранил брокер, как записано в EnqueueTimeUtc. Если не задано явно, для соответствующей очереди или раздела используется значение DefaultTimeToLive. Значение времени TimeToLive на уровне сообщения не может быть дольше значения параметра сущности DefaultTimeToLive. В противном случае оно будет автоматически скорректировано.
To (to) Это свойство зарезервировано для будущего использования в сценариях маршрутизации. Сейчас брокер игнорирует это свойство. Приложения могут использовать это значение в управляемых правилами сценариях цепочки автоматической пересылки, чтобы указать целевое логическое назначение сообщения.
Via​Partition​Key Если сообщение отправляется через очередь передачи в области транзакции, это значение выбирает раздел очереди передачи.

Модель абстрактного сообщения позволяет отправить сообщение в очередь по протоколу HTTPS. Получить сообщение можно по протоколу AMQP. В любом случае сообщение выглядит обычным в контексте соответствующего протокола. Свойства брокера преобразовываются при необходимости, а свойства пользователя сопоставляются с наиболее подходящим расположением соответствующей модели сообщения протокола. В HTTP свойства пользователя сопоставляются непосредственно с заголовками HTTP, в AMQP они сопоставляются со схемой свойств приложения.

Маршрутизация и корреляция сообщений

Свойства брокера, описанные ранее, в частности To, ReplyTo, ReplyToSessionId, MessageId, CorrelationId и SessionId, помогают приложению направлять сообщения в определенные пункты назначения. Чтобы показать эту возможность, рассмотрим несколько шаблонов.

  • Простой запрос или ответ. Издатель отправляет сообщение в очередь и ждет ответа от потребителя сообщений. Чтобы получить ответ, издателю должна принадлежать очередь, в которую будет доставлен ответ. Адрес очереди выражается в свойстве ReplyTo исходящего сообщения. Когда пользователь отвечает, он копирует MessageId обработанного сообщения в свойство CorrelationId сообщения ответа и отправляет сообщение в пункт назначения, обозначаемый свойством ReplyTo. Одно сообщение может выдавать несколько ответов в зависимости от контекста приложения.
  • Запрос или ответ многоадресной рассылки. Вариант предыдущей модели: издатель отправляет сообщение в раздел, и несколько подписчиков могут использовать это сообщение. Каждый подписчик может ответить описанным выше образом. Этот шаблон используется в сценариях обнаружения или вызовов. Респондент обычно идентифицируется с помощью свойства пользователя или внутри полезных данных. Если ReplyTo указывает на раздел, такой набор ответов обнаружения может быть распределен среди аудитории.
  • Мультиплексирование. Эта функция сеанса позволяет выполнить мультиплексирование потоков связанных сообщений через одну очередь или подписку таким образом, чтобы каждый сеанс (или группа) связанных сообщений, определенных путем сопоставления значений SessionId, направлялся конкретному получателю, в то время как получатель блокирует сеанс. Дополнительные сведения о сеансах см. здесь.
  • Мультиплексированный запрос или ответ. Эта функция сеанса включает мультиплексированные ответы, позволяя нескольким издателям совместно использовать очередь ответов. Задав ReplyToSessionId, издатель может указать получателю скопировать это значение в свойство SessionId сообщения ответа. Очередь или раздел публикации не должны учитывать сеансы. При отправке сообщения издатель может специально дождаться сеанса с указанным SessionId, чтобы материализовать очередь, условно приняв получателя сеанса.

Маршрутизацию внутри пространства имен служебной шины можно реализовать с помощью правил цепочки автоматической пересылки и подписки раздела. Маршрутизацию в пространстве имен можно реализовать с помощью Azure LogicApps. Как указано в списке выше, свойство To зарезервировано для будущего использования и в итоге может интерпретироваться брокером со специально включенной функцией. Приложения, которые желают реализовать маршрутизацию, должны сделать это на основе свойств пользователя и не полагаться на свойство To. Однако выполнение этого действия не вызовет проблем совместимости.

Сериализация полезных данных

Во время передачи или хранения в служебной шине полезные данные всегда непрозрачны и имеют двоичный блок. Свойство ContentType позволяет приложению описывать полезные данные, используя предполагаемый формат для значений свойств, и является описанием типа содержимого MIME в соответствии с IETF RFC2045, например application/json;charset=utf-8.

В отличие от вариантов Java или .NET Standard версия .NET Framework API служебной шины поддерживает создание экземпляров BrokeredMessage, передавая произвольные объекты .NET в конструктор.

30 сентября 2026 г. мы удалим библиотеки пакета SDK Служебная шина Azure WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus и com.microsoft.azure.servicebus, которые не соответствуют рекомендациям по пакету SDK Azure. Мы также завершим поддержку протокола SBMP, поэтому вы больше не сможете использовать этот протокол после 30 сентября 2026 года. Перейдите в последние библиотеки пакета SDK Azure, которые предлагают критически важные обновления системы безопасности и улучшенные возможности до этой даты.

Хотя старые библиотеки по-прежнему могут использоваться после 30 сентября 2026 года, они больше не будут получать официальную поддержку и обновления от Майкрософт. Дополнительные сведения см. в объявлении о выходе на пенсию в службу поддержки.

При использовании предыдущих версий протокола SBMP эти объекты затем сериализуются с помощью стандартного двоичного сериализатора или с помощью сериализатора, который предоставляется извне. Объект сериализуется в объект AMQP. Получатель может получить объекты с помощью метода GetBody<Т>(), передавая ожидаемый тип. При использовании AMQP объекты сериализуются в граф AMQP, состоящий из объектов ArrayList и IDictionary<string,object>, и любой клиент AMQP может декодировать их.

30 сентября 2026 года мы отставим от поддержки протокола SBMP для Служебная шина Azure, поэтому вы больше не сможете использовать этот протокол после 30 сентября 2026 года. Миграция на последние библиотеки пакета SDK Служебная шина Azure с помощью протокола AMQP, который предлагает критически важные обновления системы безопасности и улучшенные возможности до этой даты.

Дополнительные сведения см. в объявлении о выходе на пенсию в службу поддержки.

Хотя эта скрытая волшебная команда сериализации удобна, приложение должно явно контролировать сериализацию объектов и преобразовать их диаграммы объектов в потоки, прежде чем включить их в сообщение и выполнить обратную операцию на стороне получателя. Это дает взаимодействующие результаты. Хотя AMQP имеет мощную двоичную модель кодирования, она привязана к экосистеме обмена сообщениями AMQP, и у клиентов HTTP возникнут проблемы с декодированием таких полезных данных.

Варианты .NET Standard и API Java принимают только массивы байтов. Это означает, что приложение должно обрабатывать элементы управления сериализации объектов.

Если полезные данные сообщения не могут быть десериализированы, рекомендуется отменить отправку сообщения.

Следующие шаги

Дополнительные сведения об обмене сообщениями через служебную шину см. в следующих статьях: