# Хранилище объектов

NATS предоставляет место для хранения файлов без отдельного сервиса. **Объект** — сохранённый файл: PDF счёта, этикетка отправления, упаковочный лист — всё слишком крупное или двоичное для обычного сообщения. **Бакет** — именованное хранилище таких объектов. Оба находятся в одном потоке JetStream с именем `OBJ_<bucket>`, на том же слое долговременного хранения из [углублённого курса JetStream](/learn/jetstream/.md).

Помните об этом с самого начала. При `put` хранилище разбивает байты на фрагменты, записывает каждый сообщением, затем добавляет одно сообщение метаданных всего объекта. При `get` оно читает метаданные, воспроизводит фрагменты по порядку и проверяет их перед возвратом байтов. В повседневной работе вы используете удобное API (`put`, `get`, `list`, `watch`, `link`), а работу обеспечивает базовый поток.

**Движение сообщений — Core NATS и JetStream (анимация):** Core NATS и JetStream при отключении подписчика. В Core публикации во время отсутствия клиента приходят на сервер и никуда не доставляются; после возвращения приходят только новые. JetStream сохраняет пропущенное: очередь растёт при отключении и уменьшается после подключения, когда поток воспроизводит все пропущенные сообщения.

* Издатель → NATS

Сначала глава объясняет абстракцию объекта, а в конце раскрывает поток. Первые четыре страницы знакомят с API хранилища без необходимости заново изучать внутренности JetStream. Страница [Внутреннее устройство](/learn/object-store/under-the-hood.md) показывает поток `OBJ_INVOICES`, существовавший всё время.

Сравните его с соседним хранилищем. [Хранилище ключей и значений](/learn/key-value/.md) сохраняет небольшие структурированные значения и историю ревизий каждого ключа. Хранилище объектов предназначено для крупных файлов из фрагментов и сохраняет лишь последние метаданные объекта, то есть текущую версию, а не историю. KV подходит для множества небольших значений, которые нужно читать, перезаписывать и проверять по истории; объекты — для целых файлов, которые записывают и получают.

## Что получится к концу главы

* Бакет `INVOICES` с описанием «Invoice PDFs», куда сервис `order-svc` помещает счета после подтверждения оплаты.
* Сохранённый и прочитанный обратно счёт `invoice-ord_8w2k.pdf`, для которого хранилище вычисляет и проверяет **хеш** SHA-256, подтверждая совпадение записанных и полученных байтов.
* Счёт размером 3 МБ, `invoice-ord_9x3m.pdf`, разбитый на множество **фрагментов** и собранный при чтении; понимание размера фрагмента, ограничивающего каждое сообщение.
* Счёт с **описанием**, заголовком `content-type` и произвольными метаданными, а также объект `label-ord_8w2k.png`, **связанный** с ним ссылкой, прозрачно разрешаемой при get.
* Сервис `analytics`, получающий **список** объектов как снимок и **наблюдающий** за новыми объектами в реальном времени.
* Понимание потока `OBJ_INVOICES`: темы фрагментов и метаданных, свёртка для хранения только последних метаданных и смысл мягкого удаления.

## Для кого эта глава

Вы прочитали [углублённый курс JetStream](/learn/jetstream/.md) или введение [Основные концепции → JetStream](/concepts/jetstream.md) и уже понимаете, что поток хранит сообщения. Здесь не объясняются заново потоки, позиции потребителей и подтверждения. При необходимости глава обозначает нужный механизм и ссылается на [JetStream](/learn/jetstream/.md).

Специальные знания о хранилище объектов не требуются. Начнём с того, что такое бакет и зачем он нужен.

## Как читать главу

Каждая страница вводит не более двух новых понятий и опирается на предыдущую. Один бакет `INVOICES` используется всю главу; можно держать один терминал открытым без сброса состояния. На странице [Первый объект](/learn/object-store/your-first-object.md) вы создадите бакет и сохраните счёт, в разделе [Разбиение на фрагменты](/learn/object-store/chunking.md) запишете крупный счёт, в разделе [Метаданные и ссылки](/learn/object-store/metadata-and-links.md) добавите метаданные и ссылку, в разделе [Наблюдение и список объектов](/learn/object-store/watching-and-listing.md) перечислите объекты и начнёте наблюдение, затем изучите [внутреннее устройство](/learn/object-store/under-the-hood.md).

У хранилища много настроек: размер фрагментов, реплики, сжатие и все поля протокола. При длинном списке страница объясняет лишь необходимое для понимания. Полный перечень находится в [справочнике](/reference/.md); здесь важно поведение.

## Содержание

| Страница                                                                    | Что вы узнаете                                                                 |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| [Первый объект](/learn/object-store/your-first-object.md)                   | Создание `INVOICES`, запись `invoice-ord_8w2k.pdf` и чтение с проверкой хеша   |
| [Разбиение на фрагменты](/learn/object-store/chunking.md)                   | Хранение счёта на 3 МБ во множестве фрагментов и просмотр их числа             |
| [Метаданные и ссылки](/learn/object-store/metadata-and-links.md)            | Описание, заголовки, произвольные метаданные и ссылка одного объекта на другой |
| [Наблюдение и список объектов](/learn/object-store/watching-and-listing.md) | Список как снимок и текущие обновления объектов                                |
| [Внутреннее устройство](/learn/object-store/under-the-hood.md)              | Поток `OBJ_INVOICES`, темы фрагментов и метаданных, свёртка и мягкое удаление  |
| [Куда двигаться дальше](/learn/object-store/where-next.md)                  | Возможности за пределами объектов и проверки перед эксплуатацией               |

## Предварительные требования

Вам понадобятся:

* Работающий `nats-server` с включённым JetStream, на котором построено хранилище объектов. Проще всего запустить `nats-server -js`.
* Установленный CLI `nats`, подключённый к вашему серверу. Большинство операций выполняется через него; некоторые, например создание ссылки, доступны лишь через клиентские библиотеки.

Откройте терминал, выполните `nats-server -js` и переходите к следующей странице.
