Объекты и ключи
Хранилище аккаунта — это плоское пространство аккаунта, сопоставляющее ключ с
байтами объекта. Ключ 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 |
Удаляйте объекты по одному: рекурсивного удаления префикса нет. Для ценных данных запишите новую версию, проверьте контрольную сумму, атомарно обновите манифест или указатель на уровне приложения и сохраняйте предыдущую версию в течение нужного срока восстановления.