AMQP 1.0 в служебной шине Microsoft Azure: операции c запросами и ответами

  • Статья

В этой статье приводится список операций с запросами и ответами в служебной шине Microsoft Azure. Эта информация основана на использовании рабочего проекта службы управления AMQP версии 1.0.

Подробные инструкции по работе с протоколом AMQP 1.0 на уровне соединения, которые объясняют, как служебная шина реализует и использует техническую спецификацию OASIS AMQP, см. в статье Руководство по использованию протокола AMQP 1.0 в служебной шине и Центрах событий Azure.

Основные понятия

ServiceBusReceivedMessage / ServiceBusMessage

Сообщение в служебной шине, сопоставленное с сообщением AMQP. Определение сопоставления см. в статье Руководство по использованию протокола AMQP 1.0 в служебной шине и концентраторах событий Azure.

Подключение к узлу управления сущностью

Все операции, описанные в этом документе, соответствуют шаблону "запрос — ответ", ограничены сущностью, и для их выполнения требуется подключение к узлу управления сущностью.

Создание ссылки на узел управления для отправки запросов.

requestLink = session.attach(
role: SENDER,
   	target: { address: "<entity address>/$management" },
   	source: { address: ""<my request link unique address>" }
)

Создание ссылки для получения ответов от узла управления.

responseLink = session.attach(
role: RECEIVER,
	source: { address: "<entity address>/$management" }
   	target: { address: "<my response link unique address>" }
)

Передача сообщения запроса

Передача сообщения запроса.
Состояние транзакции можно добавить при необходимости для операций, поддерживающих транзакции.

requestLink.sendTransfer(
        Message(
                properties: {
                        message-id: <request id>,
                        reply-to: "<my response link unique address>"
                },
                application-properties: {
                        "operation" -> "<operation>",
                }
        ),
        [Optional] State = transactional-state: {
                txn-id: <txn-id>
        }
)

Получение ответного сообщения

Получение ответного сообщения по ссылке ответа.

responseMessage = responseLink.receiveTransfer()

Ответное сообщение имеет следующий формат:

Message(
properties: {
		correlation-id: <request id>
	},
	application-properties: {
			"statusCode" -> <status code>,
			"statusDescription" -> <status description>,
           },
)

Адрес сущности служебной шины

Адреса сущностей служебной шины составляются следующим образом:

Тип объекта Адрес Пример
очередь <queue_name> “myQueue”

“site1/myQueue”
topic <topic_name> “myTopic”

“site2/page1/myQueue”
Подписка <topic_name>/Subscriptions/<subscription_name> “myTopic/Subscriptions/MySub”

Операции с сообщениями

Блокировка обновления сообщений

Продлите блокировку сообщения, задав длительность блокировки для очереди или подписки.

Запросить

Сообщение запроса должно включать следующие свойства приложения.

Ключ Тип значения Обязательное поле Содержимое значения
Операция строка Да com.microsoft:renew-lock
com.microsoft:server-timeout uint No Время ожидания ответа от сервера, на котором выполняется операция, в миллисекундах.

Текст запроса должен включать раздел amqp-value, содержащий схему со следующими элементами.

Ключ Тип значения Обязательное поле Содержимое значения
lock-tokens Массив UUID Да Маркеры блокировки сообщения для обновления.

Примечание.

Маркером блокировки здесь называется свойство delivery-tag в полученном сообщении AMQP. Если получено отложенное сообщение и требуется продлить блокировку, используйте lock-token в сообщении вместо delivery-tag.

Response

Ответное сообщение запроса должно включать следующие свойства приложения.

Ключ Тип значения Обязательное поле Содержимое значения
statusCode INT Да Код ответа HTTP [RFC2616].

200: ОК — операция выполнена успешно; в противном случае — сбой.
statusDescription строка Нет Описание состояния.

Текст ответа должен включать раздел amqp-value, содержащий схему со следующими элементами.

Ключ Тип значения Обязательное поле Содержимое значения
expirations Массив метки времени Да Новый срок действия для маркера блокировки сообщения, который соответствует маркерам блокировки запроса.

Просмотр сообщения

Просмотр сообщений без блокировки.

Запросить

Сообщение запроса должно включать следующие свойства приложения.

Ключ Тип значения Обязательное поле Содержимое значения
Операция строка Да com.microsoft:peek-message
com.microsoft:server-timeout uint No Время ожидания ответа от сервера, на котором выполняется операция, в миллисекундах.

Текст запроса должен включать раздел amqp-value, содержащий схему со следующими элементами.

Ключ Тип значения Обязательное поле Содержимое значения
from-sequence-number длинный Да Порядковый номер, с которого следует начать просмотр.
message-count INT Да Максимальное число просматриваемых сообщений.

Response

Ответное сообщение запроса должно включать следующие свойства приложения.

Ключ Тип значения Обязательное поле Содержимое значения
statusCode INT Да Код ответа HTTP [RFC2616].

200: ОК — есть дополнительные сообщения.

204: No content — нет сообщений
statusDescription строка Нет Описание состояния.

Текст ответа должен включать раздел amqp-value, содержащий схему со следующими элементами.

Ключ Тип значения Обязательное поле Содержимое значения
messages Список схем Да Список сообщений, в котором каждая схема представляет сообщение.

Схема, представляющая сообщение, должна содержать следующие элементы.

Ключ Тип значения Обязательное поле Содержимое значения
message Массив байтов Да Сообщение с кодированием линии связи AMQP 1.0.

Расписание сообщения

Расписание для сообщений. Эта операция поддерживает транзакции.

Запросить

Сообщение запроса должно включать следующие свойства приложения.

Ключ Тип значения Обязательное поле Содержимое значения
Операция строка Да com.microsoft:schedule-message
com.microsoft:server-timeout uint No Время ожидания ответа от сервера, на котором выполняется операция, в миллисекундах.

Текст запроса должен включать раздел amqp-value, содержащий схему со следующими элементами.

Ключ Тип значения Обязательное поле Содержимое значения
messages Список схем Да Список сообщений, в котором каждая схема представляет сообщение.

Схема, представляющая сообщение, должна содержать следующие элементы.

Ключ Тип значения Обязательное поле Содержимое значения
message-id строка Да amqpMessage.Properties.MessageId в качестве строки
session-id строка Нет amqpMessage.Properties.GroupId as string
partition-key строка Нет amqpMessage.MessageAnnotations.”x-opt-partition-key"
via-partition-key строка Нет amqpMessage.MessageAnnotations."x-opt-via-partition-key"
message Массив байтов Да Сообщение с кодированием линии связи AMQP 1.0.

Response

Ответное сообщение запроса должно включать следующие свойства приложения.

Ключ Тип значения Обязательное поле Содержимое значения
statusCode INT Да Код ответа HTTP [RFC2616].

200: ОК — операция выполнена успешно; в противном случае — сбой.
statusDescription строка Нет Описание состояния.

Текст ответа должен включать раздел amqp-value, содержащий схему со следующими элементами.

Ключ Тип значения Обязательное поле Содержимое значения
sequence-numbers Массив длинных чисел Да Порядковый номер запланированных сообщений. Порядковый номер используется для отмены.

Отмена запланированного сообщения

Отмена запланированных сообщений.

Запросить

Сообщение запроса должно включать следующие свойства приложения.

Ключ Тип значения Обязательное поле Содержимое значения
Операция строка Да com.microsoft:cancel-scheduled-message
com.microsoft:server-timeout uint No Время ожидания ответа от сервера, на котором выполняется операция, в миллисекундах.

Текст запроса должен включать раздел amqp-value, содержащий схему со следующими элементами.

Ключ Тип значения Обязательное поле Содержимое значения
sequence-numbers Массив длинных чисел Да Порядковый номер запланированных сообщений для отмены.

Response

Ответное сообщение запроса должно включать следующие свойства приложения.

Ключ Тип значения Обязательное поле Содержимое значения
statusCode INT Да Код ответа HTTP [RFC2616].

200: ОК — операция выполнена успешно; в противном случае — сбой.
statusDescription строка Нет Описание состояния.

Операции на уровне сеанса

Блокировка обновления сеанса

Продлите блокировку сообщения, задав длительность блокировки для очереди или подписки.

Запросить

Сообщение запроса должно включать следующие свойства приложения.

Ключ Тип значения Обязательное поле Содержимое значения
Операция строка Да com.microsoft:renew-session-lock
com.microsoft:server-timeout uint No Время ожидания ответа от сервера, на котором выполняется операция, в миллисекундах.

Текст запроса должен включать раздел amqp-value, содержащий схему со следующими элементами.

Ключ Тип значения Обязательное поле Содержимое значения
session-id строка Да ИД сеанса.

Response

Ответное сообщение запроса должно включать следующие свойства приложения.

Ключ Тип значения Обязательное поле Содержимое значения
statusCode INT Да Код ответа HTTP [RFC2616].

200: ОК — есть дополнительные сообщения.

204: No content — нет сообщений
statusDescription строка Нет Описание состояния.

Текст ответа должен включать раздел amqp-value, содержащий схему со следующими элементами.

Ключ Тип значения Обязательное поле Содержимое значения
expiration TIMESTAMP Да Новый срок действия.

Просмотр сообщения сеанса

Просмотр сообщений сеанса без блокировки.

Запросить

Сообщение запроса должно включать следующие свойства приложения.

Ключ Тип значения Обязательное поле Содержимое значения
Операция строка Да com.microsoft:peek-message
com.microsoft:server-timeout uint No Время ожидания ответа от сервера, на котором выполняется операция, в миллисекундах.

Текст запроса должен включать раздел amqp-value, содержащий схему со следующими элементами.

Ключ Тип значения Обязательное поле Содержимое значения
from-sequence-number длинный Да Порядковый номер, с которого следует начать просмотр.
message-count INT Да Максимальное число просматриваемых сообщений.
session-id строка Да ИД сеанса.

Response

Ответное сообщение запроса должно включать следующие свойства приложения.

Ключ Тип значения Обязательное поле Содержимое значения
statusCode INT Да Код ответа HTTP [RFC2616].

200: ОК — есть дополнительные сообщения.

204: No content — нет сообщений
statusDescription строка Нет Описание состояния.

Текст ответа должен включать раздел amqp-value, содержащий схему со следующими элементами.

Ключ Тип значения Обязательное поле Содержимое значения
messages Список схем Да Список сообщений, в котором каждая схема представляет сообщение.

Схема, представляющая сообщение, должна содержать следующие элементы.

Ключ Тип значения Обязательное поле Содержимое значения
message Массив байтов Да Сообщение с кодированием линии связи AMQP 1.0.

Установка состояния сеанса

Установка состояния сеанса.

Запросить

Сообщение запроса должно включать следующие свойства приложения.

Ключ Тип значения Обязательное поле Содержимое значения
Операция строка Да com.microsoft:set-session-state
com.microsoft:server-timeout uint No Время ожидания ответа от сервера, на котором выполняется операция, в миллисекундах.

Текст запроса должен включать раздел amqp-value, содержащий схему со следующими элементами.

Ключ Тип значения Обязательное поле Содержимое значения
session-id строка Да ИД сеанса.
session-state Массив байтов Да Непрозрачные двоичные данные.

Response

Ответное сообщение запроса должно включать следующие свойства приложения.

Ключ Тип значения Обязательное поле Содержимое значения
statusCode INT Да Код ответа HTTP [RFC2616].

200: ОК — операция выполнена успешно; в противном случае — сбой.
statusDescription строка Нет Описание состояния.

Получение состояния сеанса

Получение состояния сеанса.

Запросить

Сообщение запроса должно включать следующие свойства приложения.

Ключ Тип значения Обязательное поле Содержимое значения
Операция строка Да com.microsoft:get-session-state
com.microsoft:server-timeout uint No Время ожидания ответа от сервера, на котором выполняется операция, в миллисекундах.

Текст запроса должен включать раздел amqp-value, содержащий схему со следующими элементами.

Ключ Тип значения Обязательное поле Содержимое значения
session-id строка Да ИД сеанса.

Response

Ответное сообщение запроса должно включать следующие свойства приложения.

Ключ Тип значения Обязательное поле Содержимое значения
statusCode INT Да Код ответа HTTP [RFC2616].

200: ОК — операция выполнена успешно; в противном случае — сбой.
statusDescription строка Нет Описание состояния.

Текст ответа должен включать раздел amqp-value, содержащий схему со следующими элементами.

Ключ Тип значения Обязательное поле Содержимое значения
session-state Массив байтов Да Непрозрачные двоичные данные.

Перечисление сеансов

Перечисление сеансов в сущности обмена сообщениями.

Запросить

Сообщение запроса должно включать следующие свойства приложения.

Ключ Тип значения Обязательное поле Содержимое значения
Операция строка Да com.microsoft:get-message-sessions
com.microsoft:server-timeout uint No Время ожидания ответа от сервера, на котором выполняется операция, в миллисекундах.

Текст запроса должен включать раздел amqp-value, содержащий схему со следующими элементами.

Ключ Тип значения Обязательное поле Содержимое значения
last-updated-time TIMESTAMP Да Фильтр включает только сеансы, обновленные после указанного времени.
skip INT Да Пропуск определенного числа сеансов.
популярное INT Да Максимальное число сеансов.

Примечание.

Если задано значение DateTime.MaxValueLastUpdatedTime (в .NET), метод "Перечисление сеансов" возвращает все сеансы независимо от того, имеют ли они состояние или нет. DateTime.MaxValue в .NET не может существовать на других языках программирования. В таких случаях используйте метку времени, равную 253402300800000 миллисекундам эпохи(1 января 1970 г., 00:00 GMT), эквивалентную DateTime.MaxValue .NET.

Response

Ответное сообщение запроса должно включать следующие свойства приложения.

Ключ Тип значения Обязательное поле Содержимое значения
statusCode INT Да Код ответа HTTP [RFC2616].

200: ОК — есть дополнительные сообщения.

204: No content — нет сообщений
statusDescription строка Нет Описание состояния.

Текст ответа должен включать раздел amqp-value, содержащий схему со следующими элементами.

Ключ Тип значения Обязательное поле Содержимое значения
skip INT Да Количество пропущенных сеансов, если код состояния равен 200.
sessions-ids массив строк Да Массив идентификаторов, если код состояния равен 200.

Операции с правилами

Добавление правила

Запросить

Сообщение запроса должно включать следующие свойства приложения.

Ключ Тип значения Обязательное поле Содержимое значения
Операция строка Да com.microsoft:add-rule
com.microsoft:server-timeout uint No Время ожидания ответа от сервера, на котором выполняется операция, в миллисекундах.

Текст запроса должен включать раздел amqp-value, содержащий схему со следующими элементами.

Ключ Тип значения Обязательное поле Содержимое значения
rule-name строка Да Имя правила без учета имени подписки и раздела.
rule-description map Да Описание правила, как указано в следующем разделе.

Схема rule-description должна содержать следующие элементы, где элементы sql-filter и correlation-filter являются взаимоисключающими.

Ключ Тип значения Обязательное поле Содержимое значения
sql-filter map Да sql-filter, как указано в следующем разделе.
correlation-filter map Да correlation-filter, как указано в следующем разделе.
sql-rule-action map Да sql-rule-action, как указано в следующем разделе.

Схема sql-filter должна включать следующие элементы.

Ключ Тип значения Обязательное поле Содержимое значения
выражение строка Да Выражение фильтра SQL.

Схема correlation-filter должна содержать хотя бы один из следующих элементов.

Ключ Тип значения Обязательное поле Содержимое значения
correlation-id строка Нет
message-id строка Нет
до строка Нет
reply-to строка Нет
label строка Нет
session-id строка Нет
reply-to-session-id строка Нет
тип_содержимого строка Нет
свойства map No Карты служебная шина ServiceBusMessage.Properties

Схема sql-rule-action должна включать следующие элементы.

Ключ Тип значения Обязательное поле Содержимое значения
выражение строка Да Выражение действия SQL.

Response

Ответное сообщение запроса должно включать следующие свойства приложения.

Ключ Тип значения Обязательное поле Содержимое значения
statusCode INT Да Код ответа HTTP [RFC2616].

200: ОК — операция выполнена успешно; в противном случае — сбой.
statusDescription строка Нет Описание состояния.

Удаление правила

Запросить

Сообщение запроса должно включать следующие свойства приложения.

Ключ Тип значения Обязательное поле Содержимое значения
Операция строка Да com.microsoft:remove-rule
com.microsoft:server-timeout uint No Время ожидания ответа от сервера, на котором выполняется операция, в миллисекундах.

Текст запроса должен включать раздел amqp-value, содержащий схему со следующими элементами.

Ключ Тип значения Обязательное поле Содержимое значения
rule-name строка Да Имя правила без учета имени подписки и раздела.

Response

Ответное сообщение запроса должно включать следующие свойства приложения.

Ключ Тип значения Обязательное поле Содержимое значения
statusCode INT Да Код ответа HTTP [RFC2616].

200: ОК — операция выполнена успешно; в противном случае — сбой.
statusDescription строка Нет Описание состояния.

Получение правил

Запросить

Сообщение запроса должно включать следующие свойства приложения.

Ключ Тип значения Обязательное поле Содержимое значения
Операция строка Да com.microsoft:enumerate-rules
com.microsoft:server-timeout uint No Время ожидания ответа от сервера, на котором выполняется операция, в миллисекундах.

Текст запроса должен включать раздел amqp-value, содержащий схему со следующими элементами.

Ключ Тип значения Обязательное поле Содержимое значения
популярное INT Да Число получаемых правил на странице.
skip INT Да Число пропускаемых правил. Определяет начальный индекс (+1) списка правил.

Response

Ответное сообщение содержит следующие свойства.

Ключ Тип значения Обязательное поле Содержимое значения
statusCode INT Да Код ответа HTTP [RFC2616].

200: ОК — операция выполнена успешно; в противном случае — сбой.
rules Список схем Да Список правил. Каждое правило представлено сопоставлением.

Каждая запись карты в списке включает следующие свойства:

Ключ Тип значения Обязательное поле Содержимое значения
rule-description описанный объект Да com.microsoft:rule-description с описанным кодом AMQP 0x0000013700000004

com.microsoft.rule-description Сам по себе представляет собой описанный список. Имеет следующие свойства.

Указатель Тип значения Обязательное поле Содержимое значения
0 описанный список Да filter как указано в следующей таблице.
1 описанный список Да ruleAction как указано далее в этом разделе.
2 строка Да Имя правила.
3 TIMESTAMP Да метка времени.

filter может быть одного из приведенных ниже типов.

Имя дескриптора Код дескриптора Значение
com.microsoft:sql-filter:list 0x000001370000006 Фильтр SQL
com.microsoft:correlation-filter:list 0x000001370000009 Фильтр корреляции
com.microsoft:true-filter:list 0x000001370000007 Фильтр значений True, представляющий схему 1=1
com.microsoft:false-filter:list 0x000001370000008 Фильтр значений False, представляющий схему 1=0

com.microsoft:sql-filter:list представляет собой описанный список, который включает в себя:

Указатель Тип значения Обязательное поле Содержимое значения
0 строка Да Выражение фильтра SQL
1 INT Да всегда 20. Это целое число — это уровень совместимости фильтра SQL. Он указывает версию синтаксиса фильтра SQL.

com.microsoft:correlation-filter:list представляет собой описанный список, который включает в себя:

Индекс (если существует) Тип значения Содержимое значения
0 строка Идентификатор корреляции
1 строка Идентификатор сообщения
2 строка По
3 строка Получатель ответа
4 строка Этикетка
5 строка ИД сеанса
6 строка Ответ на идентификатор сеанса
7 строка Тип содержимого
8 Карта Сопоставление определенных приложением свойств

ruleAction может быть одного из приведенных ниже типов.

Имя дескриптора Код дескриптора Значение
com.microsoft:empty-rule-action:list 0x0000013700000005 Пустое правило действия: действие правила отсутствует
com.microsoft:sql-rule-action:list 0x0000013700000006 Действие правила SQL

com.microsoft:sql-rule-action:list представляет собой описанный список с двумя элементами.

Указатель Тип значения Обязательное поле Содержимое значения
0 строка Да Выражение действия правила SQL
1 INT Да всегда 20. Это целое число — это уровень совместимости фильтра SQL. Он указывает версию синтаксиса фильтра SQL.

Операции с отложенными сообщениями

Получение по порядковому номеру

Получение отложенных сообщений по порядковым номерам.

Запросить

Сообщение запроса должно включать следующие свойства приложения.

Ключ Тип значения Обязательное поле Содержимое значения
Операция строка Да com.microsoft:receive-by-sequence-number
com.microsoft:server-timeout uint No Время ожидания ответа от сервера, на котором выполняется операция, в миллисекундах.

Текст запроса должен включать раздел amqp-value, содержащий схему со следующими элементами.

Ключ Тип значения Обязательное поле Содержимое значения
sequence-numbers Массив длинных чисел Да Порядковые номера.
receiver-settle-mode ubyte Да Режим сопоставления получателя, как указано в AMQP Core 1.0.

Response

Ответное сообщение запроса должно включать следующие свойства приложения.

Ключ Тип значения Обязательное поле Содержимое значения
statusCode INT Да Код ответа HTTP [RFC2616].

200: ОК — операция выполнена успешно; в противном случае — сбой.
statusDescription строка Нет Описание состояния.

Текст ответа должен включать раздел amqp-value, содержащий схему со следующими элементами.

Ключ Тип значения Обязательное поле Содержимое значения
messages Список схем Да Список сообщений, в котором каждая схема представляет сообщение.

Схема, представляющая сообщение, должна содержать следующие элементы.

Ключ Тип значения Обязательное поле Содержимое значения
lock-token uuid Да Маркер блокировки, если значение receiver-settle-mode равно -1.
message Массив байтов Да Сообщение с кодированием линии связи AMQP 1.0.

Обновление состояния метода обработки

Обновление состояния метода обработки для отложенных сообщений. Эта операция поддерживает транзакции.

Запросить

Сообщение запроса должно включать следующие свойства приложения.

Ключ Тип значения Обязательное поле Содержимое значения
Операция строка Да com.microsoft:update-disposition
com.microsoft:server-timeout uint No Время ожидания ответа от сервера, на котором выполняется операция, в миллисекундах.

Текст запроса должен включать раздел amqp-value, содержащий схему со следующими элементами.

Ключ Тип значения Обязательное поле Содержимое значения
disposition-status строка Да Завершено

abandoned (прервано)

suspended (приостановлено)
lock-tokens Массив UUID Да Маркеры блокировки сообщения для обновления состояния метода обработки.
deadletter-reason строка Нет Если для состояния ликвидации задано значение "Приостановлено".
deadletter-description строка Нет Если для состояния ликвидации задано значение "Приостановлено".
properties-to-modify map No Список свойств сообщений в брокере служебной шины, подлежащих изменению.

Response

Ответное сообщение запроса должно включать следующие свойства приложения.

Ключ Тип значения Обязательное поле Содержимое значения
statusCode INT Да Код ответа HTTP [RFC2616].

200: ОК — операция выполнена успешно; в противном случае — сбой.
statusDescription строка Нет Описание состояния.

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

Сведения о служебной шине и AMQP см. по следующим ссылкам.