# Объекты и ключи

Хранилище аккаунта — это плоское пространство аккаунта, сопоставляющее ключ с байтами объекта. Ключ `datasets/raw/events.jsonl` выглядит иерархически, но хранилище не создает отдельные ресурсы-каталоги `datasets/` и `datasets/raw/`.

Шлюз получает пространство аккаунта из аутентификации и добавляет внутренний префикс аккаунта перед обращением к объектному хранилищу. API и веб-интерфейс показывают только ключ относительно аккаунта. Код одного аккаунта не может обратиться к другому, добавив его ID аккаунта в начало ключа.

## Модель объекта[​](#object-model "Прямая ссылка на Модель объекта")

У объекта есть:

| Свойство        | Значение                                                           |
| --------------- | ------------------------------------------------------------------ |
| `key`           | Стабильный идентификатор относительно аккаунта, выбранный клиентом |
| `size`          | Размер сохраненного объекта в байтах                               |
| `etag`          | Необязательный признак версии от объектного хранилища              |
| `last_modified` | Необязательное время изменения от объектного хранилища             |
| Тело            | Произвольные байты с `application/octet-stream`                    |

Считайте ETag непрозрачными метаданными, а не универсальной контрольной суммой содержимого. Его формат зависит от объектного хранилища и способа передачи. Если целостность входит в контракт, храните SHA-256 в манифесте, в отдельном объекте рядом с данными или в базе данных приложения.

Публичных операций переименования, копирования, создания папки и рекурсивного удаления нет. Чтобы переместить объект через публичный API, загрузите байты с новым ключом, проверьте результат и затем удалите старый ключ.

## Правила ключей[​](#key-rules "Прямая ссылка на Правила ключей")

Ключ объекта — это строка в UTF-8, которая проходит валидацию до обращения к лежащему в основе хранилищу.

| Допустимо                                           | Недопустимо                                |
| --------------------------------------------------- | ------------------------------------------ |
| Буквы, цифры, пробелы, Unicode и точки внутри имени | Пустой ключ                                |
| `/` между непустыми сегментами                      | `/` в начале или конце                     |
| Имена вроде `file.tar.gz`                           | Пустые сегменты вроде `a//b`               |
| Доступная часть общего лимита 1 024 байта           | Сегмент, равный `.` или `..`               |
|                                                     | Обратная косая черта и управляющие символы |

Лимит лежащего в основе хранилища в 1 024 байта применяется к внутреннему префиксу аккаунта вместе с ключом пользователя. Поэтому максимально допустимый ключ пользователя немного короче 1 024 байт и зависит от ID аккаунта. Это лимит байтов, а не символов.

Когда ключ входит в `/v1/storage/objects/{key}`, закодируйте процентным кодированием каждый сегмент пути, сохраняя `/` как разделитель. `prefix` и `cursor` кодируйте как параметры запроса. Стандартный клиент делает это через `--data-urlencode`:

```
curl --fail-with-body --silent --show-error \
  --get "$JUSTRUN_API/v1/storage/objects" \
  --header "Authorization: Bearer $JUSTRUN_PAT" \
  --data-urlencode "prefix=reports/Июль 2026/"
```

## Выбор долговечных ключей[​](#choose-durable-keys "Прямая ссылка на Выбор долговечных ключей")

Хороший ключ сообщает владельца и жизненный цикл без отдельной базы каталогов. Например:

```
datasets/raw/2026-07-27/events.jsonl
models/recommender/v17/model.bin
runs/run_01k0…/results/summary.json
```

Предпочитайте:

* версионированные ключи или ключи, адресуемые по содержимому, для воспроизводимых артефактов;
* сгенерированный идентификатор, если два пишущих клиента иначе могут выбрать один ключ;
* единую схему префиксов для окружения, рабочей нагрузки и даты;
* манифест со ссылками на все объекты одного логического артефакта.

Не помещайте в ключи секреты и чувствительные персональные данные. Ключи видны в списке, веб-интерфейсе и служебных записях. Также не используйте один изменяемый ключ как средство координации одновременной записи: публичные записи безусловные, поэтому одновременные загрузки одного ключа перезаписывают друг друга, а сохраненной будет последняя завершившаяся запись.

## Префикс — это не папка[​](#prefixes-are-not-folders "Прямая ссылка на Префикс — это не папка")

Префикс — строковый фильтр. Завершающий `/` принят по соглашению, но частичный префикс вроде `datasets/ra` тоже допустим. Пустой префикс выводит корень аккаунта.

Пусть сохранены объекты:

```
datasets/raw/a.csv
datasets/raw/b.csv
datasets/clean/v1.parquet
models/v1.bin
```

Сгруппированный список имитирует один уровень папок:

```
curl --fail-with-body --silent --show-error \
  --get "$JUSTRUN_API/v1/storage/objects" \
  --header "Authorization: Bearer $JUSTRUN_PAT" \
  --data-urlencode "prefix=datasets/" \
  --data-urlencode "delimiter=/" \
  --data-urlencode "limit=100" |
  jq '{objects, common_prefixes, next_cursor}'
```

Непосредственные объекты возвращаются в `objects`, более глубокие группы — в `common_prefixes`:

```
{
  "objects": [],
  "common_prefixes": [
    "datasets/clean/",
    "datasets/raw/"
  ],
  "next_cursor": null
}
```

Уберите `delimiter`, чтобы получить плоский список всех объектов, ключи которых начинаются с префикса. Единственный поддерживаемый непустой разделитель — `/`.

Веб-интерфейс использует сгруппированный список, хлебные крошки и `common_prefixes` для отображения папок. Загрузка в открытую папку добавляет ее префикс перед локальным именем файла. Поскольку папки неявные, пустая папка не существует, а удаление всех объектов под префиксом убирает папку из интерфейса.

## Обход всех страниц списка[​](#paginate-every-complete-listing "Прямая ссылка на Обход всех страниц списка")

Эндпоинт списка возвращает не больше запрошенного размера страницы. Значение `limit` по умолчанию равно 100 и ограничивается диапазоном 1–1 000. Продолжайте, пока `next_cursor` не исчезнет:

```
PREFIX="datasets/"
CURSOR=""

while :; do
  ARGS=(
    --fail-with-body
    --silent
    --show-error
    --get
    "$JUSTRUN_API/v1/storage/objects"
    --header
    "Authorization: Bearer $JUSTRUN_PAT"
    --data-urlencode
    "prefix=$PREFIX"
    --data-urlencode
    "limit=1000"
  )

  if [ -n "$CURSOR" ]; then
    ARGS+=(--data-urlencode "cursor=$CURSOR")
  fi

  PAGE="$(curl "${ARGS[@]}")"
  jq -r '.objects[] | [.key, .size] | @tsv' <<<"$PAGE"

  CURSOR="$(jq -r '.next_cursor // empty' <<<"$PAGE")"
  [ -n "$CURSOR" ] || break
done
```

Курсор — непрозрачный токен продолжения. Передавайте его без изменений; не декодируйте, не создавайте самостоятельно и не храните как долговечную закладку. При смене `prefix`, `delimiter` или размера страницы начинайте с первой страницы. Неверный курсор возвращает `400`.

## Поведение изменений[​](#mutation-behavior "Прямая ссылка на Поведение изменений")

| Операция                      | Поведение                                           |
| ----------------------------- | --------------------------------------------------- |
| Загрузка с новым ключом       | Создает один объект                                 |
| Загрузка существующего ключа  | Заменяет байты по этому ключу                       |
| `HEAD`                        | Возвращает заголовки метаданных без скачивания тела |
| Удаление существующего ключа  | Удаляет объект                                      |
| Удаление отсутствующего ключа | Идемпотентно возвращает `204`                       |

Удаляйте объекты по одному: рекурсивного удаления префикса нет. Для ценных данных запишите новую версию, проверьте контрольную сумму, атомарно обновите манифест или указатель на уровне приложения и сохраняйте предыдущую версию в течение нужного срока восстановления.

## Связанные разделы[​](#related "Прямая ссылка на Связанные разделы")

* [Загрузка и скачивание](/storage/upload-and-download.md)
* [Доступ к хранилищу из песочницы](/storage/access-from-sandboxes.md)
* [Квоты и потребление](/storage/quotas-and-usage.md)
* [Безопасность и жизненный цикл данных](/storage/security-and-data-lifecycle.md)
* [Справочник REST API](/api-reference/rest.md)
