Обновлена 9 июля 2026 г. в 14:39
Руководство разработчика
Настоящее Руководство предназначено для разработчиков приложений, инженеров и других специалистов, взаимодействующих с TQE(MQ) для получения, обработки и отправки сообщений.
В Руководстве описаны функции API TQE(MQ).
В разделе описана спецификация API на основе протокола gRPC.
Примеры создания gRPC-клиента и выполнения запросов к очереди приведены в документах:
Сервер публикации сообщений брокера очередей.
Method Name | Request Type | Response Type | Description |
|---|---|---|---|
Produce | Публикация группы сообщений в очередь |
Запрос на публикацию группы сообщений в очередь.
Field | Type | Label | Description |
|---|---|---|---|
queue | string | Название очереди, в которую необходимо опубликовать сообщения | |
sharding_key | string | optional | Ключ шардирования. Используется для распределения данных в системе. При включенном режиме статического шардирования должен находиться в диапазоне идентификаторов бакетов карты распределения. |
messages | repeated | Набор сообщений | |
metadata | repeated | Произвольные данные в формате списка из пар ключ-значение |
Группа сообщений.
Field | Type | Label | Description |
|---|---|---|---|
routing_key | string | optional | Ключ маршрутизации сообщения (тип сообщения). Используется для фильтрации сообщений из очереди на потребителях |
deduplication_key | string | optional | Ключ дедупликации. Используется для проверки повторных сообщений. Если не указан, проверка не производится. |
payload | bytes | Произвольные данные в бинарном формате (тело сообщения) | |
metadata | repeated | Произвольные данные в формате списка из пар ключ-значение |
Ответ на публикацию группы сообщений.
Field | Type | Label | Description |
|---|---|---|---|
ids | uint64 | repeated | Идентификаторы сообщений |
is_duplicates | boolean | repeated | Флаги наличия дубликатов |
Запрос на рассылку сообщения на указанные шарды.
Field | Type | Label | Description |
|---|---|---|---|
queue | string | Название очереди, в которую необходимо опубликовать сообщение | |
routing_key | string | optional | Ключ маршрутизации сообщения (тип сообщения). Используется для фильтрации сообщений из очереди на потребителях. |
deduplication_key | string | optional | Ключ дедупликации. Используется для проверки повторных сообщений. Если не указан, проверка не производится. |
payload | bytes | Произвольные данные в бинарном формате (тело сообщения) | |
metadata | repeated | Произвольные данные в формате списка пар ключ-значение. | |
replicasets | string | repeated | Список названий наборов реплик, на которые нужно опубликовать сообщение. По умолчанию рассылка происходит на все шарды. |
timeout | uint64 | optional | Максимальное время рассылки сообщения |
Ответ на рассылку сообщения.
Field | Type | Label | Description |
|---|---|---|---|
code | uint32 | Код завершения рассылки: 0 - Успешная публикация 1 - Ошибка на роутере 2 - Ошибка на наборе реплик | |
error | string | optional | Сообщение об ошибке |
replicasets | repeated | Набор ответов с шардов |
Field | Type | Label | Description |
|---|---|---|---|
key | |||
value |
Ответ набора реплик на публикацию сообщения.
Field | Type | Label | Description |
|---|---|---|---|
success | Сообщение об успешной публикации | ||
error | Сообщение об ошибке публикации |
Сообщение об успешной публикации.
Field | Type | Label | Description |
|---|---|---|---|
id | uint64 | Идентификатор сообщения, добавленного в очередь |
Сообщение об ошибке публикации.
Field | Type | Label | Description |
|---|---|---|---|
code | uint32 | Код ошибки | |
message | string | Сообщение об ошибке |
Сервер подписок на сообщения брокера очередей.
Method Name | Request Type | Response Type | Description |
|---|---|---|---|
Subscribe | Subscription Notifications stream | Подписка на сообщения с фильтрацией |
Поток запросов на подписку.
Field | Type | Label | Description |
|---|---|---|---|
subscribe_request | Запрос на подписку | ||
commit_request | Запрос на обновление курсора персистентной подписки |
Запрос на подписку.
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 в запросе. |
Запрос на обновление курсора персистентной подписки.
Field | Type | Label | Description |
|---|---|---|---|
cursor | string | Указатель на последнее обработанное сообщение в очереди. При подписке необходимо выполнять обновление курсора как минимум для последнего сообщения из каждого пакета сообщений. При этом можно обновлять курсор и для отдельных сообщений, соблюдая это правило. |
Поток ответов подписки.
Field | Type | Label | Description |
|---|---|---|---|
notifications | Сообщения в стриме подписки | ||
commit_response | Ответ на обновление состояния подписки |
Сообщение в стриме подписки.
Field | Type | Label | Description |
|---|---|---|---|
notifications | repeated | Новые сообщения в очереди с курсорами |
Уведомление клиента о новых сообщениях в очереди.
Field | Type | Label | Description |
|---|---|---|---|
cursor | string | Строка-указатель сообщения | |
message | Сообщение |
Сообщение в очереди.
Field | Type | Label | Description |
|---|---|---|---|
id | uint64 | Идентификатор сообщения. Заполняется автоматически при записи сообщения в очередь. | |
queue | string | Название очереди, в которую необходимо опубликовать сообщение | |
routing_key | string | optional | Ключ маршрутизации сообщения (тип сообщения). Используется для фильтрации сообщений из очереди на потребителях. |
sharding_key | string | optional | Ключ шардирования. Используется для распределения данных в системе. При включенном режиме статического шардирования должен находиться в диапазоне идентификаторов бакетов карты распределения. |
deduplication_key | string | optional | Ключ дедупликации. Используется для проверки повторных сообщений. Если не указан, проверка не производится. |
payload | bytes | Произвольные данные в бинарном формате (тело сообщения) | |
metadata | repeated | Произвольные данные в формате списка пар ключ-значение | |
timestamp | int64 | Время вставки сообщения в очередь в наносекундах |
Пара ключ-значение.
Field | Type | Label | Description |
|---|---|---|---|
key | string | Ключ пары | |
value | string | Значение пары |
Ответ на обновление состояния подписки.
Field | Type | Label | Description |
|---|---|---|---|
cursor | string | Обновленная строка-указатель сообщения |
Поток запросов к группе потребителей.
Field | Type | Label | Description |
|---|---|---|---|
consume_request | Запрос к группе потребителей | ||
commit_request | Запрос на подтверждение обработки сообщения |
Поток ответов к группе потребителей.
Field | Type | Label | Description |
|---|---|---|---|
consume_response | Сообщение в стриме подписки | ||
commit_response | Ответ на подтверждение обработки сообщения |
Запрос в группу потребителей.
Field | Type | Label | Description |
|---|---|---|---|
group_id | string | Идентификатор группы потребителей. Если группы с указанным идентификатором не существует, Оркестратор создает новую группу. | |
queue | string | Название очереди | |
routing_key | string | optional | Ключ фильтрации |
ttl | float | optional | Время жизни состояния подписки |
Ответ с потребленными сообщениями группы.
Field | Type | Label | Description |
|---|---|---|---|
notifications | repeated | Список потребленных сообщений |
Запрос на подтверждение обработки сообщения группы потребителей.
Field | Type | Label | Description |
|---|---|---|---|
cursor | string | Строка-указатель на сообщение |
Ответ на подтверждение обработки сообщения группы потребителей.
Field | Type | Label | Description |
|---|---|---|---|
cursor | string | Обновленная строка-указатель сообщения |
Уведомление о сообщении в группу потребителей.
Field | Type | Label | Description |
|---|---|---|---|
cursor | string | Строка-указатель на текущее сообщение | |
message | Сообщение |