Перейти к основному содержимому

Метаданные и ссылки

Объект содержит не только байты. Пока invoice-ord_8w2k.pdf — лишь имя и содержимое: для любых сведений warehouse должен прочитать файл целиком. Добавим понятное описание, HTTP-подобные заголовки и произвольные метаданные. Затем изучим ссылки, позволяющие одному объекту представлять другой.

Счета с предыдущих страниц остаются в INVOICES; держите терминал открытым.

Каждый объект имеет ObjectInfo​

При put записываются фрагменты, затем итоговые метаданные всего объекта — запись ObjectInfo. Часть полей вычисляется автоматически: размер в байтах, число фрагментов, SHA-256, время изменения и признак удаления. Три поля задаёте вы.

Первое — описание, понятная человеку подпись объекта. Второе — заголовки, пары ключ/значение в формате HTTP, как заголовки сообщения NATS. Третье — метаданные, произвольные строковые пары для нужд приложения.

Задайте их при put. order-svc сохраняет счёт с описанием и заголовком content-type, чтобы читатель узнал о PDF до загрузки байтов:

#!/bin/bash
# Put an invoice with metadata attached. Beyond the bytes, every object
# carries an ObjectInfo record. Three of its fields are yours to set:
# --description a human label for the object
# -H / --header HTTP-style headers (repeatable)
# and a free-form metadata map, set in the client libraries.
#
# Here `order-svc` stores invoice-ord_8w2k.pdf with a description and a
# content-type header so a reader knows the bytes are a PDF without
# downloading them first.
nats object put INVOICES invoice-ord_8w2k.pdf \
--description "Invoice for order ord_8w2k" \
--header "content-type:application/pdf"

# The metadata travels in the one metadata message that follows the
# chunks, so it costs nothing extra to read it back later — it is already
# beside the object, not in a separate lookup.

Имя и байты не изменились: это прежний invoice-ord_8w2k.pdf, теперь с описанием и заголовком. Метаданные находятся в том же завершающем сообщении, без отдельной дополнительной записи или операции чтения.

Чтение метаданных​

Чтение метаданных не получает байты объекта. Последний ObjectInfo каждого имени хранится одним небольшим сообщением, поэтому warehouse может узнать свойства файла без его загрузки.

#!/bin/bash
# Read the ObjectInfo for one object. `nats object info` prints the
# metadata you set (description, headers, metadata map) alongside the
# fields the store computed for you: size, chunk count, the SHA-256
# digest, the modification time, and whether the object is deleted.
#
# `warehouse` reads this before fetching the bytes — the content-type
# header tells it the object is a PDF, and the size tells it how big the
# get will be.
nats object info INVOICES invoice-ord_8w2k.pdf

# Expected output (abridged):
#
# Object information for INVOICES > invoice-ord_8w2k.pdf
#
# Size: 12 KiB
# Modified: 2026-05-22 10:14:22
# Chunks: 1
# Digest: SHA-256=...
# Description: Invoice for order ord_8w2k
# Headers: content-type: application/pdf

В выводе описание и заголовок находятся рядом с вычисленными размером, числом фрагментов, хешем и временем изменения. warehouse читает content-type и размер, затем решает, нужны ли байты. Метаданные служат недорогим указателем содержимого бакета; крупные данные читаются лишь при необходимости.

Метаданные описывают текущий объект, а не историю его версий. Каждый повторный put заменяет их, оставляя последние. История ревизий каждого имени — задача хранилища ключей и значений; хранилище объектов сохраняет текущий ObjectInfo, а не последовательность изменений.

Ссылка — объект, указывающий на другой объект. Get ссылки прозрачно возвращает байты цели: хранилище следует по ссылке. Это ссылка, а не копия: собственных фрагментов у неё нет, сохраняются только бакет и имя цели.

Это полезно, когда два имени должны возвращать одни байты. В Acme этикетка и счёт могут представлять общий документ; стабильное имя может также служить входом к меняющимся файлам. Здесь label-ord_8w2k.png становится ссылкой на счёт, поэтому запрос этикетки возвращает байты счёта:

#!/bin/bash
# Add a link from one object to another. A link is an object whose target
# is another object; a get on the link transparently returns the target's
# bytes. Here `label-ord_8w2k.png` is a link that points at the invoice, so
# fetching the label hands back the invoice.
#
# Adding a link is a client-library operation (AddLink / AddBucketLink); the
# `nats` CLI has no link subcommand, so this snippet is illustration only —
# it shows the shape of the call with a client. The store records the target
# {bucket, name} at creation time, then traverses it on get.
#
# Pseudocode:
#
# invoice = os.GetInfo("invoice-ord_8w2k.pdf")
# os.AddLink("label-ord_8w2k.png", invoice)
#
# Once the link exists, a client get on the link name returns the invoice
# bytes, traversed for you:
#
# os.Get("label-ord_8w2k.png") # returns the invoice's bytes

# A bucket link points at a whole bucket instead of one object: pass an
# empty target name. It stores only a reference to the other bucket, so a
# get on a bucket link returns an error (ErrCantGetBucket in Go), not bytes.
# Read the link's info to learn the target bucket, then open that bucket
# yourself. Reach for a bucket link when you want a stored pointer to
# another store, not a gettable object.

Ссылка может указывать на целый бакет. Это ссылка на бакет: имя цели пустое, сохраняется только другой бакет. Get такой ссылки не возвращает байты, а завершается ошибкой (ErrCantGetBucket в Go). Прочитайте сведения ссылки, узнайте целевой бакет и откройте его самостоятельно. Это сохранённый указатель на хранилище, а не доступный через get объект.

Хранилище соблюдает два ограничения: нельзя ссылаться на удалённый объект или на другую ссылку. Цепочки ссылок не создаются. При добавлении записывается текущая цель, а каждый последующий get разрешает её.

Все поля ObjectInfo и параметры ссылок приведены в справочнике. Здесь достаточно поведения.

Подводные камни​

Здесь две ловушки: изменение цели ссылки и границы действия UpdateMeta.

Ссылка фиксирует адрес при создании и не отслеживает его изменения. Она сохраняет бакет и имя, но не поддерживает существование цели. После удаления цели ссылка остаётся висячей: get возвращает ErrObjectNotFound. Переименование ломает её так же, поскольку сохранено старое имя. Не считайте, что addLink удерживает цель или следует за переименованием. Перед использованием проверяйте её через info; после удаления или переименования создавайте ссылку заново.

Вот ошибка и безопасная проверка рядом: удалите счёт, запросите устаревшую ссылку этикетки, проверьте цель через info, затем снова запишите счёт, чтобы ссылка разрешалась, а бакет вернулся в прежнее состояние:

#!/bin/bash
# A link is a snapshot of its target at creation time, not a live
# reference that keeps the target alive. Delete the target and the link
# is left dangling: a get on the link fails with a not-found error.
#
# Delete the invoice that label-ord_8w2k.png points at:
nats object rm INVOICES invoice-ord_8w2k.pdf --force

# Now get the link. The store traverses to invoice-ord_8w2k.pdf, finds it
# deleted, and fails — the link still exists, but its target does not:
#
# nats: error: nats: object not found
#
# In a client library this surfaces as ErrObjectNotFound. Always confirm
# the target exists before depending on a link, and re-create the link
# after you delete or rename its target.
nats object get INVOICES label-ord_8w2k.png

# Confirm the target before you depend on the link. `nats object info`
# returns the metadata if the target is present and the same not-found
# error if it is gone:
nats object info INVOICES invoice-ord_8w2k.pdf

# Restore the running example. Re-put the invoice with its description and
# content-type header so the bucket is back to where the chapter left it
# and the label link resolves again:
nats object put INVOICES invoice-ord_8w2k.pdf --force \
--description "Invoice for order ord_8w2k" \
--header "content-type:application/pdf"

UpdateMeta меняет имя, описание, заголовки и метаданные, но не размер фрагмента или цель ссылки. Изменение имени переименовывает объект. Переданные новые размер фрагмента или цель ссылки молча отбрасываются: вызов успешен, но поля не сохраняются. Размер фиксируется при записи байтов, цель — при создании ссылки. Для изменения размера удалите объект и выполните put заново; для изменения цели удалите ссылку и добавьте новую. Переименование в существующее неудалённое имя возвращает ErrObjectAlreadyExists. В удалённое имя переименовать можно, заняв его снова.

Текущее состояние​

Теперь у вас есть:

  • invoice-ord_8w2k.pdf с описанием и заголовком content-type, доступными без чтения байтов.
  • label-ord_8w2k.png как ссылка на счёт с прозрачным разрешением при get.
  • Понимание ограничений ссылок — без удалённой цели и без ссылки на ссылку — и полей, изменяемых UpdateMeta.

В бакете есть объект с метаданными и ссылка рядом с ним. Следующая страница переходит к бакету целиком: снимку содержимого и наблюдению за изменениями.

Что дальше​

Изучим list и watch: снимок всех объектов и поток метаданных, через который analytics наблюдает за заполнением бакета.

Переходите к странице Наблюдение и список объектов.

См. также​