Перейти к основному содержимому
Версия: 2.15 (последняя)

Заголовки API JetStream

Полный справочник заголовков, используемых в операциях JetStream: при публикации и доставке сообщений, а также для различных возможностей JetStream.

Заголовки публикации сообщений​

Заголовки публикации сообщений в потоки JetStream.

Идентификация и дедупликация сообщений​

ЗаголовокЗначениеОписание
Nats-Msg-IdУникальный идентификатор сообщенияУникальный идентификатор сообщения для дедупликации. Сообщения с одинаковым идентификатором в пределах окна дедупликации отклоняются как дубликаты.
Nats-Expected-Last-Msg-IdИдентификатор сообщенияСообщение сохраняется только при совпадении идентификатора последнего сообщения с этим значением

Заголовки ожидаемого состояния​

Эти заголовки проверяют ожидаемое состояние при публикации. Если условия не выполнены, публикация завершается ошибкой.

ЗаголовокЗначениеОписание
Nats-Expected-StreamИмя потокаПроверяет, что сообщение публикуется в ожидаемый поток
Nats-Expected-Last-SequenceПорядковый номерСообщение сохраняется только при совпадении последнего порядкового номера потока с этим значением
Nats-Expected-Last-Subject-SequenceПорядковый номерСообщение сохраняется только при совпадении последнего порядкового номера этого субъекта с этим значением
Nats-Expected-Last-Subject-Sequence-SubjectСубъектЗадаёт субъект для проверки ожидаемого последнего порядкового номера субъекта

Свёртка сообщений​

ЗаголовокЗначениеОписание
Nats-Rollupsub или allУказывает, что сообщение должно заменить предыдущие. sub заменяет все предыдущие сообщения того же субъекта, all — все сообщения потока
Nats-Schedule-RollupСтрока

Размер сообщения​

ЗаголовокЗначениеОписание
Nats-Msg-SizeРазмер в байтахУказывает размер полезной нагрузки сообщения

TTL сообщения​

ЗаголовокЗначениеОписание
Nats-TTLСтрока длительности (например, 60s, 5m)Время жизни сообщения. По истечении этого срока сообщение автоматически удаляется

Операции со счётчиками​

ЗаголовокЗначениеОписание
Nats-IncrЧислоЗначение приращения для операций со счётчиками
Nats-Counter-SourcesJSONИсточники значений счётчиков в формате JSON

Пакетные операции​

Заголовки атомарной пакетной публикации:

ЗаголовокЗначениеОписание
Nats-Batch-IdИдентификатор пакетаУникальный идентификатор пакета
Nats-Batch-SequenceПорядковый номерПорядковый номер внутри пакета
Nats-Batch-Commit1Помечает последнее сообщение пакета, запуская атомарную фиксацию

Запланированные сообщения​

Заголовки доставки сообщений по расписанию:

ЗаголовокЗначениеОписание
Nats-ScheduleВыражение cronШаблон расписания доставки сообщений
Nats-Schedule-Time-ZoneСтрока
Nats-Schedule-TTLСтрока длительности (например, 60s, 5m)Время жизни расписания
Nats-Schedule-TargetСубъектЦелевой субъект доставки по расписанию
Nats-Schedule-SourceСубъектИсходный субъект доставки сообщений по расписанию
Nats-SchedulerИдентификатор планировщикаИдентификатор планировщика
Nats-Schedule-NextВременная метка RFC3339 или purgeВремя следующего запуска по расписанию или указание очистки

Заголовки доставки сообщений​

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

Информация о потоке​

ЗаголовокЗначениеОписание
Nats-Last-StreamПорядковый номерПоследний порядковый номер потока на момент доставки
Nats-StreamИмя потокаИмя потока, из которого получено сообщение
Nats-SequenceПорядковый номерПорядковый номер сообщения в потоке
Nats-Time-StampВременная метка RFC3339Временная метка сохранения сообщения
Nats-SubjectСубъектИсходный субъект публикации сообщения
Nats-Last-SequenceПорядковый номерПоследний порядковый номер в потоке на момент доставки этого сообщения
Nats-UpTo-SequenceПорядковый номерВерхняя граница порядкового номера для пакетной доставки
Nats-Stream-IdentityСтрокаJSStreamIdentity — идентификатор потока, используемый для отклонения создания потребителя при несовпадении и возвращаемый в ответах на создание и сброс потребителя.

Информация о потребителе​

ЗаголовокЗначениеОписание
Nats-Last-ConsumerПорядковый номерПоследний доставленный порядковый номер потребителя
Nats-Consumer-StalledСубъект ответаУказывает, что потребитель приостановлен, и содержит счётчик доставки

Заголовки pull-запросов​

Заголовки ответов на pull-запросы:

ЗаголовокЗначениеОписание
Nats-Num-PendingКоличествоЧисло ожидающих сообщений потребителя
Nats-Pending-MessagesКоличествоЧисло ожидающих сообщений для pull-запроса
Nats-Pending-BytesРазмер в байтахЧисло ожидающих байтов для pull-запроса
Nats-Pin-IdNUIDИдентификатор закрепления приоритетной группы для pull-запроса

Информация об источнике и зеркале​

ЗаголовокЗначениеОписание
Nats-Stream-SourceИнформация об источнике потокаИнформация об исходном потоке в формате: имя-потока > номер > субъект

Тип ответа​

ЗаголовокЗначениеОписание
Nats-Response-TypeСтрока типа ответаТип отправляемого ответа

Заголовки API​

Заголовки запросов и ответов API JetStream.

ЗаголовокЗначениеОписание
Nats-Required-Api-LevelНомер уровня APIМинимальный уровень API, необходимый для запроса

Заголовки маркеров​

Заголовки для обозначения специальных типов сообщений в потоках.

ЗаголовокЗначениеОписание
Nats-Marker-ReasonMaxAge, Purge или RemoveПричина маркера: MaxAge, Purge или Remove

Заголовки аутентификации и авторизации​

Заголовки auth callout и авторизации.

ЗаголовокЗначениеОписание
Nats-Request-InfoИнформация о клиенте в формате JSONИнформация об авторизации клиента для запроса
Nats-Server-XkeyСтрока X-KeyX-Key сервера для зашифрованных запросов auth callout

Заголовки трассировки сообщений​

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

ЗаголовокЗначениеОписание
Nats-Trace-DestСубъектСубъект назначения трассировки сообщений
Nats-Trace-HopЧисло переходовЧисло переходов трассировки
Nats-Trace-Origin-AccountИмя аккаунтаИсходный аккаунт трассировки сообщений
Nats-Trace-OnlyЛогический флагУказывает режим только трассировки (сообщение не доставляется)

Заголовки хранилища ключей и значений​

Заголовки хранилища ключей и значений NATS, построенного на JetStream.

ЗаголовокЗначениеОписание
KV-OperationPUT, DEL или PURGEТип операции KV: PUT, DEL или PURGE

Примеры использования​

Публикация с дедупликацией​

Nats-Msg-Id: unique-message-123

Публикация с проверкой ожидаемого состояния​

Nats-Expected-Last-Sequence: 42
Nats-Expected-Stream: my-stream

Пакетная публикация​

Nats-Batch-Id: batch-456
Nats-Batch-Sequence: 1

Для последнего сообщения пакета:

Nats-Batch-Id: batch-456
Nats-Batch-Sequence: 10
Nats-Batch-Commit: 1

Запланированное сообщение​

Nats-Schedule: 0 */5 * * * *
Nats-Schedule-TTL: 24h
Nats-Schedule-Target: notifications.email

Примечания​

  • Имена заголовков чувствительны к регистру
  • Некоторые заголовки устанавливаются сервером автоматически; клиентам не следует задавать их вручную
  • Заголовки с префиксом Nats-Expected- используются для оптимистического управления конкурентным доступом
  • Заголовок Nats-Rollup используется совместно с настройкой потока MaxMsgsPerSubject
  • Пакетные операции требуют успеха всех сообщений пакета, иначе весь пакет отклоняется
  • Операции со счётчиками атомарны и поддерживают распределённые счётчики в кластерных потоках