Стадии и продвижение
Стадии артефакта (например, release), продвижение между репозиториями и выбор версии по стадии.
Операции этой группы с правилом доступа, правилом повтора, параметрами и ответами. Каждый запрос несёт ключ: Authorization: Bearer <ключ> (см. «Аутентификация»).
Операции
Перечислить стадии артефакта
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/stages
Доступ: Право в репозитории: artifact.read; файловые ключи: read · Повтор: Можно повторять (чтение)
Возвращает текущие стадии продвижения опубликованного артефакта (не более 16), каждую со временем добавления, инициатором и комментарием.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
repository | путь | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | путь | string (uuid) | да | — |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
items | массив object | да | не больше 16 элементов |
items[].artifactId | string (uuid) | да | — |
items[].stage | string | да | по шаблону ^[a-z0-9][a-z0-9_.-]{0,31}$ |
items[].promotedAt | string (date-time) | да | — |
items[].actor | string | да | — |
items[].comment | string | да | не длиннее 1024 символов; может быть null |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/stages" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Добавить стадию артефакту
PUT /api/v1/repositories/{repository}/artifacts/{id}/stages/{stage}
Доступ: Право в репозитории: artifact.promote, artifact.read; файловые ключи: read, write · Повтор: Можно повторять: тот же запрос даёт тот же результат
Помечает опубликованный артефакт стадией stage (1–32 символа: строчные буквы, цифры или _.-, первый символ — буква или цифра) с необязательным comment до 1024 символов и записывает событие в журнал продвижения. Добавление уже имеющейся стадии ничего не меняет и сохраняет исходное время, поэтому чтобы продвинуть ту же версию снова (для отката с order=promoted), сначала удалите стадию. У артефакта не более 16 стадий (409 stage_limit).
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
repository | путь | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | путь | string (uuid) | да | — |
stage | путь | string | да | по шаблону ^[a-z0-9][a-z0-9_.-]{0,31}$ |
Тело запроса (application/json)
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
comment | string | нет | не длиннее 1024 символов; может быть null |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
artifactId | string (uuid) | да | — |
stage | string | да | по шаблону ^[a-z0-9][a-z0-9_.-]{0,31}$ |
promotedAt | string (date-time) | да | — |
actor | string | да | — |
comment | string | да | не длиннее 1024 символов; может быть null |
Ответы: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Пример
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/stages/$STAGE" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'Удалить стадию артефакта
DELETE /api/v1/repositories/{repository}/artifacts/{id}/stages/{stage}
Доступ: Право в репозитории: artifact.promote, artifact.read; файловые ключи: read, write · Повтор: Можно повторять: тот же запрос даёт тот же результат
Удаляет stage у опубликованного артефакта и записывает событие в журнал продвижения; удаление стадии, которой у артефакта нет, тоже успешно. Выбор версии пакета по этой стадии сразу перестаёт возвращать этот артефакт.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
repository | путь | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | путь | string (uuid) | да | — |
stage | путь | string | да | по шаблону ^[a-z0-9][a-z0-9_.-]{0,31}$ |
Ответы: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
Пример
curl -X DELETE "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/stages/$STAGE" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Перечислить историю продвижения артефакта
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/promotions
Доступ: Право в репозитории: artifact.read; файловые ключи: read · Повтор: Можно повторять (чтение)
Возвращает журнал одного артефакта от старых событий к новым: добавленные и удалённые стадии, продвижения в другие репозитории и из них с соответствующим артефактом другого репозитория, инициатором, комментарием и временем. Страницы содержат limit событий (1–100, по умолчанию 50); продолжайте с after, равным next.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
repository | путь | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | путь | string (uuid) | да | — |
after | запрос | string | нет | целое число десятичными цифрами, передаётся строкой |
limit | запрос | string | нет | целое число десятичными цифрами, передаётся строкой; At most 100. |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
items | массив object | да | не больше 100 элементов |
items[].sequence | string | да | целое число десятичными цифрами, передаётся строкой |
items[].repository | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
items[].artifactId | string (uuid) | да | — |
items[].action | string | да | одно из stage.added, stage.removed, promoted, received |
items[].stage | string | да | по шаблону ^[a-z0-9][a-z0-9_.-]{0,31}$; может быть null |
items[].mode | string | да | одно из copy, move, null; может быть null |
items[].peerRepository | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$; может быть null |
items[].peerArtifactId | string (uuid) | да | может быть null |
items[].actor | string | да | — |
items[].comment | string | да | не длиннее 1024 символов; может быть null |
items[].occurredAt | string (date-time) | да | — |
next | string | да | может быть null |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/promotions" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Продвинуть артефакт в другой репозиторий
POST /api/v1/repositories/{repository}/artifacts/{id}/promote
Доступ: Право в репозитории: artifact.read, content.read; файловые ключи: read · Повтор: Можно повторять: тот же запрос даёт тот же результат
Публикует артефакт в target, не отправляя байты заново, при желании со stages и comment; вызывающему также нужно право artifact.promote в целевом репозитории. Режим mode: copy (по умолчанию) оставляет источник; move, которому право artifact.promote нужно и в исходном репозитории, логически удаляет источник в той же транзакции, переносит его стадии и отклоняется с 409, если источник нельзя удалить. Ответ — 201 с копией; повтор возвращает ту же копию с 200, а если в целевом репозитории уже есть эта версия пакета, возвращается её артефакт при совпадении SHA-256 и 409 version_exists при несовпадении. Вложения сборки и пути файлов не переносятся.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
repository | путь | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | путь | string (uuid) | да | — |
Тело запроса (application/json)
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
target | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
mode | string | нет | одно из copy, move |
stages | массив string | нет | не больше 16 элементов; без повторов; каждый элемент: по шаблону ^[a-z0-9][a-z0-9_.-]{0,31}$ |
comment | string | нет | не длиннее 1024 символов; может быть null |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
repository | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
artifactId | string (uuid) | да | — |
sourceRepository | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
sourceArtifactId | string (uuid) | да | — |
mode | string | да | одно из copy, move |
created | boolean | да | — |
stages | массив string | да | не больше 16 элементов; без повторов; каждый элемент: по шаблону ^[a-z0-9][a-z0-9_.-]{0,31}$ |
Ответы: 200, 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Пример
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/promote" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"target":"<target>"}'Перечислить артефакты со стадиями
GET HEAD /api/v1/repositories/{repository}/stages
Доступ: Право в репозитории: artifact.list; файловые ключи: read · Повтор: Можно повторять (чтение)
Перечисляет записи стадий репозитория (артефакт, стадия, время, инициатор, комментарий) в порядке артефакта и стадии, при необходимости только для stage или только для артефактов из ids (1–100 ID через запятую, например чтобы показать стадии целой страницы пакетов сразу). Страницы содержат limit записей (1–100, по умолчанию 100); продолжайте с after, равным next (<artifactId>/<stage>).
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
repository | путь | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
stage | запрос | string | нет | по шаблону ^[a-z0-9][a-z0-9_.-]{0,31}$ |
after | запрос | string | нет | — |
limit | запрос | string | нет | целое число десятичными цифрами, передаётся строкой; At most 100. |
ids | запрос | string | нет | не длиннее 3699 символов; Up to 100 comma-separated artifact ids. |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
items | массив object | да | не больше 100 элементов |
items[].artifactId | string (uuid) | да | — |
items[].stage | string | да | по шаблону ^[a-z0-9][a-z0-9_.-]{0,31}$ |
items[].promotedAt | string (date-time) | да | — |
items[].actor | string | да | — |
items[].comment | string | да | не длиннее 1024 символов; может быть null |
next | string | да | может быть null |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/stages" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Следить за журналом продвижения репозитория
GET HEAD /api/v1/repositories/{repository}/promotions
Доступ: Право в репозитории: artifact.list; файловые ключи: read · Повтор: Можно повторять (чтение)
Возвращает события стадий и продвижения всех артефактов репозитория от старых к новым — для опроса из CI/CD: стадия добавлена или удалена, продвинут в другой репозиторий, получен из другого. Страницы содержат limit событий (1–100, по умолчанию 50); сохраните последний sequence и продолжайте с after, равным next.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
repository | путь | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
after | запрос | string | нет | целое число десятичными цифрами, передаётся строкой |
limit | запрос | string | нет | целое число десятичными цифрами, передаётся строкой; At most 100. |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
items | массив object | да | не больше 100 элементов |
items[].sequence | string | да | целое число десятичными цифрами, передаётся строкой |
items[].repository | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
items[].artifactId | string (uuid) | да | — |
items[].action | string | да | одно из stage.added, stage.removed, promoted, received |
items[].stage | string | да | по шаблону ^[a-z0-9][a-z0-9_.-]{0,31}$; может быть null |
items[].mode | string | да | одно из copy, move, null; может быть null |
items[].peerRepository | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$; может быть null |
items[].peerArtifactId | string (uuid) | да | может быть null |
items[].actor | string | да | — |
items[].comment | string | да | не длиннее 1024 символов; может быть null |
items[].occurredAt | string (date-time) | да | — |
next | string | да | может быть null |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/promotions" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Найти версию пакета
GET HEAD /api/v1/repositories/{repository}/packages/resolve
Доступ: Право в репозитории: package.read; файловые ключи: read · Повтор: Можно повторять (чтение)
Выбирает одну зарегистрированную версию UPack по тем же правилам, что и downloadPackageContent, и возвращает её без байтов: версию, ID артефакта, SHA-256, размер, время публикации и текущие стадии. name обязателен, group по умолчанию — корневая группа; выбор по точной version или диапазону SemVer range, при необходимости stage, prerelease=true и order=promoted (требует stage); без version и range берётся наибольшая стабильная версия. Отсутствие совпадения — 404; скачивайте результат по ID артефакта, чтобы остаться на этой версии.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
repository | путь | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
group | запрос | string | нет | не длиннее 128 символов |
name | запрос | string | да | 1–128 символов |
version | запрос | string | нет | не длиннее 128 символов; Exact version; excludes range. |
range | запрос | string | нет | не длиннее 256 символов; SemVer range: 1.2.3, ^1.2, ~1.2.3, 1.x, >=1.0.0 <2.0.0, a || b. |
stage | запрос | string | нет | по шаблону ^[a-z0-9][a-z0-9_.-]{0,31}$; Only versions promoted to this stage. |
prerelease | запрос | string | нет | одно из true, false; Include prereleases. |
order | запрос | string | нет | одно из version, promoted; promoted picks the most recently staged version and requires stage. |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
group | string | да | — |
name | string | да | — |
version | string | да | — |
artifactId | string (uuid) | да | — |
sha256 | string | да | SHA-256: 64 строчные шестнадцатеричные цифры |
size | string | да | целое число десятичными цифрами, передаётся строкой |
publishedAt | string (date-time) | да | — |
stagedAt | string (date-time) | да | может быть null |
stages | массив string | да | не больше 16 элементов; без повторов; каждый элемент: по шаблону ^[a-z0-9][a-z0-9_.-]{0,31}$ |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/packages/resolve?name=$NAME" \
-H "Authorization: Bearer $ARKVORY_TOKEN"