Перейти к основному содержимому
Открыть Markdown

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

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

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

Модель объекта​

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

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

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

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

Правила ключей​

Ключ объекта — это строка в 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/"

Выбор долговечных ключей​

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

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

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

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

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

Префикс — это не папка​

Префикс — строковый фильтр. Завершающий / принят по соглашению, но частичный префикс вроде 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 для отображения папок. Загрузка в открытую папку добавляет ее префикс перед локальным именем файла. Поскольку папки неявные, пустая папка не существует, а удаление всех объектов под префиксом убирает папку из интерфейса.

Обход всех страниц списка​

Эндпоинт списка возвращает не больше запрошенного размера страницы. Значение 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.

Поведение изменений​

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

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