Система и состояние
Живость, готовность, метрики, документ OpenAPI и возможности сервера.
Операции этой группы с правилом доступа, правилом повтора, параметрами и ответами. Каждый запрос несёт ключ: Authorization: Bearer <ключ> (см. «Аутентификация»).
Операции
Проверить подробную готовность
GET HEAD /health/ready
Доступ: Любой действующий ключ или сессия · Повтор: Можно повторять (чтение)
Отвечает ready, когда база данных и хранилище откликаются, и сообщает role этого узла (api или reader), принимает ли он сейчас запись (writable равно false на шлюзе чтения и пока на диске остаётся только резерв свободного места), общий слот скачивания шлюза чтения, а также сводные счётчики допуска и полосы пропускания для загрузок и скачиваний. Пока сервер останавливается, завершая текущие запросы, или зависимость недоступна, он отвечает 503 с Retry-After. Запрос не учитывается в лимите запросов; для балансировщика без ключа используйте getReadinessStatus.
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
role | string | да | одно из api, reader |
sharedDownloads | object | да | может быть null |
sharedDownloads.slot | integer | да | не меньше 0 |
sharedDownloads.slots | integer | да | не меньше 0 |
sharedDownloads.active | boolean | да | — |
sharedDownloads.leaseSeconds | integer | да | не меньше 0 |
status | string | да | одно из ready |
writable | 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 | да | — |
transfers | object | да | — |
transfers.uploads | object | да | — |
transfers.uploads.admission | object | да | — |
transfers.uploads.bandwidth | object | да | — |
transfers.uploads.sessions | object | нет | — |
transfers.downloads | object | да | — |
transfers.downloads.admission | object | да | — |
transfers.downloads.bandwidth | object | да | — |
transfers.downloads.sessions | object | нет | — |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/health/ready" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Получить возможности и ограничения сервера
GET HEAD /api/v1/capabilities
Доступ: Любой действующий ключ или сессия · Повтор: Можно повторять (чтение)
Возвращает версии API, роль шлюза, флаги возможностей (например, selfRegistration или mirrorFeed) и ограничения, под которые подстраивается клиент: наибольший объект (maxObjectBytes, десятичная строка), наименьший и наибольший размер части при загрузке по частям, наибольшее число частей и наибольший размер страницы. Прочитайте его один раз при запуске клиента; ресурсов он не перечисляет.
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
apiVersions | массив string | да | — |
gatewayRole | string | да | одно из api, reader |
features | словарь boolean | да | — |
limits | object | да | — |
limits.maxObjectBytes | string | нет | целое число десятичными цифрами, передаётся строкой |
limits.partBytes | integer | нет | Наименьшая часть при загрузке по частям. |
limits.maxPartBytes | integer | нет | — |
limits.maxParts | integer | нет | — |
limits.maxPageSize | integer | нет | — |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/capabilities" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Проверить готовность для балансировщика
GET HEAD /health/status
Доступ: Любой, без ключа · Повтор: Можно повторять (чтение)
Не требует ключа и не возвращает подробностей: 200 с {"status":"ready"} или 503 с unavailable или draining и Retry-After. Проверка зависимостей общая и кэшируется на одну секунду, поэтому частые пробы не нагружают базу данных; проба не учитывается в лимите запросов.
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
status | string | да | одно из ready, unavailable, draining |
Ответы: 200, 400, 403, 503
Пример
curl -X GET "$ARKVORY_URL/health/status"Проверить, что процесс жив
GET HEAD /health/live
Доступ: Любой, без ключа · Повтор: Можно повторять (чтение)
Возвращает 200 с {"status":"ok"}, пока процесс отвечает по HTTP. Зависимости не проверяются, поэтому по этому ответу решайте о перезапуске, а по getReadinessStatus — о направлении трафика.
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
status | string | да | одно из ok |
Ответы: 200, 400, 403, 503
Пример
curl -X GET "$ARKVORY_URL/health/live"Получить документ OpenAPI
GET HEAD /api/v1/openapi.json
Доступ: Любой действующий ключ или сессия · Повтор: Можно повторять (чтение)
Возвращает документ OpenAPI 3.0 этого развёртывания с расширениями x-arkvory-*, которые описывают правила доступа, повтора и шлюза каждой операции. surface (discovery, identity, catalog, transfers, administration или operations) возвращает только эту область; неизвестный или повторяющийся параметр запроса — ошибка 400. Документ одинаков для всех вызывающих и ничего не разрешает: чтобы узнать, что можно вызывать с этими учётными данными, используйте listVisibleOperations.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
surface | запрос | string | нет | одно из discovery, identity, catalog, transfers, administration, operations; Documentation view only; not filtered by caller permissions. |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
openapi | string | да | одно из 3.0.3 |
info | object | да | — |
paths | object | да | — |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/openapi.json" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Получить метрики Prometheus
GET HEAD /health/metrics
Доступ: Любой действующий ключ или сессия · Повтор: Можно повторять (чтение)
Возвращает метрики процесса в текстовом формате Prometheus (text/plain; version=0.0.4) для сборщика метрик. Счётчики и гистограммы относятся к этому процессу и после перезапуска начинаются с нуля (см. arkvory_process_start_time_seconds); метки ограничены шаблоном маршрута, методом, классом статуса и направлением передачи и никогда не называют артефакт, ключ или учётную запись. Сбор метрик не учитывается в лимите запросов.
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/health/metrics" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-o fileПеречислить операции, которые можно вызвать с этими учётными данными
GET HEAD /api/v1/operations
Доступ: Любой действующий ключ или сессия · Повтор: Можно повторять (чтение)
Перечисляет в порядке operationId операции этого шлюза, которые можно вызвать с этими учётными данными; для каждой указаны область (surface), правило повтора, требуемые действия и conditions, проверяемые только в момент вызова (например, resource-state или upload-owner). repository добавляет операции этого репозитория (неизвестный или чужой репозиторий — 404), surface сужает список до одной области; страницы содержат limit элементов (1–100, по умолчанию 50), продолжайте с after, равным next. Ответ носит справочный характер: стройте по нему меню, но каждый реальный запрос авторизуется заново, а шлюз чтения не показывает изменяющие методы.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
repository | запрос | string | нет | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$ |
surface | запрос | string | нет | одно из discovery, identity, catalog, transfers, administration, operations |
after | запрос | string | нет | по шаблону ^[A-Za-z][A-Za-z0-9]{0,95}$ |
limit | запрос | integer | нет | 1–100; по умолчанию 50 |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
apiVersion | string | да | одно из v1 |
documentVersion | string | да | по шаблону ^\d+\.\d+\.\d+$ |
gatewayRole | string | да | одно из api, reader |
repository | string | да | по шаблону ^[a-z0-9][a-z0-9_-]{0,63}$; может быть null |
advisory | boolean | да | одно из true |
items | массив object | да | не больше 100 элементов |
items[].operationId | string | да | по шаблону ^[A-Za-z][A-Za-z0-9]{0,95}$ |
items[].method | string | да | одно из get, head, post, put, patch, delete |
items[].path | string | да | по шаблону ^/; не длиннее 512 символов |
items[].summary | string | да | не длиннее 1024 символов |
items[].surface | string | да | одно из discovery, identity, catalog, transfers, administration, operations |
items[].visibility | string | да | одно из public, authenticated, self, repository, owned-resource, delegated, bootstrap, administrator |
items[].retry | string | да | одно из read, never-automatic, idempotent, idempotency-key, compare-and-swap, reconcile-upload, reconcile-job |
items[].requiredActions | массив string | да | не больше 33 элементов; без повторов; каждый элемент: одно из repository.read, storage.read, storage.manage, diagnostics.read, artifact.read, artifact.list, artifact.delete, artifact.promote, content.read, upload.create, upload.read, upload.write, upload.complete, upload.cancel, job.read, package.read, package.publish, asset.read, asset.write, asset.restore, annotation.read, annotation.write, reference.write, audit.read, service-account.read, service-account.manage, policy.read, policy.manage, credential.read, credential.manage, service-audit.read, backup.read, backup.manage |
items[].conditions | массив string | да | не больше 6 элементов; без повторов; каждый элемент: одно из resource-state, upload-owner, job-owner, reference-owner, delegation-target-and-ceiling, own-key |
next | string | да | по шаблону ^[A-Za-z][A-Za-z0-9]{0,95}$; может быть null |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/operations" \
-H "Authorization: Bearer $ARKVORY_TOKEN"