Файлы по пути

Файлы по пути в репозитории: ревизии, история, восстановление и raw-файлы одним запросом.

Операции этой группы с правилом доступа, правилом повтора, параметрами и ответами. Каждый запрос несёт ключ: Authorization: Bearer <ключ> (см. «Аутентификация»).

Операции

Перечислить пути файлов по префиксу

GET HEAD /api/v1/repositories/{repository}/assets

Доступ: Право в репозитории: asset.read; файловые ключи: read · Повтор: Можно повторять (чтение)

Возвращает все пути файлов, начинающиеся с prefix (буквально, не шаблон; пустой — все), в порядке путей, каждый с текущей ревизией и ID артефакта. Постраничной выдачи нет: более 1000 совпадений — ошибка 400 с просьбой сузить префикс, поэтому для больших деревьев лучше listAssetPage.

Параметры

Имя	Где	Тип	Обязателен	Правила
`repository`	путь	string	да	по шаблону `^[a-z0-9][a-z0-9_-]{0,63}$`
`prefix`	запрос	string	нет	—

Ответ 200

Поле	Тип	Обязателен	Правила
`items`	массив object	нет	—
`items[].path`	string	да	—
`items[].revision`	integer	да	1–2147483647
`items[].artifactId`	string (uuid)	да	—

Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507

Пример

bash

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/assets" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Перечислить пути файлов постранично

GET HEAD /api/v1/repositories/{repository}/assets/page

Доступ: Право в репозитории: asset.read; файловые ключи: read · Повтор: Можно повторять (чтение)

Возвращает текущие пути файлов, начинающиеся с prefix (буквально; пустой — все), в порядке байтов UTF-8, каждый с текущей ревизией и ID артефакта. Страницы содержат limit элементов (1–100, по умолчанию 50); продолжайте с after, равным непрозрачному next. Страницы не образуют снимок: пути, изменённые между запросами, могут появиться с более новой ревизией или быть пропущены до следующего прохода.

Параметры

Имя	Где	Тип	Обязателен	Правила
`repository`	путь	string	да	по шаблону `^[a-z0-9][a-z0-9_-]{0,63}$`
`prefix`	запрос	string	нет	не длиннее 1024 символов; по умолчанию ``; Case-sensitive literal prefix; % and _ are ordinary characters.
`after`	запрос	string	нет	по шаблону `^[A-Za-z0-9_-]+$`; 1–8192 символов
`limit`	запрос	integer	нет	1–100; по умолчанию `50`

Ответ 200

Поле	Тип	Обязателен	Правила
`items`	массив object	да	не больше 100 элементов
`items[].path`	string	да	—
`items[].revision`	integer	да	1–2147483647
`items[].artifactId`	string (uuid)	да	—
`next`	string	да	по шаблону `^[A-Za-z0-9_-]+$`; 1–8192 символов; может быть null; Непрозрачный курсор, привязанный к репозиторию и префиксу; null в конце. Доступа не даёт.

Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507

Пример

bash

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/assets/page" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Получить текущую ревизию пути файла

GET HEAD /api/v1/repositories/{repository}/asset

Доступ: Право в репозитории: asset.read; файловые ключи: read · Повтор: Можно повторять (чтение)

Возвращает текущую ревизию revision пути path и ID артефакта, на который он указывает; неизвестный путь — 404. Путь состоит из 1–1024 символов в сегментах, разделённых /, без пустых сегментов, сегментов . и .., символов \, : и управляющих символов. Скачайте байты через downloadAssetContent или передайте ревизию в setAsset как expectedRevision.

Параметры

Имя	Где	Тип	Обязателен	Правила
`repository`	путь	string	да	по шаблону `^[a-z0-9][a-z0-9_-]{0,63}$`
`path`	запрос	string	да	—

Ответ 200

Поле	Тип	Обязателен	Правила
`path`	string	да	—
`revision`	integer	да	1–2147483647
`artifactId`	string (uuid)	да	—

Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507

Пример

bash

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset?path=$PATH" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Направить путь файла на артефакт

PUT /api/v1/repositories/{repository}/asset

Доступ: Право в репозитории: asset.write, artifact.read; файловые ключи: read, write · Повтор: Повтор только с ожидаемой ревизией (compare-and-swap)

Делает path именем опубликованного артефакта того же репозитория в новой ревизии; expectedRevision равна 0 для создания пути и текущей ревизии для замены, иначе 409 revision_mismatch. Прежние ревизии остаются в истории и не дают удалить свои артефакты. Чтобы сохранить байты и назвать их одним запросом, используйте putRawFile.

Параметры

Имя	Где	Тип	Обязателен	Правила
`repository`	путь	string	да	по шаблону `^[a-z0-9][a-z0-9_-]{0,63}$`

Тело запроса (application/json)

Поле	Тип	Обязателен	Правила
`path`	string	да	—
`artifactId`	string (uuid)	да	—
`expectedRevision`	integer	да	0–2147483646

Ответ 200

Поле	Тип	Обязателен	Правила
`path`	string	да	—
`revision`	integer	да	1–2147483647
`artifactId`	string (uuid)	да	—

Ответы: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Пример

bash

curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path":"<path>","artifactId":"00000000-0000-4000-8000-000000000000","expectedRevision":0}'

Перечислить ревизии пути файла

GET HEAD /api/v1/repositories/{repository}/asset/history

Доступ: Право в репозитории: asset.read; файловые ключи: read · Повтор: Можно повторять (чтение)

Возвращает ревизии path от новых к старым, по 50 на страницу, каждую с артефактом, инициатором, временем и, для восстановления, ревизией-источником sourceRevision (инициатор и время равны null у ревизий, записанных ранними версиями сервера). Продолжайте с before, равным next. Неизвестный путь — 404.

Параметры

Имя	Где	Тип	Обязателен	Правила
`repository`	путь	string	да	по шаблону `^[a-z0-9][a-z0-9_-]{0,63}$`
`path`	запрос	string	да	—
`before`	запрос	integer	нет	1–2147483647; Only revisions strictly smaller than this value

Ответ 200

Поле	Тип	Обязателен	Правила
`items`	массив object	да	не больше 50 элементов
`items[].path`	string	да	—
`items[].revision`	integer	да	1–2147483647
`items[].artifactId`	string (uuid)	да	—
`items[].actor`	string	да	может быть null; null для истории, записанной до миграции 4
`items[].createdAt`	string (date-time)	да	может быть null; null для истории, записанной до миграции 4
`items[].sourceRevision`	integer	да	1–2147483647; может быть null; Восстановленная ревизия; null при обычной замене
`next`	integer	да	1–2147483647; может быть null; Курсор «до», не включительно; null в конце

Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507

Пример

bash

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/history?path=$PATH" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Получить одну ревизию пути файла

GET HEAD /api/v1/repositories/{repository}/asset/revision

Доступ: Право в репозитории: asset.read; файловые ключи: read · Повтор: Можно повторять (чтение)

Возвращает ревизию revision пути path с ID артефакта, инициатором, временем и источником восстановления. Ревизии не меняются, поэтому ID артефакта можно кэшировать; скачивайте через downloadArtifact. Отсутствующий путь или ревизия — 404.

Параметры

Имя	Где	Тип	Обязателен	Правила
`repository`	путь	string	да	по шаблону `^[a-z0-9][a-z0-9_-]{0,63}$`
`path`	запрос	string	да	—
`revision`	запрос	integer	да	1–2147483647

Ответ 200

Поле	Тип	Обязателен	Правила
`path`	string	да	—
`revision`	integer	да	1–2147483647
`artifactId`	string (uuid)	да	—
`actor`	string	да	может быть null; null для истории, записанной до миграции 4
`createdAt`	string (date-time)	да	может быть null; null для истории, записанной до миграции 4
`sourceRevision`	integer	да	1–2147483647; может быть null; Восстановленная ревизия; null при обычной замене

Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507

Пример

bash

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/revision?path=$PATH&revision=$REVISION" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Восстановить прежнюю ревизию пути файла

POST /api/v1/repositories/{repository}/asset/restore

Доступ: Право в репозитории: asset.restore, asset.read, artifact.read; файловые ключи: read, write · Повтор: Повтор только с ожидаемой ревизией (compare-and-swap)

Добавляет новую ревизию path, указывающую на артефакт ревизии sourceRevision; ничего не копируется и ни одна ревизия не удаляется. expectedRevision должна быть текущей ревизией (не менее 1), иначе 409 revision_mismatch — поэтому повтор уже выполненного восстановления даёт 409, а не второе восстановление. Новая ревизия запоминает sourceRevision, а изменение попадает в аудит в той же транзакции.

Параметры

Имя	Где	Тип	Обязателен	Правила
`repository`	путь	string	да	по шаблону `^[a-z0-9][a-z0-9_-]{0,63}$`

Тело запроса (application/json)

Поле	Тип	Обязателен	Правила
`path`	string	да	—
`sourceRevision`	integer	да	1–2147483647
`expectedRevision`	integer	да	1–2147483646

Ответ 200

Поле	Тип	Обязателен	Правила
`path`	string	да	—
`revision`	integer	да	1–2147483647
`artifactId`	string (uuid)	да	—

Ответы: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Пример

bash

curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/restore" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path":"<path>","sourceRevision":1,"expectedRevision":1}'

Скачать файл по пути

GET HEAD /api/v1/repositories/{repository}/asset/content

Доступ: Право в репозитории: content.read; файловые ключи: read · Повтор: Можно повторять (чтение)

Определяет текущую ревизию path и передаёт её артефакт потоком, как downloadArtifact, с поддержкой Range, If-Range, If-None-Match и HEAD. Путь сопоставляется при каждом запросе, поэтому для возобновления используйте If-Range с возвращённым ETag: если путь уже указывает на другую ревизию, ответом будет весь новый файл, а не смесь старого и нового. downloadRawFile делает то же самое с путём в URL.

Параметры

Имя	Где	Тип	Обязателен	Правила
`repository`	путь	string	да	по шаблону `^[a-z0-9][a-z0-9_-]{0,63}$`
`Range`	заголовок	string	нет	Single bytes range; multi-range is unsupported. HEAD ignores Range.
`If-Range`	заголовок	string	нет	Exact strong ETag; a mismatch causes a full response.
`If-None-Match`	заголовок	string	нет	Matching ETag returns 304, including HEAD.
`Arkvory-Download-Id`	заголовок	string	нет	по шаблону `^[A-Za-z0-9_-]{16,64}$`; The client own id of one download, the same on every range of it: the queue keys the session by it instead of the client address, answers a waiting request at once with 503 download_queued, and may ask it to yield its place at a range boundary. Without it, a waiting request is held until its turn for a bounded time.
`Arkvory-Queue-Ticket`	заголовок	string	нет	не длиннее 80 символов; The last Arkvory-Queue-Ticket the server sent for this download: after a server restart the download takes its old turn. A ticket that is wrong, expired or of another download is ignored.
`Arkvory-Download-Class`	заголовок	string	нет	одно из `interactive`, `release`, `bulk`, `background`; Queue class of the download. Only a class lower than the caller own one applies (people: interactive, services and links: release); an unknown value is 400. The response names the class applied.
`path`	запрос	string	да	—

Ответы: 200, 206, 304, 400, 401, 403, 404, 409, 416, 422, 503, 507

Пример

bash

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/content?path=$PATH" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -o file

Загрузить файл по пути одним запросом

PUT /api/v1/repositories/{repository}/raw/{assetPath}

Доступ: Право в репозитории: upload.create, upload.write, upload.complete, asset.read, asset.write, artifact.read; файловые ключи: write · Повтор: Можно повторять: тот же запрос даёт тот же результат

Сохраняет тело запроса любого медиатипа как новую ревизию пути из URL — для скриптов и CI (curl -T); ответ — 201 с путём, ревизией и артефактом. С X-Checksum-Sha256 и Content-Length байты идут потоком прямо в хранилище и проверяются; без них сначала записываются во временную область (staging) и хешируются (422, если тело не совпадает с заданной контрольной суммой). Те же байты, что в текущей ревизии, ничего не добавляют и дают 200 с created: false, If-None-Match: * только создаёт (409 already_exists), а параллельный запрос, пишущий в тот же путь, получает 409 revision_mismatch. Для очень больших файлов лучше использовать сессии загрузки с возобновлением.

Параметры

Имя	Где	Тип	Обязателен	Правила
`repository`	путь	string	да	по шаблону `^[a-z0-9][a-z0-9_-]{0,63}$`
`assetPath`	путь	string	да	1–1024 символов; File path; may contain slashes (folders). No empty, "." or ".." segments, backslash or colon.
`X-Checksum-Sha256`	заголовок	string	нет	по шаблону `^[a-fA-F0-9]{64}$`; SHA-256 of the body (64 hex digits); a mismatch stores nothing (422).
`If-None-Match`	заголовок	string	нет	одно из ``; "": store only when the path does not exist yet (409 already_exists).

Тело запроса (application/octet-stream)

Ответ 200

Поле	Тип	Обязателен	Правила
`path`	string	да	—
`revision`	integer	да	не меньше 1
`created`	boolean	да	—
`artifact`	object	да	—
`artifact.id`	string (uuid)	да	—
`artifact.size`	string	да	целое число десятичными цифрами, передаётся строкой
`artifact.sha256`	string	да	SHA-256: 64 строчные шестнадцатеричные цифры

Ответы: 200, 201, 400, 401, 403, 404, 405, 409, 422, 503, 507

Пример

bash

curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/raw/$ASSETPATH" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @file

Скачать файл по пути из URL

GET HEAD /api/v1/repositories/{repository}/raw/{assetPath}

Доступ: Право в репозитории: content.read; файловые ключи: read · Повтор: Можно повторять (чтение)

Передаёт потоком текущую ревизию пути из URL, как downloadArtifact, с поддержкой Range, If-Range, If-None-Match, HEAD и с X-Arkvory-Artifact-Id, называющим артефакт. Путь сопоставляется при каждом запросе, поэтому для возобновления используйте If-Range с возвращённым ETag или скачивайте артефакт по ID.

Параметры

Имя	Где	Тип	Обязателен	Правила
`repository`	путь	string	да	по шаблону `^[a-z0-9][a-z0-9_-]{0,63}$`
`assetPath`	путь	string	да	1–1024 символов; File path; may contain slashes (folders). No empty, "." or ".." segments, backslash or colon.
`Range`	заголовок	string	нет	Single bytes range; multi-range is unsupported. HEAD ignores Range.
`If-Range`	заголовок	string	нет	Exact strong ETag; a mismatch causes a full response.
`If-None-Match`	заголовок	string	нет	Matching ETag returns 304, including HEAD.
`Arkvory-Download-Id`	заголовок	string	нет	по шаблону `^[A-Za-z0-9_-]{16,64}$`; The client own id of one download, the same on every range of it: the queue keys the session by it instead of the client address, answers a waiting request at once with 503 download_queued, and may ask it to yield its place at a range boundary. Without it, a waiting request is held until its turn for a bounded time.
`Arkvory-Queue-Ticket`	заголовок	string	нет	не длиннее 80 символов; The last Arkvory-Queue-Ticket the server sent for this download: after a server restart the download takes its old turn. A ticket that is wrong, expired or of another download is ignored.
`Arkvory-Download-Class`	заголовок	string	нет	одно из `interactive`, `release`, `bulk`, `background`; Queue class of the download. Only a class lower than the caller own one applies (people: interactive, services and links: release); an unknown value is 400. The response names the class applied.

Ответы: 200, 206, 304, 400, 401, 403, 404, 409, 416, 422, 503, 507

Пример

bash

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/raw/$ASSETPATH" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -o file

Файлы по пути ​

Операции ​

Перечислить пути файлов по префиксу ​

Перечислить пути файлов постранично ​

Получить текущую ревизию пути файла ​

Направить путь файла на артефакт ​

Перечислить ревизии пути файла ​

Получить одну ревизию пути файла ​

Восстановить прежнюю ревизию пути файла ​

Скачать файл по пути ​

Загрузить файл по пути одним запросом ​

Скачать файл по пути из URL ​

Файлы по пути

Операции

Перечислить пути файлов по префиксу

Перечислить пути файлов постранично

Получить текущую ревизию пути файла

Направить путь файла на артефакт

Перечислить ревизии пути файла

Получить одну ревизию пути файла

Восстановить прежнюю ревизию пути файла

Скачать файл по пути

Загрузить файл по пути одним запросом

Скачать файл по пути из URL