المُخرَجات والفهرس

المُخرَجات المنشورة: السرد، والتفاصيل، والمحتوى، والتعليقات التوضيحية، والارتباطات، والبحث، وتدقيق الفهرس وموجز تغييراته.

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

العمليات

الحصول على التعليقات التوضيحية لمُخرَج

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 مرتبةً حسب المعرّف، لكل منها الحجم وأوقات الإنشاء والنشر والتسميات الحالية ومراحل الترقية؛ وللمتابعة اضبط 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; آخر معرّف في صفحة ممتلئة؛ مرّره بوصفه 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 حرفًا من الأحرف والأرقام أو _.:/-)، مثل اسم نشر (deployment). لا يمكن حذف المُخرَج المُشار إليه ولا إزالته بقواعد الاحتفاظ إلى أن تزول كل المراجع. والمرجع يخص المستدعي؛ وإضافة المفتاح نفسه مرة أخرى لا تغيّر شيئًا.

المعلمات

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

يسرد المُخرَجات المنشورة في المستودع مرتبةً حسب المعرّف، بمعدل 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 · إعادة المحاولة: آمن للتكرار (قراءة)

يعيد مُخرَجًا منشورًا: معرّفه ومستودعه وحالته ووقت إنشائه والواصف المُعطى عند الرفع (الاسم والحجم و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 يجوز أن يحمل الطلب رابط تنزيل من createDownloadLink بوصفه token؛ وتنتظر التنزيلات خانة شاغرة في قبول التنزيلات بالخادم.

المعلمات

الاسم	الموضع	النوع	مطلوب	القواعد
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). يصل المتن إلى الموقع كما هو؛ يتحقق الموقع من المراجعة أو معرّف الطلب، فلا يُطبَّق التغيير المكرر مرتين. تُرفض المسارات الأخرى بالرمز 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 · إعادة المحاولة: آمن للتكرار (قراءة)

يعيد، بترتيب التثبيت (commit)، ما يصل إلى limit تغييرًا (من 1 إلى 100، والافتراضي 100) بعد التسلسل after (الافتراضي 0): الإجراء والمُخرَج، وبالنسبة لمسارات الملفات والمراحل المسار أو المرحلة في detail؛ ولا يتضمن الفاعلين، لذا يكفي إذن عرض القوائم. head هو أحدث تسلسل في المستودع، وnext مؤشر الصفحة التالية أو null إذا بلغت الصفحة head. وتخزّن المرآة آخر تسلسل طبّقته وتستطلع (poll) بدءًا منه.

المعلمات

الاسم	الموضع	النوع	مطلوب	القواعد
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 (origin) و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 '{}'