Наблюдение и список объектов
В INVOICES уже несколько объектов: invoice-ord_8w2k.pdf с описанием и content-type, крупный invoice-ord_9x3m.pdf из многих фрагментов и ссылка label-ord_8w2k.png на первый счёт. Для get нужно знать имя. Но analytics не знает имён заранее: ему нужно обнаружить содержимое и узнавать о новых объектах сразу после записи.
Для этого есть две операции. List получает снимок всех текущих объектов, watch передаёт обновления метаданных по мере возникновения. Так analytics узнаёт о счёте сразу после put от order-svc, не зная заранее содержимого бакета.
List возвращает снимок
List однократно возвращает все неудалённые объекты. Он не остаётся открытым и не передаёт последующие изменения: отвечает на вопрос о текущем содержимом и завершается.
Выполните его для INVOICES:
- CLI
#!/bin/bash
# List every live object in the INVOICES bucket. `analytics` does not know
# the object names ahead of time, so it lists the bucket to discover what
# is there right now. A list is a one-time snapshot: it reads metadata for
# each object and returns — it does not stay open or stream changes.
#
# A list reads metadata only, never chunks, so it is cheap even when the
# objects themselves are large. Soft-deleted objects are filtered out: the
# list shows only what is really in the bucket.
nats object ls INVOICES
# Expected output: one row per object, metadata only, e.g.
#
# Name Size Time
# invoice-ord_8w2k.pdf 18 KiB 2026-05-22 10:14:22
# invoice-ord_9x3m.pdf 3.0 MiB 2026-05-22 10:15:30
# label-ord_8w2k.png 0 B 2026-05-22 10:15:01
#
# An empty bucket is not an error — it lists zero rows. In client code an
# empty bucket surfaces as a "no objects found" condition; treat it as the
# valid answer "nothing here yet", not as a failure.
Результат содержит по записи для invoice-ord_8w2k.pdf, invoice-ord_9x3m.pdf и label-ord_8w2k.png. В каждой — метаданные: имя, размер, число фрагментов, описание, время изменения. Байтов нет. List читает только метаданные; можно перечислить гигабайтные счета без передачи содержимого объектов.
Мягко удалённые объекты пропускаются. Когда order-svc удаляет счёт, ставится признак удаления и очищаются фрагменты, но метаданные остаются как маркер. List отфильтровывает их, показывая только существующие объекты. Механизм рассматривается в разделе Внутреннее устройство; здесь важно поведение.
Пустой бакет не является ошибкой. Список нового бакета возвращает пустой результат. Клиентские библиотеки сообщают отдельное состояние отсутствия объектов, которое следует понимать как ноль результатов, а не неполадку. Пример приведён ниже.
Watch передаёт изменения метаданных
Watch — непрерывный аналог list: открывает поток метаданных и передаёт обновление при каждом изменении объекта, будь то первый put, повторный put или удаление. Так analytics следит за бакетом без циклического вызова list.
Запустите analytics для наблюдения за INVOICES в отдельном терминале и оставьте работать:
- CLI
#!/bin/bash
# Watch the INVOICES bucket for changes. This is the `analytics` service:
# it wants to learn about every new invoice the instant `order-svc` puts
# it, with no polling.
#
# A watch delivers metadata updates in order, one per change (put, re-put,
# or delete). When it has caught up with everything already in the bucket,
# it delivers a single nil sentinel to mark the snapshot/live boundary,
# then streams live changes until you stop it (Ctrl-C). The CLI consumes
# the sentinel for you and keeps printing. Run this in its own terminal.
nats object watch INVOICES
# Expected output: one line per existing object (the catch-up snapshot),
# then it waits. Leave it running and, from another terminal, have
# `order-svc` put the packing slip for the same order:
#
# echo "PACK ord_8w2k: 3 items" | \
# nats object put INVOICES --name packing-slip-ord_8w2k.txt
#
# The watch prints the live metadata update the moment the put lands:
#
# [2026-05-22 10:16:40] PUT INVOICES > packing-slip-ord_8w2k.txt
#
# Each update carries the object's metadata — name, size, chunk count,
# digest — never the chunk bytes. To read the data, issue a separate get.
Обновления приходят в порядке записи бакетом, поэтому позднее состояние не опережает раннее. После получения всего уже существующего watch передаёт один маркер nil — пустое обновление, обозначающее переход к текущим изменениям. CLI обрабатывает его автоматически и продолжает вывод. В коде нужно распознать границу и продолжить чтение.
В другом терминале пусть order-svc запишет упаковочный лист того же заказа:
echo "PACK ord_8w2k: 3 items" | nats object put INVOICES --name packing-slip-ord_8w2k.txt
Обновление появляется сразу после put, без опроса и задержки. analytics узнаёт о packing-slip-ord_8w2k.txt, как только order-svc сохраняет его.
Обновление содержит только метаданные объекта: имя, размер, число фрагментов и хеш. Байты через watch не передаются. Это его важнейшее свойство.
Watch передаёт метаданные без содержимого
Метаданные и фрагменты объекта находятся в разных темах. Watch подписывается на метаданные, поэтому каждое обновление — запись ObjectInfo, а не байты объекта.
Это позволяет наблюдать недорого. analytics следит за счетами на 3 МБ и медиафайлами на 100 МБ без передачи их содержимого. Он узнаёт об изменении и свойствах; при необходимости запрашивает данные отдельным get.
Шаблон двухэтапный: узнать изменение через watch, затем получить нужные байты через get. Для панели analytics может хватить метаданных без чтения содержимого. Сервис повторной обработки, наоборот, получает каждый новый объект. Наблюдение одинаково, различается лишь выполнение второго шага.
Это отличие от наблюдения в KV: там передаётся само значение небольшого ключа. Объект может занимать гигабайты, поэтому watch оставляет загрузку вам. См. Ключи и значения → Наблюдение. Для объектов watch сообщает об изменении, get возвращает байты.
Дополнительные параметры позволяют воспроизводить историю, игнорировать удаления или пропускать начальный снимок ради только новых обновлений. Они настраивают тот же поток метаданных. Все параметры приведены в справочнике; здесь достаточно стандартного поведения.
Подводные камни
При чтении неизвестного содержимого бакета распространены две ошибки: непонимание результата list и данных watch.
Watch передаёт метаданные, а не байты. Обновление — запись ObjectInfo с именем, размером, числом фрагментов и хешем. Сервис, принимающий её за файл и ожидающий полезную нагрузку на 100 МБ, получит лишь метаданные и сломается. Используйте два шага: watch сообщает, что изменилось, get читает нужные объекты. Не ждите содержимого от наблюдения.
Наблюдайте, затем выполняйте get только при необходимости:
- CLI
#!/bin/bash
# Watch tells you WHAT changed; get gives you the bytes. A watch update is
# an ObjectInfo record — name, size, chunk count, digest — and never the
# object's data. The chunks live on a separate subject, so the bytes do
# not ride the watch. This keeps watch cheap even for gigabyte objects.
#
# The pattern is two steps: watch to learn what changed, then get only the
# objects whose bytes you actually need. Do not expect the data to arrive
# on the watch.
#
# Step 1 — watch for changes (run in its own terminal, leave it running):
nats object watch INVOICES
# The watch prints a metadata line when `order-svc` puts a new object,
# e.g.
#
# [2026-05-22 10:16:40] PUT INVOICES > packing-slip-ord_8w2k.txt
#
# Step 2 — now that you know what changed, get the bytes you want. Run
# this from another terminal for the object the watch reported. Without
# --output the file lands in the current directory under the object's name;
# --output writes it to a path you choose (the directory must exist):
nats object get INVOICES packing-slip-ord_8w2k.txt --output ./packing-slip-ord_8w2k.txt
# In client code the loop reads the watch, branches on the nil sentinel
# (the snapshot/live boundary) and keeps going, then issues a get only for
# the objects it needs:
#
# for info in watcher:
# if info is None: # caught-up sentinel; keep reading
# continue
# if needs_bytes(info.name): # only fetch what you actually use
# data = bucket.get_bytes(info.name)
#
# Reading the bytes directly off the watch update would find only
# metadata. Use watch to learn what, get to fetch the data.
Пустой бакет даёт пустой результат, а не ошибку. List без живых объектов возвращает ноль записей. Библиотеки выделяют состояние отсутствия объектов; если считать его фатальным, программа упадёт на пустом бакете или после удаления всех объектов. Принимайте пустой список как корректный ответ «пока ничего нет». Отсутствие объектов и отсутствие самого бакета — разные состояния; проблема лишь во втором.
Текущее состояние
Теперь у вас есть:
- Список
INVOICES: метаданныеinvoice-ord_8w2k.pdf,invoice-ord_9x3m.pdfиlabel-ord_8w2k.png, без мягко удалённых объектов. analytics, наблюдающий за бакетом и получивший текущее обновление добавленногоpacking-slip-ord_8w2k.txt.- Двухэтапная модель: watch сообщает об изменении, get получает байты.
Что дальше
Вы использовали put, get, фрагменты, метаданные, ссылки, list и watch. Следующая страница показывает поток OBJ_INVOICES, его темы фрагментов и метаданных, свёртку до одной текущей записи на объект и устройство мягкого удаления.
Переходите к странице Внутреннее устройство.
См. также
- Ключи и значения → Наблюдение — наблюдение, напрямую передающее значения ключей.
- Внутреннее устройство — тема метаданных и мягкое удаление.
- Справочник — все параметры наблюдения.