انتقل إلى المحتوى

النسخ الاحتياطية ​

حالة وكيل النسخ الاحتياطي المدمج، وخطته، وعمليات تشغيله، ونقاطه، والتحقق، والاحتفاظ.

عمليات هذه المجموعة مع قاعدة الوصول وقاعدة إعادة المحاولة والمعلمات والاستجابات. يحمل كل طلب مفتاحًا: Authorization: Bearer <key> (راجع «المصادقة»).

العمليات ​

الحصول على حالة النسخ الاحتياطي ​

GET HEAD /api/v1/backup/status

الوصول: إذن النظام backup.read · إعادة المحاولة: آمن للتكرار (قراءة)

يلخّص نظام النسخ الاحتياطي: مخزن النسخ الاحتياطية (configured وavailable والبايتات الحرة والكلية)، ووكيل النسخ الاحتياطي (online وآخر نبضة (heartbeat) وإصداره)، والخطة، وأحدث نقطة مكتملة، والتشغيل المجدول التالي، والمهمة الجارية، وwarnings، وكل منها رمز مثل agent_offline أو backup_stale بخطورة warning أو critical. ويُبلَّغ عن المخزن بأنه غير متاح ما دام الوكيل غير متصل. ولا يتضمن مسارات ولا أسرارًا.

الاستجابة 200

الحقلالنوعمطلوبالقواعد
vaultobjectنعم—
vault.configuredbooleanنعم—
vault.idstring (uuid)نعميمكن أن يكون null
vault.availablebooleanنعم—
vault.encryptedbooleanنعميمكن أن يكون null; هل الخزنة مشفّرة؛ القيمة null عند عدم المعرفة أو عدم الاتصال.
vault.freeBytesstringنعمعدد صحيح بأرقام عشرية، يُرسَل كسلسلة نصية; يمكن أن يكون null
vault.totalBytesstringنعمعدد صحيح بأرقام عشرية، يُرسَل كسلسلة نصية; يمكن أن يكون null
agentobjectنعم—
agent.onlinebooleanنعم—
agent.lastSeenAtstring (date-time)نعميمكن أن يكون null
agent.versionstringنعمعدد الأحرف: 64 كحد أقصى; يمكن أن يكون null
planobjectنعم—
plan.enabledbooleanنعم—
plan.hourintegerنعم0–23
plan.minuteintegerنعم0–59
plan.timezonestringنعمعدد الأحرف: 1–64; منطقة زمنية صريحة من IANA، مثل Europe/Moscow؛ يتحقق منها الخادم.
plan.retentionobjectنعم—
plan.retention.dailyintegerنعم0–366
plan.retention.weeklyintegerنعم0–260
plan.retention.monthlyintegerنعم0–120
plan.revisionintegerنعم0–2147483647
lastCompletedobjectنعميمكن أن يكون null
lastCompleted.idstring (uuid)نعم—
lastCompleted.snapshotAtstring (date-time)نعموقت اللقطة T؛ ويُحتسب عمر النقطة منذ T.
lastCompleted.completedAtstring (date-time)نعم—
lastCompleted.blobsintegerنعم0 على الأقل
lastCompleted.contentBytesstringنعمعدد صحيح بأرقام عشرية، يُرسَل كسلسلة نصية
lastCompleted.newBytesstringنعمعدد صحيح بأرقام عشرية، يُرسَل كسلسلة نصية; البايتات التي أضافتها هذه النقطة إلى المخزن.
lastCompleted.tablesintegerنعم0 على الأقل
lastCompleted.rowsintegerنعم0 على الأقل
lastCompleted.pinnedbooleanنعم—
lastCompleted.verifiedAtstring (date-time)نعميمكن أن يكون null
lastCompleted.verifyDepthstringنعمإحدى القيم: structural, deep, null; يمكن أن يكون null
lastCompleted.verifyErrorstringنعميطابق النمط ^[a-z][a-z0-9_]{0,63}$; يمكن أن يكون null
nextRunAtstring (date-time)نعميمكن أن يكون null
runningobjectنعميمكن أن يكون null
running.idstring (uuid)نعم—
running.kindstringنعمإحدى القيم: capture, verify, retention
running.statestringنعمإحدى القيم: queued, running, committing, completed, failed, interrupted
running.phasestringنعميطابق النمط ^[a-z][a-z0-9_]{0,63}$; يمكن أن يكون null
running.startedAtstring (date-time)نعمبداية التنفيذ، أو وقت الطلب ما دام في الطابور.
running.finishedAtstring (date-time)نعميمكن أن يكون null
running.errorCodestringنعميطابق النمط ^[a-z][a-z0-9_]{0,63}$; يمكن أن يكون null
running.pointIdstring (uuid)نعميمكن أن يكون null
running.progressobjectنعم—
running.progress.bytesCopiedstringنعمعدد صحيح بأرقام عشرية، يُرسَل كسلسلة نصية; البايتات المعالَجة: المنسوخة أو الموجودة بالفعل في المخزن.
running.progress.bytesTotalstringنعمعدد صحيح بأرقام عشرية، يُرسَل كسلسلة نصية
running.progress.blobsCopiedintegerنعم0 على الأقل
running.progress.blobsTotalintegerنعم0 على الأقل
warningsمصفوفة من objectنعمعدد العناصر: 10 كحد أقصى
warnings[].codestringنعمإحدى القيم: 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[].severitystringنعمإحدى القيم: warning, critical

الاستجابات: 200, 400, 401, 403, 404, 409, 422, 503, 507

مثال

bash
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 في المنطقة الزمنية IANA timezone) وسياسة الاحتفاظ (نقاط daily وweekly وmonthly المراد الاحتفاظ بها) مع revision التي تُرسل مرة أخرى إلى updateBackupPlan. وما لم تتغير الخطة تكون معطّلة، بجدول 02:00 UTC و7 نقاط يومية و4 أسبوعية و6 شهرية.

الاستجابة 200

الحقلالنوعمطلوبالقواعد
enabledbooleanنعم—
hourintegerنعم0–23
minuteintegerنعم0–59
timezonestringنعمعدد الأحرف: 1–64; منطقة زمنية صريحة من IANA، مثل Europe/Moscow؛ يتحقق منها الخادم.
retentionobjectنعم—
retention.dailyintegerنعم0–366
retention.weeklyintegerنعم0–260
retention.monthlyintegerنعم0–120
revisionintegerنعم0–2147483647

الاستجابات: 200, 400, 401, 403, 404, 409, 422, 503, 507

مثال

bash
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)

الحقلالنوعمطلوبالقواعد
expectedRevisionintegerنعم0–2147483647
enabledbooleanنعم—
hourintegerنعم0–23
minuteintegerنعم0–59
timezonestringنعمعدد الأحرف: 1–64; منطقة زمنية صريحة من IANA، مثل Europe/Moscow؛ يتحقق منها الخادم.
retentionobjectنعم—
retention.dailyintegerنعم0–366
retention.weeklyintegerنعم0–260
retention.monthlyintegerنعم0–120

الاستجابة 200

الحقلالنوعمطلوبالقواعد
enabledbooleanنعم—
hourintegerنعم0–23
minuteintegerنعم0–59
timezonestringنعمعدد الأحرف: 1–64; منطقة زمنية صريحة من IANA، مثل Europe/Moscow؛ يتحقق منها الخادم.
retentionobjectنعم—
retention.dailyintegerنعم0–366
retention.weeklyintegerنعم0–260
retention.monthlyintegerنعم0–120
revisionintegerنعم0–2147483647

الاستجابات: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

مثال

bash
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 نفسه

يضع في الطابور عملية التقاط (capture) للوكيل خارج الجدول ويردّ بـ 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

الحقلالنوعمطلوبالقواعد
idstring (uuid)نعم—
kindstringنعمإحدى القيم: capture, verify, retention
statestringنعمإحدى القيم: queued, running, committing, completed, failed, interrupted

الاستجابات: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507

مثال

bash
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 · إعادة المحاولة: آمن للتكرار (قراءة)

يسرد مهام الالتقاط والتحقق والاحتفاظ، بدءًا من الأحدث، لكل منها 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[].idstring (uuid)نعم—
items[].kindstringنعمإحدى القيم: capture, verify, retention
items[].statestringنعمإحدى القيم: queued, running, committing, completed, failed, interrupted
items[].phasestringنعميطابق النمط ^[a-z][a-z0-9_]{0,63}$; يمكن أن يكون null
items[].startedAtstring (date-time)نعمبداية التنفيذ، أو وقت الطلب ما دام في الطابور.
items[].finishedAtstring (date-time)نعميمكن أن يكون null
items[].errorCodestringنعميطابق النمط ^[a-z][a-z0-9_]{0,63}$; يمكن أن يكون null
items[].pointIdstring (uuid)نعميمكن أن يكون null
items[].progressobjectنعم—
items[].progress.bytesCopiedstringنعمعدد صحيح بأرقام عشرية، يُرسَل كسلسلة نصية; البايتات المعالَجة: المنسوخة أو الموجودة بالفعل في المخزن.
items[].progress.bytesTotalstringنعمعدد صحيح بأرقام عشرية، يُرسَل كسلسلة نصية
items[].progress.blobsCopiedintegerنعم0 على الأقل
items[].progress.blobsTotalintegerنعم0 على الأقل
nextstringنعميطابق النمط ^[0-9]{1,17}_[0-9a-f-]{36}$; يمكن أن يكون null

الاستجابات: 200, 400, 401, 403, 404, 409, 422, 503, 507

مثال

bash
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[].idstring (uuid)نعم—
items[].snapshotAtstring (date-time)نعموقت اللقطة T؛ ويُحتسب عمر النقطة منذ T.
items[].completedAtstring (date-time)نعم—
items[].blobsintegerنعم0 على الأقل
items[].contentBytesstringنعمعدد صحيح بأرقام عشرية، يُرسَل كسلسلة نصية
items[].newBytesstringنعمعدد صحيح بأرقام عشرية، يُرسَل كسلسلة نصية; البايتات التي أضافتها هذه النقطة إلى المخزن.
items[].tablesintegerنعم0 على الأقل
items[].rowsintegerنعم0 على الأقل
items[].pinnedbooleanنعم—
items[].verifiedAtstring (date-time)نعميمكن أن يكون null
items[].verifyDepthstringنعمإحدى القيم: structural, deep, null; يمكن أن يكون null
items[].verifyErrorstringنعميطابق النمط ^[a-z][a-z0-9_]{0,63}$; يمكن أن يكون null
nextstringنعميطابق النمط ^[0-9]{1,17}_[0-9a-f-]{36}$; يمكن أن يكون null

الاستجابات: 200, 400, 401, 403, 404, 409, 422, 503, 507

مثال

bash
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

الحقلالنوعمطلوبالقواعد
idstring (uuid)نعم—
kindstringنعمإحدى القيم: capture, verify, retention
statestringنعمإحدى القيم: queued, running, committing, completed, failed, interrupted

الاستجابات: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507

مثال

bash
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)

الحقلالنوعمطلوبالقواعد
pinnedbooleanنعم—

الاستجابة 200

الحقلالنوعمطلوبالقواعد
idstring (uuid)نعم—
snapshotAtstring (date-time)نعموقت اللقطة T؛ ويُحتسب عمر النقطة منذ T.
completedAtstring (date-time)نعم—
blobsintegerنعم0 على الأقل
contentBytesstringنعمعدد صحيح بأرقام عشرية، يُرسَل كسلسلة نصية
newBytesstringنعمعدد صحيح بأرقام عشرية، يُرسَل كسلسلة نصية; البايتات التي أضافتها هذه النقطة إلى المخزن.
tablesintegerنعم0 على الأقل
rowsintegerنعم0 على الأقل
pinnedbooleanنعم—
verifiedAtstring (date-time)نعميمكن أن يكون null
verifyDepthstringنعمإحدى القيم: structural, deep, null; يمكن أن يكون null
verifyErrorstringنعميطابق النمط ^[a-z][a-z0-9_]{0,63}$; يمكن أن يكون null

الاستجابات: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

مثال

bash
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[].idstring (uuid)نعم—
keep[].reasonsمصفوفة من stringنعمكل عنصر: إحدى القيم: daily, weekly, monthly, pinned, newest
deleteمصفوفة من objectنعم—
delete[].idstring (uuid)نعم—

الاستجابات: 200, 400, 401, 403, 404, 409, 422, 503, 507

مثال

bash
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

الحقلالنوعمطلوبالقواعد
idstring (uuid)نعم—
kindstringنعمإحدى القيم: capture, verify, retention
statestringنعمإحدى القيم: queued, running, committing, completed, failed, interrupted

الاستجابات: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507

مثال

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

Arkvory · ProAnimaStudio