Резервные копии
Состояние, план, запуски, точки, проверка и хранение копий встроенного агента.
Операции этой группы с правилом доступа, правилом повтора, параметрами и ответами. Каждый запрос несёт ключ: Authorization: Bearer <ключ> (см. «Аутентификация»).
Операции
Получить состояние резервного копирования
GET HEAD /api/v1/backup/status
Доступ: Системное право backup.read · Повтор: Можно повторять (чтение)
Сводка по системе резервного копирования: хранилище копий (configured, available, свободные и общие байты), агент резервного копирования (online, последний heartbeat, версия), план, новейшая завершённая точка, следующий плановый запуск, выполняющееся задание и warnings — каждое с кодом вроде agent_offline или backup_stale и серьёзностью warning или critical. Пока агент не в сети, хранилище считается недоступным. Путей и секретов в ответе нет.
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
vault | object | да | — |
vault.configured | boolean | да | — |
vault.id | string (uuid) | да | может быть null |
vault.available | boolean | да | — |
vault.encrypted | boolean | да | может быть null; Хранилище зашифровано; null, если неизвестно или не подключено. |
vault.freeBytes | string | да | целое число десятичными цифрами, передаётся строкой; может быть null |
vault.totalBytes | string | да | целое число десятичными цифрами, передаётся строкой; может быть null |
agent | object | да | — |
agent.online | boolean | да | — |
agent.lastSeenAt | string (date-time) | да | может быть null |
agent.version | string | да | не длиннее 64 символов; может быть null |
plan | object | да | — |
plan.enabled | boolean | да | — |
plan.hour | integer | да | 0–23 |
plan.minute | integer | да | 0–59 |
plan.timezone | string | да | 1–64 символов; Явный часовой пояс IANA, например Europe/Moscow; проверяется сервером. |
plan.retention | object | да | — |
plan.retention.daily | integer | да | 0–366 |
plan.retention.weekly | integer | да | 0–260 |
plan.retention.monthly | integer | да | 0–120 |
plan.revision | integer | да | 0–2147483647 |
lastCompleted | object | да | может быть null |
lastCompleted.id | string (uuid) | да | — |
lastCompleted.snapshotAt | string (date-time) | да | Время снимка T; возраст точки отсчитывается от T. |
lastCompleted.completedAt | string (date-time) | да | — |
lastCompleted.blobs | integer | да | не меньше 0 |
lastCompleted.contentBytes | string | да | целое число десятичными цифрами, передаётся строкой |
lastCompleted.newBytes | string | да | целое число десятичными цифрами, передаётся строкой; Байты, которые эта точка добавила в хранилище копий. |
lastCompleted.tables | integer | да | не меньше 0 |
lastCompleted.rows | integer | да | не меньше 0 |
lastCompleted.pinned | boolean | да | — |
lastCompleted.verifiedAt | string (date-time) | да | может быть null |
lastCompleted.verifyDepth | string | да | одно из structural, deep, null; может быть null |
lastCompleted.verifyError | string | да | по шаблону ^[a-z][a-z0-9_]{0,63}$; может быть null |
nextRunAt | string (date-time) | да | может быть null |
running | object | да | может быть null |
running.id | string (uuid) | да | — |
running.kind | string | да | одно из capture, verify, retention |
running.state | string | да | одно из queued, running, committing, completed, failed, interrupted |
running.phase | string | да | по шаблону ^[a-z][a-z0-9_]{0,63}$; может быть null |
running.startedAt | string (date-time) | да | Начало выполнения или время запроса, пока задание в очереди. |
running.finishedAt | string (date-time) | да | может быть null |
running.errorCode | string | да | по шаблону ^[a-z][a-z0-9_]{0,63}$; может быть null |
running.pointId | string (uuid) | да | может быть null |
running.progress | object | да | — |
running.progress.bytesCopied | string | да | целое число десятичными цифрами, передаётся строкой; Обработанные байты: скопированные или уже находящиеся в хранилище копий. |
running.progress.bytesTotal | string | да | целое число десятичными цифрами, передаётся строкой |
running.progress.blobsCopied | integer | да | не меньше 0 |
running.progress.blobsTotal | integer | да | не меньше 0 |
warnings | массив object | да | не больше 10 элементов |
warnings[].code | string | да | одно из vault_not_configured, agent_offline, schedule_disabled, no_backup_yet, backup_stale, last_run_failed, vault_unavailable, vault_low_space, verify_failed, never_deep_verified |
warnings[].severity | string | да | одно из warning, critical |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/backup/status" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Получить план резервного копирования
GET HEAD /api/v1/backup/plan
Доступ: Системное право backup.read · Повтор: Можно повторять (чтение)
Возвращает ежедневное расписание (enabled, hour и minute в часовом поясе timezone из базы IANA) и политику хранения (сколько точек daily, weekly, monthly оставлять) с revision, которую нужно передать в updateBackupPlan. Пока план не менялся, он выключен, с расписанием 02:00 UTC и 7 ежедневными, 4 еженедельными и 6 ежемесячными точками.
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
enabled | boolean | да | — |
hour | integer | да | 0–23 |
minute | integer | да | 0–59 |
timezone | string | да | 1–64 символов; Явный часовой пояс IANA, например Europe/Moscow; проверяется сервером. |
retention | object | да | — |
retention.daily | integer | да | 0–366 |
retention.weekly | integer | да | 0–260 |
retention.monthly | integer | да | 0–120 |
revision | integer | да | 0–2147483647 |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/backup/plan" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Заменить план резервного копирования
PUT /api/v1/backup/plan
Доступ: Системное право backup.manage · Повтор: Повтор только с ожидаемой ревизией (compare-and-swap)
Заменяет план целиком: enabled, hour (0–23), minute (0–59), timezone и retention (не более 366 ежедневных, 260 еженедельных, 120 ежемесячных) должны быть заданы все. expectedRevision должна быть текущей ревизией, иначе 409 revision_mismatch; недопустимое поле — 400 с указателем JSON Pointer в details. Агент переходит на новое расписание со своей следующей проверки.
Тело запроса (application/json)
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
expectedRevision | integer | да | 0–2147483647 |
enabled | boolean | да | — |
hour | integer | да | 0–23 |
minute | integer | да | 0–59 |
timezone | string | да | 1–64 символов; Явный часовой пояс IANA, например Europe/Moscow; проверяется сервером. |
retention | object | да | — |
retention.daily | integer | да | 0–366 |
retention.weekly | integer | да | 0–260 |
retention.monthly | integer | да | 0–120 |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
enabled | boolean | да | — |
hour | integer | да | 0–23 |
minute | integer | да | 0–59 |
timezone | string | да | 1–64 символов; Явный часовой пояс IANA, например Europe/Moscow; проверяется сервером. |
retention | object | да | — |
retention.daily | integer | да | 0–366 |
retention.weekly | integer | да | 0–260 |
retention.monthly | integer | да | 0–120 |
revision | integer | да | 0–2147483647 |
Ответы: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Пример
curl -X PUT "$ARKVORY_URL/api/v1/backup/plan" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"expectedRevision":0,"enabled":false,"hour":0,"minute":0,"timezone":"<timezone>","retention":{"daily":0,"weekly":0,"monthly":0}}'Запросить резервное копирование сейчас
POST /api/v1/backup/runs
Доступ: Системное право backup.manage · Повтор: Можно повторять с тем же Idempotency-Key
Ставит агенту резервного копирования задание на снятие копии вне расписания и возвращает 202 с заданием (kind равно capture); агент выполняет его, затем проверку и очистку по правилам хранения. Idempotency-Key обязателен: повтор от того же вызывающего возвращает то же задание. Следите за заданием через listBackupJobs. Одновременно может быть открыто не более 100 запросов на резервное копирование (507 queue_full); пока ни один агент не в сети, задание ждёт.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
Idempotency-Key | заголовок | string | да | по шаблону ^[A-Za-z0-9_.:-]{1,128}$; Repeat returns the same job; per caller and operation kind. |
Ответ 202
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
id | string (uuid) | да | — |
kind | string | да | одно из capture, verify, retention |
state | string | да | одно из queued, running, committing, completed, failed, interrupted |
Ответы: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507
Пример
curl -X POST "$ARKVORY_URL/api/v1/backup/runs" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"Перечислить задания резервного копирования
GET HEAD /api/v1/backup/jobs
Доступ: Системное право backup.read · Повтор: Можно повторять (чтение)
Перечисляет задания снятия копии (capture), проверки (verify) и применения правил хранения (retention) от новых к старым, каждое с состоянием state (queued, running, committing, completed, failed, interrupted), phase, временем, errorCode, полученной точкой и progress (обработанные байты и объекты). Страницы содержат limit заданий (1–100, по умолчанию 50); продолжайте с after, равным next.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
after | запрос | string | нет | по шаблону ^[0-9]{1,17}_[0-9a-f-]{36}$; next of the previous page |
limit | запрос | integer | нет | 1–100; по умолчанию 50 |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
items | массив object | да | не больше 100 элементов |
items[].id | string (uuid) | да | — |
items[].kind | string | да | одно из capture, verify, retention |
items[].state | string | да | одно из queued, running, committing, completed, failed, interrupted |
items[].phase | string | да | по шаблону ^[a-z][a-z0-9_]{0,63}$; может быть null |
items[].startedAt | string (date-time) | да | Начало выполнения или время запроса, пока задание в очереди. |
items[].finishedAt | string (date-time) | да | может быть null |
items[].errorCode | string | да | по шаблону ^[a-z][a-z0-9_]{0,63}$; может быть null |
items[].pointId | string (uuid) | да | может быть null |
items[].progress | object | да | — |
items[].progress.bytesCopied | string | да | целое число десятичными цифрами, передаётся строкой; Обработанные байты: скопированные или уже находящиеся в хранилище копий. |
items[].progress.bytesTotal | string | да | целое число десятичными цифрами, передаётся строкой |
items[].progress.blobsCopied | integer | да | не меньше 0 |
items[].progress.blobsTotal | integer | да | не меньше 0 |
next | string | да | по шаблону ^[0-9]{1,17}_[0-9a-f-]{36}$; может быть null |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/backup/jobs" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Перечислить точки восстановления
GET HEAD /api/v1/backup/points
Доступ: Системное право backup.read · Повтор: Можно повторять (чтение)
Перечисляет завершённые точки восстановления текущего хранилища копий от новых снимков к старым, каждую со временем снимка T, размером, байтами, добавленными в хранилище, признаком закрепления pinned и последней проверкой (verifiedAt, verifyDepth — structural или deep, verifyError). Страницы содержат limit точек (1–100, по умолчанию 50); продолжайте с after, равным next. Для заменённого хранилища показываются только его собственные точки.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
after | запрос | string | нет | по шаблону ^[0-9]{1,17}_[0-9a-f-]{36}$; next of the previous page |
limit | запрос | integer | нет | 1–100; по умолчанию 50 |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
items | массив object | да | не больше 100 элементов |
items[].id | string (uuid) | да | — |
items[].snapshotAt | string (date-time) | да | Время снимка T; возраст точки отсчитывается от T. |
items[].completedAt | string (date-time) | да | — |
items[].blobs | integer | да | не меньше 0 |
items[].contentBytes | string | да | целое число десятичными цифрами, передаётся строкой |
items[].newBytes | string | да | целое число десятичными цифрами, передаётся строкой; Байты, которые эта точка добавила в хранилище копий. |
items[].tables | integer | да | не меньше 0 |
items[].rows | integer | да | не меньше 0 |
items[].pinned | boolean | да | — |
items[].verifiedAt | string (date-time) | да | может быть null |
items[].verifyDepth | string | да | одно из structural, deep, null; может быть null |
items[].verifyError | string | да | по шаблону ^[a-z][a-z0-9_]{0,63}$; может быть null |
next | string | да | по шаблону ^[0-9]{1,17}_[0-9a-f-]{36}$; может быть null |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/backup/points" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Запросить глубокую проверку точки восстановления
POST /api/v1/backup/points/{id}/verify
Доступ: Системное право backup.manage · Повтор: Можно повторять с тем же Idempotency-Key
Ставит в очередь проверку точки id, которая читает каждый её сохранённый байт; ответ — 202 с заданием, а результат появляется в verifiedAt, verifyDepth и verifyError точки. Idempotency-Key обязателен, а его повторное использование для другой точки — 409 idempotency_mismatch. Неизвестная точка — 404.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
id | путь | string (uuid) | да | — |
Idempotency-Key | заголовок | string | да | по шаблону ^[A-Za-z0-9_.:-]{1,128}$; Repeat returns the same job; per caller and operation kind. |
Ответ 202
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
id | string (uuid) | да | — |
kind | string | да | одно из capture, verify, retention |
state | string | да | одно из queued, running, committing, completed, failed, interrupted |
Ответы: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507
Пример
curl -X POST "$ARKVORY_URL/api/v1/backup/points/$ID/verify" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"Закрепить или открепить точку восстановления
PUT /api/v1/backup/points/{id}/pin
Доступ: Системное право backup.manage · Повтор: Можно повторять: тот же запрос даёт тот же результат
Задаёт pinned точки id; закреплённая точка сохраняется правилами хранения сверх политики, пока её не открепят. Повторная установка того же значения ничего не меняет, а в ответе — обновлённая точка. Неизвестная или уже забытая точка — 404.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
id | путь | string (uuid) | да | — |
Тело запроса (application/json)
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
pinned | boolean | да | — |
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
id | string (uuid) | да | — |
snapshotAt | string (date-time) | да | Время снимка T; возраст точки отсчитывается от T. |
completedAt | string (date-time) | да | — |
blobs | integer | да | не меньше 0 |
contentBytes | string | да | целое число десятичными цифрами, передаётся строкой |
newBytes | string | да | целое число десятичными цифрами, передаётся строкой; Байты, которые эта точка добавила в хранилище копий. |
tables | integer | да | не меньше 0 |
rows | integer | да | не меньше 0 |
pinned | boolean | да | — |
verifiedAt | string (date-time) | да | может быть null |
verifyDepth | string | да | одно из structural, deep, null; может быть null |
verifyError | string | да | по шаблону ^[a-z][a-z0-9_]{0,63}$; может быть null |
Ответы: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Пример
curl -X PUT "$ARKVORY_URL/api/v1/backup/points/$ID/pin" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"pinned":false}'Просмотреть, что сохранят правила хранения копий
GET HEAD /api/v1/backup/retention/preview
Доступ: Системное право backup.read · Повтор: Можно повторять (чтение)
Показывает, какие точки политика хранения сохранила бы, каждую с причинами (daily, weekly, monthly, pinned, newest), и какие удалила бы сейчас. Точки, не прошедшие проверку, не учитываются. Просмотр носит справочный характер: requestBackupRetention при запуске решает заново по состоянию хранилища.
Ответ 200
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
keep | массив object | да | — |
keep[].id | string (uuid) | да | — |
keep[].reasons | массив string | да | каждый элемент: одно из daily, weekly, monthly, pinned, newest |
delete | массив object | да | — |
delete[].id | string (uuid) | да | — |
Ответы: 200, 400, 401, 403, 404, 409, 422, 503, 507
Пример
curl -X GET "$ARKVORY_URL/api/v1/backup/retention/preview" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Запросить применение правил хранения копий
POST /api/v1/backup/retention/apply
Доступ: Системное право backup.manage · Повтор: Можно повторять с тем же Idempotency-Key
Ставит в очередь задание хранения: агент забывает точки вне политики, а затем удаляет содержимое, которое не использует ни одна оставшаяся точка, поэтому место возвращается в хранилище только после завершения задания. Возвращает 202 с заданием; Idempotency-Key обязателен, и его повтор возвращает то же задание. Сначала посмотрите previewBackupRetention.
Параметры
| Имя | Где | Тип | Обязателен | Правила |
|---|---|---|---|---|
Idempotency-Key | заголовок | string | да | по шаблону ^[A-Za-z0-9_.:-]{1,128}$; Repeat returns the same job; per caller and operation kind. |
Ответ 202
| Поле | Тип | Обязателен | Правила |
|---|---|---|---|
id | string (uuid) | да | — |
kind | string | да | одно из capture, verify, retention |
state | string | да | одно из queued, running, committing, completed, failed, interrupted |
Ответы: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507
Пример
curl -X POST "$ARKVORY_URL/api/v1/backup/retention/apply" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"