Загрузки
Возобновляемые загрузки: создать сессию, отправить байты целиком или частями, завершить и следить за заданием завершения.
Операции этой группы с правилом доступа, правилом повтора, параметрами и ответами. Каждый запрос несёт ключ: Authorization: Bearer <ключ> (см. «Аутентификация»).
Операции
Перечислить принятые части загрузки
GET HEAD /api/v1/repositories/{repository}/uploads/{id}/parts
Доступ: Право в репозитории: upload.read; файловые ключи: write · Повтор: Можно повторять (чтение)
Возвращает partBytes — размер части, зафиксированный для этой загрузки при её создании (8 МиБ, удваивается для файлов, которым потребовалось бы больше 10 000 частей; только последняя часть короче), и уже сохранённые части с индексом, размером и SHA-256. Прочитайте его перед продолжением прерванной загрузки по частям и отправляйте через putUploadPart только недостающие части. Видеть его может только создатель загрузки; для остальных — 404.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
repository | путь | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | путь | string (uuid) | да | — |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
partBytes | integer | нет | 8388608–1073741824; Все части имеют этот размер, кроме последней. |
items | массив object | нет | — |
items[].index | integer | да | 0–9999 |
items[].size | integer | да | 1–1073741824 |
items[].sha256 | string | да | SHA-256: 64 строчные шестнадцатеричные цифры |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/parts" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Загрузить одну часть
PUT /api/v1/repositories/{repository}/uploads/{id}/parts/{index}
Доступ: Право в репозитории: upload.write; файловые ключи: write · Повтор: Перечитать загрузку, затем решать
Сохраняет тело запроса как часть index (с 0) незавершённой загрузки по частям; его длина должна быть ровно partBytes (из listUploadParts) или равна остатку для последней части, а X-Content-SHA256 — SHA-256 этих байтов в шестнадцатеричной записи строчными буквами, иначе 422. Части могут приходить в любом порядке, но загрузка обрабатывает один запрос за раз (параллельный получит 503 busy); повторная отправка части с тем же хешем безопасна, другой хеш для уже сохранённого индекса — 409 part_mismatch. Когда все части сохранены, вызовите completeUpload или enqueueCompletion.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
repository | путь | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | путь | string (uuid) | да | — |
index | путь | integer | да | 0–9999 |
X-Content-SHA256 | заголовок | string | да | SHA-256: 64 строчные шестнадцатеричные цифры |
Тело запроса (application/octet-stream)
Ответы: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
Пример
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/parts/$INDEX" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "X-Content-SHA256: $X_CONTENT_SHA256" \
-H "Content-Type: application/octet-stream" \
--data-binary @fileЗавершить загрузку в фоне
POST /api/v1/repositories/{repository}/uploads/{id}/complete-async
Доступ: Право в репозитории: upload.complete; файловые ключи: write · Повтор: Перечитать задание, затем решать
Ставит завершение незавершённой загрузки в очередь для обработчика (worker) вместо выполнения в самом запросе и сразу возвращает задание с кодом 202; следите за ним через getCompletionJob. Повторный вызов для той же загрузки возвращает то же задание, а задание, завершившееся ошибкой по временной причине, ставится в очередь снова. Задание в очереди не означает, что артефакт опубликован: об этом говорит только статус completed. 409 upload_state, если загрузка уже не ожидает завершения; 507 queue_full, если у вызывающего 100 открытых заданий или у сервера 10 000.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
repository | путь | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | путь | string (uuid) | да | — |
Ответ 202
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
id | string (uuid) | да | — |
uploadId | string (uuid) | да | — |
repository | string | да | — |
owner | string | да | — |
status | string | да | одно из queued, running, completed, failed |
generation | integer | да | 0–2147483647 |
attempts | integer | да | не меньше 0 |
credentialId | string (uuid) | нет | ID инициировавшего управляемого ключа (необязательно); никогда не его секрет. |
errorCode | string | да | может быть null |
Ответы: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507
Пример
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/complete-async" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Получить задание на завершение
GET HEAD /api/v1/jobs/{id}
Доступ: Право в репозитории: job.read; файловые ключи: write · Повтор: Можно повторять (чтение)
Возвращает состояние задания на завершение, поставленного через enqueueCompletion: queued, running, completed (загрузка опубликована) или failed с errorCode, а также число попыток. Обработчик (worker) делает до пяти попыток с растущими паузами; ошибки вроде integrity_mismatch приводят к немедленному отказу. Видеть его может только создатель задания; для остальных — 404.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
id | путь | string (uuid) | да | — |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
id | string (uuid) | да | — |
uploadId | string (uuid) | да | — |
repository | string | да | — |
owner | string | да | — |
status | string | да | одно из queued, running, completed, failed |
generation | integer | да | 0–2147483647 |
attempts | integer | да | не меньше 0 |
credentialId | string (uuid) | нет | ID инициировавшего управляемого ключа (необязательно); никогда не его секрет. |
errorCode | string | да | может быть null |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/jobs/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Создать сессию загрузки
POST /api/v1/repositories/{repository}/uploads
Доступ: Право в репозитории: upload.create; файловые ключи: write · Повтор: Можно повторять с тем же Idempotency-Key
Резервирует загрузку одного файла, описанного полями name, size (десятичная строка), sha256 и необязательными labels и metadata; возвращает 201 с сессией (pending, действует 7 суток) и её Location. Idempotency-Key (1–128 символов: буквы, цифры и _.:-) обязателен: тот же ключ с тем же описанием возвращает ту же сессию, с другим описанием — 409 idempotency_mismatch. Размер сразу резервируется в квоте репозитория и в ёмкости сервера (507). Затем отправьте байты целиком через putUploadContent или по частям через putUploadPart и завершите вызовом completeUpload.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
repository | путь | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
Idempotency-Key | заголовок | string | да | не длиннее 128 символов |
Тело запроса (application/json)
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
name | string | да | 1–240 символов |
size | string | да | целое число десятичными цифрами, передаётся строкой |
sha256 | string | да | SHA-256: 64 строчные шестнадцатеричные цифры |
labels | массив string | нет | не больше 32 элементов; каждый элемент: не длиннее 64 символов |
metadata | словарь string | нет | не больше 32 записей |
Ответ 201
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
id | string (uuid) | да | — |
repository | string | да | — |
status | string | да | одно из pending, available, cancelled |
createdAt | string (date-time) | да | — |
expiresAt | string (date-time) | да | — |
descriptor | object | да | — |
descriptor.name | string | да | 1–240 символов |
descriptor.size | string | да | целое число десятичными цифрами, передаётся строкой |
descriptor.sha256 | string | да | SHA-256: 64 строчные шестнадцатеричные цифры |
descriptor.labels | массив string | нет | не больше 32 элементов; каждый элемент: не длиннее 64 символов |
descriptor.metadata | словарь string | нет | не больше 32 записей |
Ответы: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Пример
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"name":"<name>","size":"1024","sha256":"<sha256: SHA-256>"}'Получить загрузку
GET HEAD /api/v1/repositories/{repository}/uploads/{id}
Доступ: Право в репозитории: upload.read; файловые ключи: write · Повтор: Можно повторять (чтение)
Возвращает сессию со статусом status (pending, available после публикации, cancelled), сроком действия и заявленным дескриптором. Если ответ на putUploadContent или completeUpload потерян, сначала прочитайте её: available означает, что артефакт опубликован под тем же ID. Видеть её может только создатель загрузки; для остальных — 404.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
repository | путь | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | путь | string (uuid) | да | — |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
id | string (uuid) | да | — |
repository | string | да | — |
status | string | да | одно из pending, available, cancelled |
createdAt | string (date-time) | да | — |
expiresAt | string (date-time) | да | — |
descriptor | object | да | — |
descriptor.name | string | да | 1–240 символов |
descriptor.size | string | да | целое число десятичными цифрами, передаётся строкой |
descriptor.sha256 | string | да | SHA-256: 64 строчные шестнадцатеричные цифры |
descriptor.labels | массив string | нет | не больше 32 элементов; каждый элемент: не длиннее 64 символов |
descriptor.metadata | словарь string | нет | не больше 32 записей |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Отменить загрузку
DELETE /api/v1/repositories/{repository}/uploads/{id}
Доступ: Право в репозитории: upload.cancel; файловые ключи: write · Повтор: Перечитать загрузку, затем решать
Отменяет незавершённую загрузку и возвращает её со статусом cancelled; опубликованную загрузку отменить нельзя (409 upload_state). Полученные байты сразу скрываются, но остаются зарезервированными в квоте, пока их не удалит физическая очистка репозитория (setCleanup, по умолчанию выключена) по истечении защитного срока.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
repository | путь | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | путь | string (uuid) | да | — |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
id | string (uuid) | да | — |
repository | string | да | — |
status | string | да | одно из pending, available, cancelled |
createdAt | string (date-time) | да | — |
expiresAt | string (date-time) | да | — |
descriptor | object | да | — |
descriptor.name | string | да | 1–240 символов |
descriptor.size | string | да | целое число десятичными цифрами, передаётся строкой |
descriptor.sha256 | string | да | SHA-256: 64 строчные шестнадцатеричные цифры |
descriptor.labels | массив string | нет | не больше 32 элементов; каждый элемент: не длиннее 64 символов |
descriptor.metadata | словарь string | нет | не больше 32 записей |
Ответы: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
Пример
curl -X DELETE "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Загрузить весь файл одним запросом
PUT /api/v1/repositories/{repository}/uploads/{id}/content
Доступ: Право в репозитории: upload.write, upload.complete; файловые ключи: write · Повтор: Перечитать загрузку, затем решать
Принимает тело запроса потоком как полное содержимое незавершённой загрузки, сверяет его с заявленными размером и SHA-256 (при несовпадении 422) и публикует артефакт; в ответе — загрузка со статусом available. Прерванный запрос ничего не оставляет для продолжения: прочитайте загрузку через getUpload и отправьте файл заново с нулевого байта. Не подходит для загрузки, у которой уже есть части (409 upload_state); кроме того, один запрос должен уложиться в срок загрузки на сервере (по умолчанию 30 минут), поэтому крупные файлы отправляйте по частям.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
repository | путь | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | путь | string (uuid) | да | — |
Тело запроса (application/octet-stream)
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
id | string (uuid) | да | — |
repository | string | да | — |
status | string | да | одно из pending, available, cancelled |
createdAt | string (date-time) | да | — |
expiresAt | string (date-time) | да | — |
descriptor | object | да | — |
descriptor.name | string | да | 1–240 символов |
descriptor.size | string | да | целое число десятичными цифрами, передаётся строкой |
descriptor.sha256 | string | да | SHA-256: 64 строчные шестнадцатеричные цифры |
descriptor.labels | массив string | нет | не больше 32 элементов; каждый элемент: не длиннее 64 символов |
descriptor.metadata | словарь string | нет | не больше 32 записей |
Ответы: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
Пример
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/content" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/octet-stream" \
--data-binary @fileЗавершить загрузку
POST /api/v1/repositories/{repository}/uploads/{id}/complete
Доступ: Право в репозитории: upload.complete; файловые ключи: write · Повтор: Перечитать загрузку, затем решать
Собирает сохранённые части по порядку, сверяет весь файл с заявленными размером и SHA-256 и публикует артефакт; возвращает загрузку со статусом available. Повторный вызов для опубликованной загрузки возвращает тот же результат, поэтому им можно восстановить завершение, ответ на которое потерян. Отсутствующая часть — 409 parts_incomplete, несовпадение содержимого — 422; для очень больших файлов, когда запрос может не уложиться во время, используйте вместо него enqueueCompletion.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
repository | путь | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | путь | string (uuid) | да | — |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
id | string (uuid) | да | — |
repository | string | да | — |
status | string | да | одно из pending, available, cancelled |
createdAt | string (date-time) | да | — |
expiresAt | string (date-time) | да | — |
descriptor | object | да | — |
descriptor.name | string | да | 1–240 символов |
descriptor.size | string | да | целое число десятичными цифрами, передаётся строкой |
descriptor.sha256 | string | да | SHA-256: 64 строчные шестнадцатеричные цифры |
descriptor.labels | массив string | нет | не больше 32 элементов; каждый элемент: не длиннее 64 символов |
descriptor.metadata | словарь string | нет | не больше 32 записей |
Ответы: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
Пример
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/complete" \
-H "Authorization: Bearer $ARKVORY_TOKEN"