Обновлена 28 апреля 2026 г. в 08:17

Справочники

Документ рассматривает функции API для Tarantool Queue Enterprise, функциональность MQ (далее по тексту – TQE(MQ))

API

В этом разделе описана спецификация API на основе протокола gRPC.

Примеры создания gRPC-клиента и выполнения запросов к очереди приведены в документах:

Producer

Сервер публикации сообщений брокера очередей.

Method Name	Request Type	Response Type	Description
Produce	ProduceRequest	ProduceResponse	Публикация группы сообщений в очередь

ProduceRequest

Запрос на публикацию группы сообщений в очередь.

Field	Type	Label	Description
queue	string		Название очереди, в которой необходимо опубликовать сообщения
sharding_key	string	optional	Ключ шардирования. Необходим для распределения данных в системе. При включенном режиме статического шардирования должен быть в диапазоне идентификаторов бакетов карты распределения
messages	ProduceMessage	repeated	Набор сообщений
metadata	Pair	repeated	Произвольные данные в формате списка из пар ключ-значение.

ProduceMessage

Группа сообщений.

Field	Type	Label	Description
routing_key	string	optional	Ключ маршрутизации сообщения (тип сообщения). Необходим для фильтрации сообщений из очереди на потребителях
deduplication_key	string	optional	Ключ дедупликации. Необходим для проверки повторных сообщений. Если не указан, то проверка не производится
payload	bytes		Произвольные данные в бинарном формате (тело сообщения)
metadata	Pair	repeated	Произвольные данные в формате списка из пар ключ-значение.

ProduceResponse

Ответ на публикацию группы сообщений.

Field	Type	Label	Description
ids	uint64	repeated	Идентификаторы сообщений
is_duplicates	boolean	repeated	Флаги наличия дубликатов

BroadcastRequest

Запрос на рассылку сообщения на указанные шарды.

Field	Type	Label	Description
queue	string		Название очереди, в которую необходимо опубликовать сообщение
routing_key	string	optional	Ключ маршрутизации сообщения (тип сообщения) необходим для фильтрации сообщений из очереди на потребителях
deduplication_key	string	optional	Ключ дедупликации необходим для проверки повторных сообщений, если не указан, то проверка не производится
payload	bytes		Произвольные данные в бинарном формате, содержит тело сообщения
metadata	Pair	repeated	Произвольные данные в формате списка из пар ключ-значение.
replicasets	string	repeated	Список с названиями набором реплик, на которые нужно опубликовать сообщение. По умолчанию рассылка происходит на все шарды.
timeout	uint64	optional	Максимальное время на рассылку сообщения

BroadcastResponse

Ответ на рассылку сообщения.

Field	Type	Label	Description
code	uint32		Код завершения рассылки: `0` - Успешная публикация `1` - Ошибка на роутере `2` - Ошибка на наборе реплик
error	string	optional	Сообщение об ошибке
replicasets	BroadcastResponse.ReplicasetsEntry	repeated	Набор ответов с шардов

BroadcastResponse.ReplicasetsEntry

Field	Type	Label	Description
key	string
value	ReplicasetResponse

ReplicasetResponse

Ответ набора реплик на публикацию сообщения.

Field	Type	Label	Description
success	Success		Сообщение об успешной публикации
error	Error		Сообщение об ошибке публикации

Success

Сообщение об успешной публикации.

Field	Type	Label	Description
id	uint64		Идентификатор сообщения добавленного в очередь

Error

Сообщение об ошибке публикации.

Field	Type	Label	Description
code	uint32		Код ошибки
message	string		Сообщение об ошибке

ConsumerService

Сервер подписок на сообщения брокера очередей.

Method Name	Request Type	Response Type	Description
Subscribe	SubscriptionRequest	Subscription Notifications stream	Подписка на сообщения с фильтром

SubscriptionStreamRequest

Поток запросов подписки.

Field	Type	Label	Description
subscribe_request	SubscriptionRequest		Запрос на подписку
commit_request	CommitRequest		Запрос на обновление курсора персистентной подписки

SubscriptionRequest

Запрос на подписку.

Field	Type	Label	Description
queue	string		Название очереди
routing_key	string	optional	Ключ маршрутизации сообщения (тип сообщения). Необходим для фильтрации сообщений из очереди. Если не указан, то подписка происходит на все типы сообщений в очереди
cursor	string	optional	Опциональная строка указатель на последнее полученное сообщение. Необходим для возможности получения истории сообщений или восстановления работы потребителя после сбоя или при истечении времени, указанного в `ttl` в случае персистентной подписки. Если значение не указано -- подписка с текущего момента. Значение как пустая строка -- подписка с начала очереди. Значение указано -- подписка с указанного сообщения в очереди
sharding_key	string	optional	Ключ шардирования. Необходим для распределения данных в системе. Если не указан, то подписка происходит на все типы сообщений в очереди. При включенном режиме статического шардирования должен быть в диапазоне идентификаторов бакетов карты распределения
sharding_keys	string	repeated	Ключи шардирования позволяют производить фильтрацию по нескольким ключам шардирования в рамках одной подписки. При включенном режиме статического шардирования должны быть в диапазоне идентификаторов бакетов карты распределения
consume_id	string	optional	Уникальный ключ идентификации подписки. По значению этого параметра система может создать персистентную подписку и восстановить сохраненное состояние персистентной подписки, чтобы возобновить передачу сообщений с последней сохраненной позиции
ttl	float		Время жизни состояния подписки. Параметр используется совместно с параметром `consume_id` для управления временем жизни подписки. Подписка очищается вместе со всем состоянием по прошествии времени, указанного в `ttl`, при отключении от подписки. При повторном подключении запросом `SubscriptionRequest` после истечения `ttl` клиенту с тем же значением `consume_id` необходимо учитывать значение параметра `cursor`
restore	boolean	optional	Позволяет игнонировать курсор при восстановлении подписки. Если указано значение `false` (используется по умолчанию), то система требует точного совпадения переданного в запросе курсора с сохраненным значением, и при несовпадении операция завершится ошибкой. При значении `true` система начнет или возобновит подписку с позиции курсора в хранилище, игнорируя значение `cursor` в запросе

CommitRequest

Запрос на обновление курсора персистентной подписки.

Field	Type	Label	Description
cursor	string		Указатель на последнее обработанное сообщение в очереди. При подписке необходимо выполнять обновление курсора как минимум для последнего сообщения из каждого пакета сообщений. При этом можно обновлять курсор и для отдельных сообщений, соблюдая это правило

SubscriptionStreamResponse

Поток ответов подписки.

Field	Type	Label	Description
notifications	SubscriptionNotifications		Сообщения в стриме подписки
commit_response	CommitResponse		Ответ на обновление состояния подписки

SubscriptionNotifications

Сообщение в стриме подписки.

Field	Type	Label	Description
notifications	SubscriptionNotification	repeated	Новые сообщения в очереди с курсорами

SubscriptionNotification

Уведомление клиента о новых сообщениях в очереди.

Field	Type	Label	Description
cursor	string		Строка-указатель сообщения
message	QueueMessage		Сообщение

QueueMessage

Сообщение в очереди.

Field	Type	Label	Description
id	uint64		Идентификатор сообщения. Заполняется автоматически при записи сообщения в очередь
queue	string		Название очереди, в которую необходимо опубликовать сообщение
routing_key	string	optional	Ключ маршрутизации сообщения (тип сообщения). Необходим для фильтрации сообщений из очереди на потребителях
sharding_key	string	optional	Ключ шардирования. Необходим для распределения данных в системе. При включенном режиме ссылка должен быть в диапазоне идентификаторов бакетов карты распределения
deduplication_key	string	optional	Ключ дедупликации. Необходим для проверки повторных сообщений. Если не указан, то проверка не производится
payload	bytes		Произвольные данные в бинарном формате (тело сообщения)
metadata	Pair	repeated	Произвольные данные в формате списка из пар ключ-значение.
timestamp	int64		Время вставки сообщения в очередь в наносекундах

Pair

Пара ключ-значение.

Field	Type	Label	Description
key	string		Ключ пары
value	string		Значение пары

CommitResponse

Ответ на обновление состояния подписки.

Field	Type	Label	Description
cursor	string		Обновленная строка-указатель сообщения.

ConsumeGroupStreamRequest

Поток запросов к группе потребителей.

Field	Type	Label	Description
consume_request	ConsumeGroupRequest		Запрос к Consumer Group
commit_request	CommitGroupRequest		Запрос на подтверждение обработки сообщения

ConsumeGroupStreamResponse

Поток ответов к группе потребителей.

Field	Type	Label	Description
consume_response	ConsumeGroupResponse		Сообщение в стриме подписки
commit_response	CommitGroupResponse		Ответ на подтверждение обработки сообщения

ConsumeGroupRequest

Запрос в группу потребителей.

Field	Type	Label	Description
group_id	string		Идентификатор группы потребителей. Если группы с указанным идентификатором не существует - Оркестратор создаст новую группу
queue	string		Название очереди
routing_key	string	optional	Опциональный ключ фильтрации
ttl	float	optional	Время жизни состояния подписки

ConsumeGroupResponse

Ответ с потребленными сообщениями группы.

Field	Type	Label	Description
notifications	ссылка	repeated	Список потребленных сообщений

CommitGroupRequest

Запрос на подтверждение обработки сообщения группы потребителей.

Field	Type	Label	Description
cursor	string		Строка-указатель на сообщение

CommitGroupResponse

Ответ на подтверждение обработки сообщения группы потребителей.

Field	Type	Label	Description
cursor	string		Обновленная строка-указатель сообщения

ConsumeGroupNotification{heading(ConsumeGroupNotification)[id=api-consumegroupnotification]}

Уведомление о сообщении в группу потребителей.

Field	Type	Label	Description
cursor	string		Строка-указатель на текущее сообщение
message	QueueMessage		Сообщение

Не нашли ответа?Напишите нам

Содержание
API