Артефакты и каталог
Опубликованные артефакты: список, сведения, содержимое, аннотации, ссылки удержания, поиск, аудит каталога и лента изменений.
Операции этой группы с правилом доступа, правилом повтора, параметрами и ответами. Каждый запрос несёт ключ: Authorization: Bearer <ключ> (см. «Аутентификация»).
Операции
Получить аннотации артефакта
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/annotations
Доступ: Право в репозитории: annotation.read; файловые ключи: read · Повтор: Можно повторять (чтение)
Возвращает текущие метки, метаданные и коллекции опубликованного артефакта с их revision. Ревизия 0 означает, что их ни разу не заменяли: метки и метаданные — те, что были заданы при создании загрузки, а коллекции пусты. Передайте ревизию в setAnnotations как expectedRevision.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
repository | путь | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | путь | string (uuid) | да | — |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
revision | integer | да | 0–2147483647 |
labels | массив string | да | не больше 32 элементов |
metadata | словарь string | да | не больше 32 записей |
collections | массив string | да | не больше 32 элементов |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/annotations" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Заменить аннотации артефакта
PUT /api/v1/repositories/{repository}/artifacts/{id}/annotations
Доступ: Право в репозитории: annotation.write, artifact.read; файловые ключи: read, write · Повтор: Повтор только с ожидаемой ревизией (compare-and-swap)
Заменяет labels, metadata и collections опубликованного артефакта целиком; поле, не указанное в value, становится пустым. expectedRevision должна быть текущей ревизией (0 для первого изменения), иначе 409 revision_mismatch: прочитайте аннотации заново и повторите изменение. Допускается до 32 меток и 32 коллекций (длиной 1–64 символа: буквы, цифры или _.:-) и до 32 записей метаданных (значения до 1024 символов); байты и исходный дескриптор не меняются.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
repository | путь | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | путь | string (uuid) | да | — |
Тело запроса (application/json)
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
expectedRevision | integer | да | 0–2147483646 |
value | object | да | — |
value.labels | массив string | нет | не больше 32 элементов |
value.metadata | словарь string | нет | не больше 32 записей |
value.collections | массив string | нет | не больше 32 элементов |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
revision | integer | да | 0–2147483647 |
labels | массив string | да | не больше 32 элементов |
metadata | словарь string | да | не больше 32 записей |
collections | массив string | да | не больше 32 элементов |
Ответы: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Пример
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/annotations" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"expectedRevision":0,"value":{}}'Зарегистрировать артефакт как пакет UPack
POST /api/v1/repositories/{repository}/artifacts/{id}/package
Доступ: Право в репозитории: package.publish, artifact.read; файловые ключи: read, write · Повтор: Можно повторять: тот же запрос даёт тот же результат
Открывает опубликованный артефакт как ZIP-архив UPack, читает корневой upack.json (name, необязательный group, версия version по SemVer) и регистрирует для него эту версию пакета; небезопасные или некорректные архивы отклоняются с кодом 400. Версия неизменяема: повторная регистрация того же артефакта возвращает ту же запись, а другой артефакт для существующих группы, имени и версии (сравнение без учёта регистра) — 409 version_exists. После этого версия появляется в listPackages и находится по имени, диапазону и стадии.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
repository | путь | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | путь | string (uuid) | да | — |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
group | string | нет | — |
name | string | нет | — |
version | string | нет | — |
artifactId | string (uuid) | нет | — |
manifest | object | нет | — |
Ответы: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
Пример
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/package" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Искать артефакты
GET HEAD /api/v1/repositories/{repository}/search
Доступ: Право в репозитории: artifact.list; файловые ключи: read · Повтор: Можно повторять (чтение)
Находит опубликованные артефакты по q (подстрока без учёта регистра в имени или в текущем значении метаданных), точной текущей метке label, коллекции collection и точной паре metadataKey/metadataValue (они указываются только вместе); должны совпасть все заданные фильтры. Результаты выдаются страницами по 100 в порядке ID, для каждого — размер, время создания и публикации, текущие метки и стадии продвижения; продолжайте с after, равным next. Метаданные и коллекции не возвращаются: читайте их через getAnnotations.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
repository | путь | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
q | запрос | string | нет | — |
label | запрос | string | нет | — |
collection | запрос | string | нет | — |
after | запрос | string | нет | — |
metadataKey | запрос | string | нет | по шаблону ^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$; не длиннее 64 символов; Exact metadata key; requires metadataValue. |
metadataValue | запрос | string | нет | не длиннее 1024 символов; Exact case-sensitive value; requires metadataKey. Empty string is allowed. |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
items | массив object | да | не больше 100 элементов |
items[].id | string (uuid) | да | — |
items[].name | string | да | — |
items[].size | string | да | целое число десятичными цифрами, передаётся строкой; Размер в байтах, десятичная строка |
items[].createdAt | string (date-time) | да | Время резервирования загрузки |
items[].publishedAt | string (date-time) | да | может быть null; Время публикации; null только если оно не записано |
items[].labels | массив string | да | не больше 32 элементов; Текущие метки: из аннотации, если её заменяли, иначе из дескриптора загрузки |
items[].stages | массив string | да | не больше 16 элементов; каждый элемент: по шаблону ^[a-z0-9][a-z0-9_.-]{0,31}$; Текущие стадии продвижения в порядке байтов |
next | string (uuid) | да | может быть null; Последний ID полной страницы; передайте как after |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/search" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Прочитать аудит каталога репозитория
GET HEAD /api/v1/repositories/{repository}/audit
Доступ: Право в репозитории: audit.read; файловые ключи: write · Повтор: Можно повторять (чтение)
Возвращает от старых к новым до 100 изменений каталога репозитория после порядкового номера after (по умолчанию 0): публикации, удаления, изменения аннотаций и вложений, регистрации пакетов, изменения путей файлов, внешние ссылки, стадии и продвижения, для каждого — инициатор, действие, артефакт и время. Чтобы читать дальше, передайте последний sequence страницы как after; поля next нет. Скачивания и входы в систему в аудит не попадают; зеркала следуют за listCatalogChanges, где инициаторов нет.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
repository | путь | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
after | запрос | string | нет | — |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
items | массив object | нет | — |
items[].sequence | string | нет | — |
items[].actor | string | нет | — |
items[].action | string | нет | — |
items[].artifactId | string | нет | — |
items[].occurredAt | string (date-time) | нет | — |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/audit" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Добавить ссылку на артефакт
POST /api/v1/repositories/{repository}/artifacts/{id}/references
Доступ: Право в репозитории: reference.write, artifact.read; файловые ключи: read, write · Повтор: Можно повторять: тот же запрос даёт тот же результат
Фиксирует, что нечто вне Arkvory использует этот артефакт, под выбранным вами key (1–256 символов: буквы, цифры или _.:/-), например под названием развёртывания. Артефакт со ссылкой нельзя удалить, и правила хранения его не удалят, пока не исчезнут все ссылки. Ссылка принадлежит вызывающему; повторное добавление того же ключа ничего не меняет.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
repository | путь | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | путь | string (uuid) | да | — |
Тело запроса (application/json)
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
key | string | да | не длиннее 256 символов |
Ответы: 204, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Пример
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/references" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"key":"<key>"}'Удалить ссылку на артефакт
DELETE /api/v1/repositories/{repository}/artifacts/{id}/references
Доступ: Право в репозитории: reference.write, artifact.read; файловые ключи: read, write · Повтор: Можно повторять: тот же запрос даёт тот же результат
Удаляет собственную ссылку вызывающего с ключом key из артефакта; ссылки других вызывающих остаются. Удаление отсутствующего ключа тоже завершается успехом.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
repository | путь | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | путь | string (uuid) | да | — |
Тело запроса (application/json)
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
key | string | да | не длиннее 256 символов |
Ответы: 204, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Пример
curl -X DELETE "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/references" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"key":"<key>"}'Перечислить артефакты
GET HEAD /api/v1/repositories/{repository}/artifacts
Доступ: Право в репозитории: artifact.list; файловые ключи: read · Повтор: Можно повторять (чтение)
Перечисляет опубликованные артефакты репозитория в порядке ID, по limit на страницу (1–100, по умолчанию 50); продолжайте с after, равным next. next задаётся всякий раз, когда страница заполнена, поэтому последняя страница может оказаться пустой. Каждый элемент содержит дескриптор, заданный при загрузке; текущие метки и метаданные — в getAnnotations.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
repository | путь | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
after | запрос | string (uuid) | нет | — |
limit | запрос | integer | нет | 1–100; по умолчанию 50 |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
items | массив object | нет | — |
items[].id | string (uuid) | да | — |
items[].repository | string | да | — |
items[].status | string | да | одно из pending, available, cancelled |
items[].createdAt | string (date-time) | да | — |
items[].expiresAt | string (date-time) | да | — |
items[].descriptor | object | да | — |
items[].descriptor.name | string | да | 1–240 символов |
items[].descriptor.size | string | да | целое число десятичными цифрами, передаётся строкой |
items[].descriptor.sha256 | string | да | SHA-256: 64 строчные шестнадцатеричные цифры |
items[].descriptor.labels | массив string | нет | не больше 32 элементов; каждый элемент: не длиннее 64 символов |
items[].descriptor.metadata | словарь string | нет | не больше 32 записей |
next | string | нет | может быть null |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Получить артефакт
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}
Доступ: Право в репозитории: artifact.read; файловые ключи: read · Повтор: Можно повторять (чтение)
Возвращает опубликованный артефакт: его ID, репозиторий, статус, время создания и дескриптор, заданный при загрузке (имя, размер, SHA-256, исходные метки и метаданные). Незавершённые, отменённые и удалённые артефакты отвечают 404. Чтобы прочитать байты, используйте downloadArtifact.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
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/artifacts/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Удалить артефакт
DELETE /api/v1/repositories/{repository}/artifacts/{id}
Доступ: Право в репозитории: artifact.delete · Повтор: Можно повторять: тот же запрос даёт тот же результат
Логически удаляет опубликованный артефакт: он сразу пропадает из списков, поиска и скачиваний, а его байты освобождает физическая очистка репозитория (setCleanup, по умолчанию выключена) по истечении защитного срока. expectedAnnotationRevision должна совпадать с текущей ревизией аннотаций. Ответ — 200 с outcome: deleted, already_deleted, changed (ревизия отличается), not_found или protected со списком blockers, которые не дают удалить артефакт (ссылка, ревизия пути файла, вложение сборки или стадия продвижения). Заранее проверьте через inspectArtifactDeletion.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
repository | путь | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | путь | string (uuid) | да | — |
Тело запроса (application/json)
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
expectedAnnotationRevision | integer | да | 0–2147483647 |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
id | string (uuid) | да | — |
outcome | string | да | одно из deleted, already_deleted, protected, changed, not_eligible, not_found |
blockers | массив string | да | не больше 4 элементов; без повторов; каждый элемент: одно из reference, asset_history, attachment_history, protected_label, promotion_stage |
Ответы: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Пример
curl -X DELETE "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"expectedAnnotationRevision":0}'Скачать артефакт
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/content
Доступ: Право в репозитории: content.read; файловые ключи: read · Повтор: Можно повторять (чтение)
Передаёт исходные байты потоком с заголовками Content-Length, Content-Disposition (имя артефакта) и сильным ETag ("sha256:<hex>"). Один Range даёт 206 (невыполнимый — 416); If-Range с ETag позволяет безопасно продолжить скачивание, а If-None-Match даёт 304. HEAD возвращает те же заголовки без тела и игнорирует Range. Вместо заголовка Authorization запрос может содержать в параметре token ссылку на скачивание из createDownloadLink; скачивания ждут свободного слота допуска скачиваний на сервере.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
repository | путь | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | путь | string (uuid) | да | — |
Range | заголовок | string | нет | — |
If-Range | заголовок | string | нет | — |
If-None-Match | заголовок | string | нет | — |
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. |
token | запрос | string | нет | по шаблону ^dtl_[A-Za-z0-9_-]{43}$; Download link from POST …/artifacts/{id}/links, instead of an Authorization header |
Ответы: 200, 206, 304, 400, 401, 403, 404, 409, 416, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/content" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-o fileПрочитать обзор площадок
GET HEAD /api/v1/fleet/overview
Доступ: Администратор · Повтор: Можно повторять (чтение)
Оповещения по управляемым площадкам и этой установке, самые серьёзные первыми (critical, warning, info), и связи зеркал между ними. Строится по последним фоновым опросам, не чаще раза в 5 секунд. Источник, по адресу которого не отвечает ни одна управляемая площадка, — external:<origin>; эта установка — self, и связи к ней видны только при заданном ARKVORY_SITE_URL. Отвечает только процесс записи.
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
generatedAt | string (date-time) | да | — |
self | object | да | — |
self.name | string | да | — |
self.version | string | да | — |
self.url | string | да | может быть null |
alerts | массив object | да | — |
alerts[].site | string | да | — |
alerts[].name | string | да | — |
alerts[].kind | string | да | одно из unreachable, certificate, revoked, refused, invalid, stale, not-writable, copies, single-copy, mirror-failing, mirror-lag, updates-failed, version-skew |
alerts[].severity | string | да | одно из critical, warning, info |
alerts[].subject | string | да | может быть null |
alerts[].since | string (date-time) | да | может быть null |
links | массив object | да | — |
links[].from | string | да | — |
links[].to | string | да | — |
links[].repository | string | да | — |
links[].sourceRepository | string | да | — |
links[].mode | string | да | одно из mirror, import |
links[].lagChanges | string | да | целое число десятичными цифрами, передаётся строкой; может быть null |
links[].failing | boolean | да | — |
links[].stale | boolean | нет | — |
external | массив string | да | — |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/fleet/overview" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Список управляемых площадок
GET HEAD /api/v1/fleet/sites
Доступ: Администратор · Повтор: Можно повторять (чтение)
Перечисляет площадки, которыми управляет эта установка (ADR 0077), и что каждая сообщила последней: state (ok или почему не прочитана: unreachable, certificate, revoked, invalid, refused), когда отвечала последний раз и последнюю topology. Площадки опрашиваются в фоне каждые 30 секунд. Ключ площадки не возвращается никогда.
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
items | массив object | да | не больше 256 элементов |
items[].id | string (uuid) | да | — |
items[].name | string | да | — |
items[].url | string | да | — |
items[].fingerprint | string | да | по шаблону ^[0-9a-f]{64}$; может быть null |
items[].addedBy | string | да | — |
items[].addedAt | string (date-time) | да | — |
items[].seenAt | string (date-time) | да | может быть null |
items[].state | string | да | одно из pending, ok, unreachable, certificate, revoked, invalid, refused |
items[].error | string | да | может быть null |
items[].topology | object | да | может быть null |
items[].topology.collectedAt | string (date-time) | да | — |
items[].topology.site | object | да | — |
items[].topology.health | object | да | — |
items[].topology.replication | object | да | может быть null |
items[].topology.gateways | массив object | да | не больше 16 элементов |
items[].topology.mirrors | массив object | да | не больше 64 элементов |
items[].topology.updates | object | да | может быть null |
items[].topology.downloads | object | да | — |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/fleet/sites" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Подключить площадку
POST /api/v1/fleet/sites
Доступ: Администратор · Повтор: Не повторять автоматически
Подключает площадку: управляющая площадка соединяется заново, сертификат должен по-прежнему иметь подтверждённый администратором fingerprint (null для HTTP на loopback), код сопряжения code, созданный на площадке, обменивается на ключ, ключ запечатывается ARKVORY_FLEET_KEY_FILE. До ответа площадка читается один раз. Без файла ключа ответ — 503.
Тело запроса (application/json)
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
url | string | да | — |
fingerprint | string | да | по шаблону ^[0-9a-f]{64}$; может быть null |
code | string | да | не длиннее 32 символов |
Ответ 201
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
id | string (uuid) | да | — |
name | string | да | — |
url | string | да | — |
fingerprint | string | да | по шаблону ^[0-9a-f]{64}$; может быть null |
addedBy | string | да | — |
addedAt | string (date-time) | да | — |
seenAt | string (date-time) | да | может быть null |
state | string | да | одно из pending, ok, unreachable, certificate, revoked, invalid, refused |
error | string | да | может быть null |
topology | object | да | может быть null |
topology.collectedAt | string (date-time) | да | — |
topology.site | object | да | — |
topology.site.name | string | да | — |
topology.site.version | string | да | — |
topology.site.schema | integer | да | не меньше 0 |
topology.site.role | string | да | одно из api, reader |
topology.health | object | да | — |
topology.health.available | boolean | да | — |
topology.health.writable | boolean | да | — |
topology.health.draining | boolean | да | — |
topology.replication | object | да | может быть null |
topology.replication.copies | integer | да | 0–16 |
topology.replication.required | integer | да | 1–16 |
topology.replication.singleCopyUntil | string (date-time) | да | может быть null |
topology.replication.node | string | нет | не длиннее 63 символов |
topology.replication.profile | string | нет | одно из ha-2, ha-3 |
topology.replication.peers | массив object | нет | не больше 16 элементов |
topology.gateways | массив object | да | не больше 16 элементов |
topology.gateways[].slot | integer | да | не меньше 0 |
topology.gateways[].active | boolean | да | — |
topology.gateways[].expiresAt | string (date-time) | да | — |
topology.mirrors | массив object | да | не больше 64 элементов |
topology.mirrors[].repository | string | да | — |
topology.mirrors[].mode | string | да | одно из mirror, import |
topology.mirrors[].upstream | string | да | — |
topology.mirrors[].sourceRepository | string | да | — |
topology.mirrors[].phase | string | да | — |
topology.mirrors[].errorCode | string | да | может быть null |
topology.mirrors[].checkedAt | string (date-time) | да | может быть null |
topology.mirrors[].syncedAt | string (date-time) | да | может быть null |
topology.mirrors[].lagChanges | string | да | целое число десятичными цифрами, передаётся строкой; может быть null |
topology.mirrors[].copiedArtifacts | integer | да | не меньше 0 |
topology.mirrors[].copiedBytes | string | да | целое число десятичными цифрами, передаётся строкой |
topology.updates | object | да | может быть null |
topology.updates.currentVersion | string | да | — |
topology.updates.latest | string | да | может быть null |
topology.updates.phase | string | да | — |
topology.updates.error | string | да | может быть null |
topology.updates.automatic | boolean | да | — |
topology.updates.heartbeatAt | string (date-time) | да | — |
topology.downloads | object | да | — |
topology.downloads.strategy | string | да | одно из ordered, smallest-first, shared |
topology.downloads.sessions | integer | да | не меньше 0 |
topology.downloads.active | integer | да | не меньше 0 |
topology.downloads.waiting | integer | да | не меньше 0 |
topology.downloads.oldestWaitSeconds | integer | да | не меньше 0 |
topology.downloads.bytesPerSecond | integer | да | не меньше 0 |
Ответы: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Пример
curl -X POST "$ARKVORY_URL/api/v1/fleet/sites" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"<url>","fingerprint":"<fingerprint>","code":"<code>"}'Прочитать сертификат площадки
POST /api/v1/fleet/sites/probe
Доступ: Администратор · Повтор: Можно повторять: тот же запрос даёт тот же результат
Соединяется с адресом и читает сертификат площадки, ничего не отправляя: сравните его fingerprint с тем, что видит администратор площадки, перед сопряжением.
Тело запроса (application/json)
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
url | string | да | — |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
url | string | да | — |
certificate | object | да | может быть null |
certificate.fingerprint | string | да | по шаблону ^[0-9a-f]{64}$ |
certificate.subject | string | да | — |
certificate.issuer | string | да | — |
certificate.validTo | string (date-time) | да | — |
Ответы: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Пример
curl -X POST "$ARKVORY_URL/api/v1/fleet/sites/probe" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"<url>"}'Забыть площадку
DELETE /api/v1/fleet/sites/{id}
Доступ: Администратор · Повтор: Можно повторять: тот же запрос даёт тот же результат
Удаляет площадку и её запечатанный ключ здесь. Отзовите эту управляющую площадку и на самой площадке: до тех пор ключ там действует.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
id | путь | string (uuid) | да | — |
Ответы: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
Пример
curl -X DELETE "$ARKVORY_URL/api/v1/fleet/sites/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Прочитать каталог площадки
GET HEAD /api/v1/fleet/sites/{id}/read
Доступ: Администратор · Повтор: Можно повторять (чтение)
Передаёт одно чтение каталога управляемой площадке и возвращает её ответ без изменений: репозитории, поиск, артефакты, аннотации, стадии, пакеты, страницы и история файлов, занятое место, состояние зеркала. path — маршрут площадки с параметрами запроса. Другие маршруты и байты файлов отклоняются с 400.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
id | путь | string (uuid) | да | — |
path | запрос | string | да | по шаблону ^/api/v1/; не длиннее 2048 символов; A read route of the site with its query, from a fixed list: catalog metadata (repositories, search, artifacts, annotations, stages, packages, file pages and history, storage usage, mirror state), download queue settings and update state. Never file bytes. |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/fleet/sites/$ID/read?path=$PATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Изменить настройку площадки
POST /api/v1/fleet/sites/{id}/change
Доступ: Администратор · Повтор: Не повторять автоматически
Передаёт одно изменение управляемой площадке и возвращает её ответ без изменений. path — один из маршрутов: /api/v1/system/downloads/settings (настройки очереди скачиваний, отправляется как PUT) или /api/v1/system/updates/requests (запрос обновления, отправляется как POST). Тело уходит на площадку как есть; площадка проверяет ревизию или id запроса, поэтому повтор не применяется дважды. Другие пути отклоняются с 400.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
id | путь | string (uuid) | да | — |
path | запрос | string | да | по шаблону ^/api/v1/; не длиннее 2048 символов; A change route of the site, from a fixed list: PUT /api/v1/system/downloads/settings, POST /api/v1/system/updates/requests. |
Тело запроса (application/json)
Ответы: 200, 202, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Пример
curl -X POST "$ARKVORY_URL/api/v1/fleet/sites/$ID/change?path=$PATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'Прочитать площадку сейчас
POST /api/v1/fleet/sites/{id}/refresh
Доступ: Администратор · Повтор: Можно повторять: тот же запрос даёт тот же результат
Читает площадку сейчас, не дожидаясь следующего круга, и возвращает её с новым состоянием.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
id | путь | string (uuid) | да | — |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
id | string (uuid) | да | — |
name | string | да | — |
url | string | да | — |
fingerprint | string | да | по шаблону ^[0-9a-f]{64}$; может быть null |
addedBy | string | да | — |
addedAt | string (date-time) | да | — |
seenAt | string (date-time) | да | может быть null |
state | string | да | одно из pending, ok, unreachable, certificate, revoked, invalid, refused |
error | string | да | может быть null |
topology | object | да | может быть null |
topology.collectedAt | string (date-time) | да | — |
topology.site | object | да | — |
topology.site.name | string | да | — |
topology.site.version | string | да | — |
topology.site.schema | integer | да | не меньше 0 |
topology.site.role | string | да | одно из api, reader |
topology.health | object | да | — |
topology.health.available | boolean | да | — |
topology.health.writable | boolean | да | — |
topology.health.draining | boolean | да | — |
topology.replication | object | да | может быть null |
topology.replication.copies | integer | да | 0–16 |
topology.replication.required | integer | да | 1–16 |
topology.replication.singleCopyUntil | string (date-time) | да | может быть null |
topology.replication.node | string | нет | не длиннее 63 символов |
topology.replication.profile | string | нет | одно из ha-2, ha-3 |
topology.replication.peers | массив object | нет | не больше 16 элементов |
topology.gateways | массив object | да | не больше 16 элементов |
topology.gateways[].slot | integer | да | не меньше 0 |
topology.gateways[].active | boolean | да | — |
topology.gateways[].expiresAt | string (date-time) | да | — |
topology.mirrors | массив object | да | не больше 64 элементов |
topology.mirrors[].repository | string | да | — |
topology.mirrors[].mode | string | да | одно из mirror, import |
topology.mirrors[].upstream | string | да | — |
topology.mirrors[].sourceRepository | string | да | — |
topology.mirrors[].phase | string | да | — |
topology.mirrors[].errorCode | string | да | может быть null |
topology.mirrors[].checkedAt | string (date-time) | да | может быть null |
topology.mirrors[].syncedAt | string (date-time) | да | может быть null |
topology.mirrors[].lagChanges | string | да | целое число десятичными цифрами, передаётся строкой; может быть null |
topology.mirrors[].copiedArtifacts | integer | да | не меньше 0 |
topology.mirrors[].copiedBytes | string | да | целое число десятичными цифрами, передаётся строкой |
topology.updates | object | да | может быть null |
topology.updates.currentVersion | string | да | — |
topology.updates.latest | string | да | может быть null |
topology.updates.phase | string | да | — |
topology.updates.error | string | да | может быть null |
topology.updates.automatic | boolean | да | — |
topology.updates.heartbeatAt | string (date-time) | да | — |
topology.downloads | object | да | — |
topology.downloads.strategy | string | да | одно из ordered, smallest-first, shared |
topology.downloads.sessions | integer | да | не меньше 0 |
topology.downloads.active | integer | да | не меньше 0 |
topology.downloads.waiting | integer | да | не меньше 0 |
topology.downloads.oldestWaitSeconds | integer | да | не меньше 0 |
topology.downloads.bytesPerSecond | integer | да | не меньше 0 |
Ответы: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
Пример
curl -X POST "$ARKVORY_URL/api/v1/fleet/sites/$ID/refresh" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Создать код сопряжения
POST /api/v1/system/fleet/pairings
Доступ: Администратор · Повтор: Не повторять автоматически
Создаёт одноразовый код на десять минут, который администратор управляющей площадки вводит, чтобы управлять этой. Код показывается один раз и хранится только как хеш. Создать его может только глобальный администратор площадки.
Ответ 201
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
code | string | да | по шаблону ^[0-9A-Z]{4}-[0-9A-Z]{4}-[0-9A-Z]{4}$ |
expiresAt | string (date-time) | да | — |
fingerprint | string | да | по шаблону ^[0-9a-f]{64}$; может быть null |
Ответы: 201, 400, 401, 403, 404, 405, 409, 422, 503, 507
Пример
curl -X POST "$ARKVORY_URL/api/v1/system/fleet/pairings" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Список управляющих площадки
GET HEAD /api/v1/system/fleet/controllers
Доступ: Администратор · Повтор: Можно повторять (чтение)
Перечисляет управляющие площадки, которым разрешено управлять этой: имя, кто сопряг, когда и когда ключ использовался последний раз.
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
items | массив object | да | не больше 100 элементов |
items[].id | string (uuid) | да | — |
items[].name | string | да | — |
items[].pairedBy | string | да | — |
items[].pairedAt | string (date-time) | да | — |
items[].usedAt | string (date-time) | да | может быть null |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/system/fleet/controllers" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Отозвать управляющую площадку
DELETE /api/v1/system/fleet/controllers/{id}
Доступ: Администратор · Повтор: Можно повторять: тот же запрос даёт тот же результат
Отзывает управляющую площадку: её ключ сразу перестаёт приниматься. Чтобы снова управлять площадкой, нужно сопряжение с новым кодом.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
id | путь | string (uuid) | да | — |
Ответы: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
Пример
curl -X DELETE "$ARKVORY_URL/api/v1/system/fleet/controllers/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Сопрячь с управляющей площадкой
POST /api/v1/system/fleet/enrollment
Доступ: Любой, без ключа · Повтор: Не повторять автоматически
Один раз обменивает действующий код сопряжения на ключ управления. Управляющая площадка вызывает его по TLS, закреплённому на отпечатке, который подтвердил администратор. Ключ возвращается один раз и открывает только нужные управляющей площадке маршруты.
Тело запроса (application/json)
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
code | string | да | не длиннее 32 символов |
name | string | да | 1–63 символов |
Ответ 201
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
key | string | да | по шаблону ^afk_[A-Za-z0-9_-]{43}$ |
site | object | да | — |
site.name | string | да | — |
site.version | string | да | — |
Ответы: 201, 400, 403, 405, 413, 415, 503
Пример
curl -X POST "$ARKVORY_URL/api/v1/system/fleet/enrollment" \
-H "Content-Type: application/json" \
-d '{"code":"<code>","name":"<name>"}'Получить площадку для единой консоли
GET HEAD /api/v1/system/topology
Доступ: Администратор · Повтор: Можно повторять (чтение)
Возвращает установку как одну площадку парка (ADR 0077): имя, версию, схему и роль, доступна ли она и принимает ли запись, копии и узлы HA, шлюзы чтения по их арендам, каждое зеркало и импорт с фазой, последней синхронизацией и lagChanges (ещё не применённые изменения источника), состояние агента обновлений и очередь скачиваний. Читать может только глобальный администратор площадки или сопряжённый с ней управляющий.
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
collectedAt | string (date-time) | да | — |
site | object | да | — |
site.name | string | да | — |
site.version | string | да | — |
site.schema | integer | да | не меньше 0 |
site.role | string | да | одно из api, reader |
health | object | да | — |
health.available | boolean | да | — |
health.writable | boolean | да | — |
health.draining | boolean | да | — |
replication | object | да | может быть null |
replication.copies | integer | да | 0–16 |
replication.required | integer | да | 1–16 |
replication.singleCopyUntil | string (date-time) | да | может быть null |
replication.node | string | нет | не длиннее 63 символов |
replication.profile | string | нет | одно из ha-2, ha-3 |
replication.peers | массив object | нет | не больше 16 элементов |
replication.peers[].name | string | да | не длиннее 63 символов |
replication.peers[].connected | boolean | да | — |
replication.peers[].disk | string | да | не длиннее 24 символов |
replication.peers[].complete | boolean | да | — |
replication.peers[].witness | boolean | да | — |
gateways | массив object | да | не больше 16 элементов |
gateways[].slot | integer | да | не меньше 0 |
gateways[].active | boolean | да | — |
gateways[].expiresAt | string (date-time) | да | — |
mirrors | массив object | да | не больше 64 элементов |
mirrors[].repository | string | да | — |
mirrors[].mode | string | да | одно из mirror, import |
mirrors[].upstream | string | да | — |
mirrors[].sourceRepository | string | да | — |
mirrors[].phase | string | да | — |
mirrors[].errorCode | string | да | может быть null |
mirrors[].checkedAt | string (date-time) | да | может быть null |
mirrors[].syncedAt | string (date-time) | да | может быть null |
mirrors[].lagChanges | string | да | целое число десятичными цифрами, передаётся строкой; может быть null |
mirrors[].copiedArtifacts | integer | да | не меньше 0 |
mirrors[].copiedBytes | string | да | целое число десятичными цифрами, передаётся строкой |
updates | object | да | может быть null |
updates.currentVersion | string | да | — |
updates.latest | string | да | может быть null |
updates.phase | string | да | — |
updates.error | string | да | может быть null |
updates.automatic | boolean | да | — |
updates.heartbeatAt | string (date-time) | да | — |
downloads | object | да | — |
downloads.strategy | string | да | одно из ordered, smallest-first, shared |
downloads.sessions | integer | да | не меньше 0 |
downloads.active | integer | да | не меньше 0 |
downloads.waiting | integer | да | не меньше 0 |
downloads.oldestWaitSeconds | integer | да | не меньше 0 |
downloads.bytesPerSecond | integer | да | не меньше 0 |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/system/topology" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Прочитать настройки очереди скачиваний
GET HEAD /api/v1/system/downloads/settings
Доступ: Администратор · Повтор: Можно повторять (чтение)
Возвращает изменённые значения (overrides), значения из окружения сервера (defaults) и то, что очередь использует сейчас (effective), а также ревизию, которую нужно передать при изменении. problem объясняет, почему сохранённые настройки не подходят этому серверу; тогда очередь работает на значениях по умолчанию.
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
revision | integer | да | 0–9007199254740991 |
overrides | object | да | — |
overrides.strategy | string | нет | одно из ordered, smallest-first, shared |
overrides.sessions | integer | нет | 1–1024 |
overrides.reserve | integer | нет | 0–1023 |
overrides.perPrincipal | integer | нет | 1–1024 |
overrides.weights | object | нет | — |
overrides.weights.interactive | integer | да | 1–1000 |
overrides.weights.release | integer | да | 1–1000 |
overrides.weights.bulk | integer | да | 1–1000 |
overrides.weights.background | integer | да | 1–1000 |
overrides.sessionMinBytes | integer | нет | 0–9007199254740991 |
overrides.idleSeconds | integer | нет | 1–3600 |
overrides.agingMinutes | integer | нет | 0–10080 |
overrides.preempt | boolean | нет | — |
overrides.rangesPerSession | integer | нет | 1–64 |
defaults | object | да | — |
defaults.strategy | string | да | одно из ordered, smallest-first, shared |
defaults.sessions | integer | да | 1–1024 |
defaults.reserve | integer | да | 0–1023 |
defaults.perPrincipal | integer | да | 1–1024 |
defaults.weights | object | да | — |
defaults.weights.interactive | integer | да | 1–1000 |
defaults.weights.release | integer | да | 1–1000 |
defaults.weights.bulk | integer | да | 1–1000 |
defaults.weights.background | integer | да | 1–1000 |
defaults.sessionMinBytes | integer | да | 0–9007199254740991 |
defaults.idleSeconds | integer | да | 1–3600 |
defaults.agingMinutes | integer | да | 0–10080 |
defaults.preempt | boolean | да | — |
defaults.rangesPerSession | integer | да | 1–64 |
effective | object | да | — |
effective.strategy | string | да | одно из ordered, smallest-first, shared |
effective.sessions | integer | да | 1–1024 |
effective.reserve | integer | да | 0–1023 |
effective.perPrincipal | integer | да | 1–1024 |
effective.weights | object | да | — |
effective.weights.interactive | integer | да | 1–1000 |
effective.weights.release | integer | да | 1–1000 |
effective.weights.bulk | integer | да | 1–1000 |
effective.weights.background | integer | да | 1–1000 |
effective.sessionMinBytes | integer | да | 0–9007199254740991 |
effective.idleSeconds | integer | да | 1–3600 |
effective.agingMinutes | integer | да | 0–10080 |
effective.preempt | boolean | да | — |
effective.rangesPerSession | integer | да | 1–64 |
admission | string | да | одно из sessions, per-request |
updatedAt | string (date-time) | да | может быть null |
updatedBy | string | да | может быть null |
actor | string | да | может быть null |
problem | string | да | может быть null |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/system/downloads/settings" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Изменить настройки очереди скачиваний
PUT /api/v1/system/downloads/settings
Доступ: Администратор · Повтор: Повтор только с ожидаемой ревизией (compare-and-swap)
Сохраняет overrides поверх окружения сервера и применяет их без перезапуска: новые решения сразу следуют им, активные скачивания сохраняют места. Переданные значения заменяют все прежние изменения; {} возвращает к окружению. Настройки, которые не могут работать на этом сервере, отклоняются с 400 и именем поля; устаревшая expectedRevision получает 409. Шлюзы чтения сохраняют своё окружение.
Тело запроса (application/json)
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
expectedRevision | integer | да | 0–9007199254740991 |
overrides | object | да | — |
overrides.strategy | string | нет | одно из ordered, smallest-first, shared |
overrides.sessions | integer | нет | 1–1024 |
overrides.reserve | integer | нет | 0–1023 |
overrides.perPrincipal | integer | нет | 1–1024 |
overrides.weights | object | нет | — |
overrides.weights.interactive | integer | да | 1–1000 |
overrides.weights.release | integer | да | 1–1000 |
overrides.weights.bulk | integer | да | 1–1000 |
overrides.weights.background | integer | да | 1–1000 |
overrides.sessionMinBytes | integer | нет | 0–9007199254740991 |
overrides.idleSeconds | integer | нет | 1–3600 |
overrides.agingMinutes | integer | нет | 0–10080 |
overrides.preempt | boolean | нет | — |
overrides.rangesPerSession | integer | нет | 1–64 |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
revision | integer | да | 0–9007199254740991 |
overrides | object | да | — |
overrides.strategy | string | нет | одно из ordered, smallest-first, shared |
overrides.sessions | integer | нет | 1–1024 |
overrides.reserve | integer | нет | 0–1023 |
overrides.perPrincipal | integer | нет | 1–1024 |
overrides.weights | object | нет | — |
overrides.weights.interactive | integer | да | 1–1000 |
overrides.weights.release | integer | да | 1–1000 |
overrides.weights.bulk | integer | да | 1–1000 |
overrides.weights.background | integer | да | 1–1000 |
overrides.sessionMinBytes | integer | нет | 0–9007199254740991 |
overrides.idleSeconds | integer | нет | 1–3600 |
overrides.agingMinutes | integer | нет | 0–10080 |
overrides.preempt | boolean | нет | — |
overrides.rangesPerSession | integer | нет | 1–64 |
defaults | object | да | — |
defaults.strategy | string | да | одно из ordered, smallest-first, shared |
defaults.sessions | integer | да | 1–1024 |
defaults.reserve | integer | да | 0–1023 |
defaults.perPrincipal | integer | да | 1–1024 |
defaults.weights | object | да | — |
defaults.weights.interactive | integer | да | 1–1000 |
defaults.weights.release | integer | да | 1–1000 |
defaults.weights.bulk | integer | да | 1–1000 |
defaults.weights.background | integer | да | 1–1000 |
defaults.sessionMinBytes | integer | да | 0–9007199254740991 |
defaults.idleSeconds | integer | да | 1–3600 |
defaults.agingMinutes | integer | да | 0–10080 |
defaults.preempt | boolean | да | — |
defaults.rangesPerSession | integer | да | 1–64 |
effective | object | да | — |
effective.strategy | string | да | одно из ordered, smallest-first, shared |
effective.sessions | integer | да | 1–1024 |
effective.reserve | integer | да | 0–1023 |
effective.perPrincipal | integer | да | 1–1024 |
effective.weights | object | да | — |
effective.weights.interactive | integer | да | 1–1000 |
effective.weights.release | integer | да | 1–1000 |
effective.weights.bulk | integer | да | 1–1000 |
effective.weights.background | integer | да | 1–1000 |
effective.sessionMinBytes | integer | да | 0–9007199254740991 |
effective.idleSeconds | integer | да | 1–3600 |
effective.agingMinutes | integer | да | 0–10080 |
effective.preempt | boolean | да | — |
effective.rangesPerSession | integer | да | 1–64 |
admission | string | да | одно из sessions, per-request |
updatedAt | string (date-time) | да | может быть null |
updatedBy | string | да | может быть null |
actor | string | да | может быть null |
problem | string | да | может быть null |
Ответы: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Пример
curl -X PUT "$ARKVORY_URL/api/v1/system/downloads/settings" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"expectedRevision":0,"overrides":{}}'Прочитать изменения площадки
GET HEAD /api/v1/system/changes
Доступ: Администратор · Повтор: Можно повторять (чтение)
Возвращает, отвечает ли агент площадки (agent), ожидающий запрос и 20 последних с состоянием: pending, applying, done или failed с причиной. Ключей источников здесь нет никогда.
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
agent | boolean | да | — |
updating | boolean | да | — |
blocked | string | да | одно из expired, interrupted, key_missing, not_a_mirror, already_attached, mirror_failed, switchover_failed, single_copy_failed, unreadable, digest_mismatch, null; может быть null |
pending | object | да | может быть null |
pending.id | string (uuid) | да | — |
pending.kind | string | да | одно из mirror-attach, mirror-key, mirror-detach, cluster-switchover, single-copy |
pending.actor | string | да | не длиннее 200 символов |
pending.requestedAt | string (date-time) | да | — |
recent | массив object | да | не больше 20 элементов |
recent[].id | string (uuid) | да | — |
recent[].digest | string | да | по шаблону ^[0-9a-f]{64}$ |
recent[].kind | string | да | одно из mirror-attach, mirror-key, mirror-detach, cluster-switchover, single-copy |
recent[].state | string | да | одно из pending, applying, done, failed |
recent[].error | string | да | одно из expired, interrupted, key_missing, not_a_mirror, already_attached, mirror_failed, switchover_failed, single_copy_failed, unreadable, digest_mismatch, null; может быть null |
recent[].actor | string | да | не длиннее 200 символов |
recent[].requestedAt | string (date-time) | да | — |
recent[].finishedAt | string (date-time) | да | может быть null |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/system/changes" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Поставить изменение площадки в очередь
POST /api/v1/system/changes
Доступ: Администратор · Повтор: Можно повторять: тот же запрос даёт тот же результат
Ставит одно изменение для агента площадки; он применяет его в течение минуты с проверками и откатом arkvory configure и cluster-*: подключить зеркало или импорт, заменить ключ источника, отключить зеркала, перевести активный узел HA (имя узла вводится дважды) или принять запись с одной копией. id выбирает клиент; повтор не ставит изменение второй раз. key — ключ источника только для mirror-attach и mirror-key: он уходит агенту отдельным файлом 0600 и никогда не возвращается. 202 означает «в очереди», а не «применено».
Тело запроса (application/json)
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
id | string (uuid) | да | — |
change | object | да | — |
change.kind | string | да | одно из mirror-attach |
change.repository | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
change.upstream | string | да | не длиннее 255 символов |
change.sourceRepository | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
change.stages | массив string | нет | 1–16 элементов; каждый элемент: по шаблону ^[a-z0-9][a-z0-9_.-]{0,31}$; может быть null |
change.repositories | массив string | да | 1–64 элементов; каждый элемент: по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
change.node | string | да | по шаблону ^[A-Za-z0-9][A-Za-z0-9_.-]{0,62}$ |
change.confirm | string | да | по шаблону ^[A-Za-z0-9][A-Za-z0-9_.-]{0,62}$ |
change.until | string (date-time) | да | может быть null |
change.reason | string | да | 1–200 символов |
key | string | нет | 16–4000 символов |
Ответ 202
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
id | string (uuid) | да | — |
Ответы: 202, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Пример
curl -X POST "$ARKVORY_URL/api/v1/system/changes" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"id":"00000000-0000-4000-8000-000000000000","change":{"kind":"mirror-attach","repository":"<repository>","upstream":"<upstream>","sourceRepository":"<sourceRepository>"}}'Следить за лентой изменений репозитория
GET HEAD /api/v1/repositories/{repository}/changes
Доступ: Право в репозитории: artifact.list; файловые ключи: read · Повтор: Можно повторять (чтение)
Возвращает в порядке фиксации до limit изменений (1–100, по умолчанию 100) после номера after (по умолчанию 0): действие, артефакт и, для путей файлов и стадий, путь или стадию в detail; инициаторы не указываются, поэтому достаточно доступа на чтение списка. head — новейший номер репозитория, next — курсор следующей страницы или null, если страница дошла до head. Зеркало сохраняет последний применённый номер и опрашивает с него.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
repository | путь | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
after | запрос | string | нет | целое число десятичными цифрами, передаётся строкой; Sequence cursor, default 0 |
limit | запрос | integer | нет | 1–100 |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
items | массив object | да | — |
items[].sequence | string | да | целое число десятичными цифрами, передаётся строкой |
items[].action | string | да | — |
items[].artifactId | string (uuid) | да | — |
items[].detail | string | да | может быть null |
head | string | да | целое число десятичными цифрами, передаётся строкой |
next | string | да | целое число десятичными цифрами, передаётся строкой; может быть null |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/changes" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Создать ссылку на скачивание
POST /api/v1/repositories/{repository}/artifacts/{id}/links
Доступ: Право в репозитории: content.read; файловые ключи: read · Повтор: Не повторять автоматически
Возвращает секретный token, url относительно адреса сервера API и expiresAt для downloadArtifact этого одного артефакта без ключа; ttlSeconds задаёт срок жизни (от 60 секунд до суток, по умолчанию час). Токен показывается только в этом ответе и не может быть отозван: он перестаёт действовать, когда истекает срок или удаляется артефакт, а скачивания по нему учитываются в лимитах передачи создателя. У вызывающего может быть 1000 действующих ссылок (507 token_limit), а ссылка на скачивание не может создавать новые ссылки.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
repository | путь | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | путь | string (uuid) | да | — |
Тело запроса (application/json)
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
ttlSeconds | integer | нет | 60–86400; по умолчанию 3600 |
Ответ 201
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
token | string | да | по шаблону ^dtl_[A-Za-z0-9_-]{43}$ |
url | string | да | — |
expiresAt | string (date-time) | да | — |
Ответы: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Пример
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/links" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'