Backups

Status, Plan, Läufe, Wiederherstellungspunkte, Prüfung und Aufbewahrung des integrierten Backup-Agenten.

Die Vorgänge dieser Gruppe mit ihrer Zugriffsregel, Wiederholungsregel, ihren Parametern und Antworten. Jede Anfrage trägt einen Schlüssel: Authorization: Bearer <Schlüssel> (siehe „Authentifizierung“).

Vorgänge

Backup-Status abrufen

GET HEAD /api/v1/backup/status

Zugriff: Systemberechtigung backup.read · Wiederholung: Wiederholen ist sicher (Lesen)

Fasst das Backup-System zusammen: den Backup-Speicher (configured, available, freie und gesamte Bytes), den Backup-Agent (online, letzter Heartbeat, Version), den Plan, den neuesten abgeschlossenen Wiederherstellungspunkt, den nächsten geplanten Lauf, den laufenden Job und warnings, jede ein Code wie agent_offline oder backup_stale mit dem Schweregrad warning oder critical. Der Backup-Speicher wird als nicht verfügbar gemeldet, solange der Agent offline ist. Die Antwort enthält keine Pfade oder Geheimnisse.

Antwort 200

Feld	Typ	Erforderlich	Regeln
vault	object	ja	—
vault.configured	boolean	ja	—
vault.id	string (uuid)	ja	darf null sein
vault.available	boolean	ja	—
vault.encrypted	boolean	ja	darf null sein; Das Vault ist verschlüsselt; null, wenn unbekannt oder nicht verbunden.
vault.freeBytes	string	ja	eine ganze Zahl in Dezimalziffern, als String gesendet; darf null sein
vault.totalBytes	string	ja	eine ganze Zahl in Dezimalziffern, als String gesendet; darf null sein
agent	object	ja	—
agent.online	boolean	ja	—
agent.lastSeenAt	string (date-time)	ja	darf null sein
agent.version	string	ja	höchstens 64 Zeichen; darf null sein
plan	object	ja	—
plan.enabled	boolean	ja	—
plan.hour	integer	ja	0–23
plan.minute	integer	ja	0–59
plan.timezone	string	ja	1–64 Zeichen; Explizite IANA-Zeitzone, z. B. Europe/Moscow; wird vom Server validiert.
plan.retention	object	ja	—
plan.retention.daily	integer	ja	0–366
plan.retention.weekly	integer	ja	0–260
plan.retention.monthly	integer	ja	0–120
plan.revision	integer	ja	0–2147483647
lastCompleted	object	ja	darf null sein
lastCompleted.id	string (uuid)	ja	—
lastCompleted.snapshotAt	string (date-time)	ja	Snapshot-Zeitpunkt T; das Alter eines Punkts zählt ab T.
lastCompleted.completedAt	string (date-time)	ja	—
lastCompleted.blobs	integer	ja	mindestens 0
lastCompleted.contentBytes	string	ja	eine ganze Zahl in Dezimalziffern, als String gesendet
lastCompleted.newBytes	string	ja	eine ganze Zahl in Dezimalziffern, als String gesendet; Bytes, die dieser Punkt zum Backup-Speicher hinzugefügt hat.
lastCompleted.tables	integer	ja	mindestens 0
lastCompleted.rows	integer	ja	mindestens 0
lastCompleted.pinned	boolean	ja	—
lastCompleted.verifiedAt	string (date-time)	ja	darf null sein
lastCompleted.verifyDepth	string	ja	einer von structural, deep, null; darf null sein
lastCompleted.verifyError	string	ja	entspricht ^[a-z][a-z0-9_]{0,63}$; darf null sein
nextRunAt	string (date-time)	ja	darf null sein
running	object	ja	darf null sein
running.id	string (uuid)	ja	—
running.kind	string	ja	einer von capture, verify, retention
running.state	string	ja	einer von queued, running, committing, completed, failed, interrupted
running.phase	string	ja	entspricht ^[a-z][a-z0-9_]{0,63}$; darf null sein
running.startedAt	string (date-time)	ja	Beginn der Ausführung oder, solange eingereiht, die Zeit der Anfrage.
running.finishedAt	string (date-time)	ja	darf null sein
running.errorCode	string	ja	entspricht ^[a-z][a-z0-9_]{0,63}$; darf null sein
running.pointId	string (uuid)	ja	darf null sein
running.progress	object	ja	—
running.progress.bytesCopied	string	ja	eine ganze Zahl in Dezimalziffern, als String gesendet; Verarbeitete Bytes: kopiert oder bereits im Backup-Speicher.
running.progress.bytesTotal	string	ja	eine ganze Zahl in Dezimalziffern, als String gesendet
running.progress.blobsCopied	integer	ja	mindestens 0
running.progress.blobsTotal	integer	ja	mindestens 0
warnings	Array von object	ja	höchstens 10 Elemente
warnings[].code	string	ja	einer von 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	ja	einer von warning, critical

Antworten: 200, 400, 401, 403, 404, 409, 422, 503, 507

Beispiel

curl -X GET "$ARKVORY_URL/api/v1/backup/status" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Backup-Plan abrufen

GET HEAD /api/v1/backup/plan

Zugriff: Systemberechtigung backup.read · Wiederholung: Wiederholen ist sicher (Lesen)

Liefert den täglichen Zeitplan (enabled, hour und minute in der IANA-timezone) und die Aufbewahrungsrichtlinie (daily, weekly, monthly aufzubewahrende Punkte) mit der revision, die Sie an updateBackupPlan zurücksenden. Bis zu einer Änderung ist der Plan deaktiviert, mit einem Zeitplan um 02:00 UTC und 7 täglichen, 4 wöchentlichen und 6 monatlichen Punkten.

Antwort 200

Feld	Typ	Erforderlich	Regeln
enabled	boolean	ja	—
hour	integer	ja	0–23
minute	integer	ja	0–59
timezone	string	ja	1–64 Zeichen; Explizite IANA-Zeitzone, z. B. Europe/Moscow; wird vom Server validiert.
retention	object	ja	—
retention.daily	integer	ja	0–366
retention.weekly	integer	ja	0–260
retention.monthly	integer	ja	0–120
revision	integer	ja	0–2147483647

Antworten: 200, 400, 401, 403, 404, 409, 422, 503, 507

Beispiel

curl -X GET "$ARKVORY_URL/api/v1/backup/plan" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Backup-Plan ersetzen

PUT /api/v1/backup/plan

Zugriff: Systemberechtigung backup.manage · Wiederholung: Nur mit der erwarteten Revision wiederholen (compare-and-swap)

Ersetzt den gesamten Plan: enabled, hour (0–23), minute (0–59), timezone und retention (höchstens 366 tägliche, 260 wöchentliche, 120 monatliche) müssen alle vorhanden sein. expectedRevision muss die aktuelle Revision sein, sonst 409 revision_mismatch; ein ungültiges Feld ergibt 400 mit einem JSON Pointer in details. Der Agent folgt dem neuen Zeitplan ab seiner nächsten Prüfung.

Anfragetext (application/json)

Feld	Typ	Erforderlich	Regeln
expectedRevision	integer	ja	0–2147483647
enabled	boolean	ja	—
hour	integer	ja	0–23
minute	integer	ja	0–59
timezone	string	ja	1–64 Zeichen; Explizite IANA-Zeitzone, z. B. Europe/Moscow; wird vom Server validiert.
retention	object	ja	—
retention.daily	integer	ja	0–366
retention.weekly	integer	ja	0–260
retention.monthly	integer	ja	0–120

Antwort 200

Feld	Typ	Erforderlich	Regeln
enabled	boolean	ja	—
hour	integer	ja	0–23
minute	integer	ja	0–59
timezone	string	ja	1–64 Zeichen; Explizite IANA-Zeitzone, z. B. Europe/Moscow; wird vom Server validiert.
retention	object	ja	—
retention.daily	integer	ja	0–366
retention.weekly	integer	ja	0–260
retention.monthly	integer	ja	0–120
revision	integer	ja	0–2147483647

Antworten: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Beispiel

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}}'

Ein Backup jetzt anfordern

POST /api/v1/backup/runs

Zugriff: Systemberechtigung backup.manage · Wiederholung: Wiederholen ist sicher mit demselben Idempotency-Key

Reiht außerhalb des Zeitplans eine Erfassung für den Backup-Agent ein und liefert 202 mit dem Job (kind capture); der Agent führt sie aus, danach Verifikation und Aufbewahrung. Idempotency-Key ist erforderlich: Dessen Wiederholung durch denselben Aufrufer liefert denselben Job. Verfolgen Sie den Job in listBackupJobs. Höchstens 100 Backup-Anforderungen dürfen gleichzeitig offen sein (507 queue_full); solange kein Agent online ist, wartet der Job.

Parameter

Name	Ort	Typ	Erforderlich	Regeln
Idempotency-Key	Header	string	ja	entspricht ^[A-Za-z0-9_.:-]{1,128}$; Repeat returns the same job; per caller and operation kind.

Antwort 202

Feld	Typ	Erforderlich	Regeln
id	string (uuid)	ja	—
kind	string	ja	einer von capture, verify, retention
state	string	ja	einer von queued, running, committing, completed, failed, interrupted

Antworten: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507

Beispiel

curl -X POST "$ARKVORY_URL/api/v1/backup/runs" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Backup-Jobs auflisten

GET HEAD /api/v1/backup/jobs

Zugriff: Systemberechtigung backup.read · Wiederholung: Wiederholen ist sicher (Lesen)

Listet die Jobs zur Erfassung, Verifikation und Aufbewahrung auf, neueste zuerst, jeweils mit state (queued, running, committing, completed, failed, interrupted), phase, Zeiten, errorCode, dem entstandenen Punkt und progress (verarbeitete Bytes und Objekte). Seiten enthalten limit Jobs (1–100, Standard 50); weiter mit after = next.

Parameter

Name	Ort	Typ	Erforderlich	Regeln
after	Query	string	nein	entspricht ^[0-9]{1,17}_[0-9a-f-]{36}$; next of the previous page
limit	Query	integer	nein	1–100; Standard 50

Antwort 200

Feld	Typ	Erforderlich	Regeln
items	Array von object	ja	höchstens 100 Elemente
items[].id	string (uuid)	ja	—
items[].kind	string	ja	einer von capture, verify, retention
items[].state	string	ja	einer von queued, running, committing, completed, failed, interrupted
items[].phase	string	ja	entspricht ^[a-z][a-z0-9_]{0,63}$; darf null sein
items[].startedAt	string (date-time)	ja	Beginn der Ausführung oder, solange eingereiht, die Zeit der Anfrage.
items[].finishedAt	string (date-time)	ja	darf null sein
items[].errorCode	string	ja	entspricht ^[a-z][a-z0-9_]{0,63}$; darf null sein
items[].pointId	string (uuid)	ja	darf null sein
items[].progress	object	ja	—
items[].progress.bytesCopied	string	ja	eine ganze Zahl in Dezimalziffern, als String gesendet; Verarbeitete Bytes: kopiert oder bereits im Backup-Speicher.
items[].progress.bytesTotal	string	ja	eine ganze Zahl in Dezimalziffern, als String gesendet
items[].progress.blobsCopied	integer	ja	mindestens 0
items[].progress.blobsTotal	integer	ja	mindestens 0
next	string	ja	entspricht ^[0-9]{1,17}_[0-9a-f-]{36}$; darf null sein

Antworten: 200, 400, 401, 403, 404, 409, 422, 503, 507

Beispiel

curl -X GET "$ARKVORY_URL/api/v1/backup/jobs" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Wiederherstellungspunkte auflisten

GET HEAD /api/v1/backup/points

Zugriff: Systemberechtigung backup.read · Wiederholung: Wiederholen ist sicher (Lesen)

Listet die abgeschlossenen Wiederherstellungspunkte des aktuellen Backup-Speichers auf, neuester Snapshot zuerst, jeweils mit dem Snapshot-Zeitpunkt T, der Größe, den zum Backup-Speicher hinzugekommenen Bytes, der Angabe, ob er pinned (angeheftet) ist, und seiner letzten Verifikation (verifiedAt, verifyDepth structural oder deep, verifyError). Seiten enthalten limit Punkte (1–100, Standard 50); weiter mit after = next. Ein ersetzter Backup-Speicher zeigt nur seine eigenen Punkte.

Parameter

Name	Ort	Typ	Erforderlich	Regeln
after	Query	string	nein	entspricht ^[0-9]{1,17}_[0-9a-f-]{36}$; next of the previous page
limit	Query	integer	nein	1–100; Standard 50

Antwort 200

Feld	Typ	Erforderlich	Regeln
items	Array von object	ja	höchstens 100 Elemente
items[].id	string (uuid)	ja	—
items[].snapshotAt	string (date-time)	ja	Snapshot-Zeitpunkt T; das Alter eines Punkts zählt ab T.
items[].completedAt	string (date-time)	ja	—
items[].blobs	integer	ja	mindestens 0
items[].contentBytes	string	ja	eine ganze Zahl in Dezimalziffern, als String gesendet
items[].newBytes	string	ja	eine ganze Zahl in Dezimalziffern, als String gesendet; Bytes, die dieser Punkt zum Backup-Speicher hinzugefügt hat.
items[].tables	integer	ja	mindestens 0
items[].rows	integer	ja	mindestens 0
items[].pinned	boolean	ja	—
items[].verifiedAt	string (date-time)	ja	darf null sein
items[].verifyDepth	string	ja	einer von structural, deep, null; darf null sein
items[].verifyError	string	ja	entspricht ^[a-z][a-z0-9_]{0,63}$; darf null sein
next	string	ja	entspricht ^[0-9]{1,17}_[0-9a-f-]{36}$; darf null sein

Antworten: 200, 400, 401, 403, 404, 409, 422, 503, 507

Beispiel

curl -X GET "$ARKVORY_URL/api/v1/backup/points" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Tiefenprüfung eines Wiederherstellungspunkts anfordern

POST /api/v1/backup/points/{id}/verify

Zugriff: Systemberechtigung backup.manage · Wiederholung: Wiederholen ist sicher mit demselben Idempotency-Key

Reiht eine Verifikation des Punkts id ein, die jedes gespeicherte Byte von ihm liest; die Antwort ist 202 mit dem Job, und das Ergebnis erscheint in verifiedAt, verifyDepth und verifyError des Punkts. Idempotency-Key ist erforderlich, und seine Wiederverwendung für einen anderen Punkt ergibt 409 idempotency_mismatch. Ein unbekannter Punkt ergibt 404.

Parameter

Name	Ort	Typ	Erforderlich	Regeln
id	Pfad	string (uuid)	ja	—
Idempotency-Key	Header	string	ja	entspricht ^[A-Za-z0-9_.:-]{1,128}$; Repeat returns the same job; per caller and operation kind.

Antwort 202

Feld	Typ	Erforderlich	Regeln
id	string (uuid)	ja	—
kind	string	ja	einer von capture, verify, retention
state	string	ja	einer von queued, running, committing, completed, failed, interrupted

Antworten: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507

Beispiel

curl -X POST "$ARKVORY_URL/api/v1/backup/points/$ID/verify" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Wiederherstellungspunkt anheften oder Anheftung aufheben

PUT /api/v1/backup/points/{id}/pin

Zugriff: Systemberechtigung backup.manage · Wiederholung: Wiederholen ist sicher: Dieselbe Anfrage hat dieselbe Wirkung

Setzt pinned des Punkts id; ein angehefteter Punkt wird von der Aufbewahrung über die Richtlinie hinaus behalten, bis die Anheftung aufgehoben wird. Denselben Wert erneut zu setzen ändert nichts, und die Antwort ist der aktualisierte Punkt. Ein unbekannter oder bereits vergessener Punkt ergibt 404.

Parameter

Name	Ort	Typ	Erforderlich	Regeln
id	Pfad	string (uuid)	ja	—

Anfragetext (application/json)

Feld	Typ	Erforderlich	Regeln
pinned	boolean	ja	—

Antwort 200

Feld	Typ	Erforderlich	Regeln
id	string (uuid)	ja	—
snapshotAt	string (date-time)	ja	Snapshot-Zeitpunkt T; das Alter eines Punkts zählt ab T.
completedAt	string (date-time)	ja	—
blobs	integer	ja	mindestens 0
contentBytes	string	ja	eine ganze Zahl in Dezimalziffern, als String gesendet
newBytes	string	ja	eine ganze Zahl in Dezimalziffern, als String gesendet; Bytes, die dieser Punkt zum Backup-Speicher hinzugefügt hat.
tables	integer	ja	mindestens 0
rows	integer	ja	mindestens 0
pinned	boolean	ja	—
verifiedAt	string (date-time)	ja	darf null sein
verifyDepth	string	ja	einer von structural, deep, null; darf null sein
verifyError	string	ja	entspricht ^[a-z][a-z0-9_]{0,63}$; darf null sein

Antworten: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Beispiel

curl -X PUT "$ARKVORY_URL/api/v1/backup/points/$ID/pin" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pinned":false}'

Vorschau anzeigen, was die Backup-Aufbewahrung behält

GET HEAD /api/v1/backup/retention/preview

Zugriff: Systemberechtigung backup.read · Wiederholung: Wiederholen ist sicher (Lesen)

Zeigt, welche Punkte die Aufbewahrungsrichtlinie behalten würde, jeweils mit den Gründen (daily, weekly, monthly, pinned, newest), und welche sie jetzt löschen würde. Punkte, die die Verifikation nicht bestanden haben, werden nicht berücksichtigt. Die Vorschau ist unverbindlich: requestBackupRetention entscheidet beim Lauf erneut anhand des Backup-Speichers.

Antwort 200

Feld	Typ	Erforderlich	Regeln
keep	Array von object	ja	—
keep[].id	string (uuid)	ja	—
keep[].reasons	Array von string	ja	jedes Element: einer von daily, weekly, monthly, pinned, newest
delete	Array von object	ja	—
delete[].id	string (uuid)	ja	—

Antworten: 200, 400, 401, 403, 404, 409, 422, 503, 507

Beispiel

curl -X GET "$ARKVORY_URL/api/v1/backup/retention/preview" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Backup-Aufbewahrung anfordern

POST /api/v1/backup/retention/apply

Zugriff: Systemberechtigung backup.manage · Wiederholung: Wiederholen ist sicher mit demselben Idempotency-Key

Reiht einen Aufbewahrungs-Job ein: Der Agent vergisst die Punkte außerhalb der Richtlinie und entfernt dann Inhalte, die kein verbleibender Punkt mehr verwendet, sodass der Speicherplatz erst nach Abschluss des Jobs in den Backup-Speicher zurückkehrt. Liefert 202 mit dem Job; Idempotency-Key ist erforderlich, und seine Wiederholung liefert denselben Job. Sehen Sie sich zuerst previewBackupRetention an.

Parameter

Name	Ort	Typ	Erforderlich	Regeln
Idempotency-Key	Header	string	ja	entspricht ^[A-Za-z0-9_.:-]{1,128}$; Repeat returns the same job; per caller and operation kind.

Antwort 202

Feld	Typ	Erforderlich	Regeln
id	string (uuid)	ja	—
kind	string	ja	einer von capture, verify, retention
state	string	ja	einer von queued, running, committing, completed, failed, interrupted

Antworten: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507

Beispiel

curl -X POST "$ARKVORY_URL/api/v1/backup/retention/apply" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"