الملفات حسب المسار
ملفات يُشار إليها بمسار في المستودع: المراجعات، والمحفوظات، والاستعادة، والملفات الخام في طلب واحد.
عمليات هذه المجموعة مع قاعدة الوصول وقاعدة إعادة المحاولة والمعلمات والاستجابات. يحمل كل طلب مفتاحًا: Authorization: Bearer <key> (راجع «المصادقة»).
العمليات
عرض قائمة مسارات الملفات حسب البادئة
GET HEAD /api/v1/repositories/{repository}/assets
الوصول: إذن المستودع: asset.read; مفاتيح الملفات: read · إعادة المحاولة: آمن للتكرار (قراءة)
يعيد كل مسار ملف يبدأ بـ prefix (حرفيًا لا بوصفه نمطًا؛ وتعني القيمة الفارغة كل المسارات)، مرتبةً حسب المسار، لكل منها مراجعته الحالية ومعرّف المُخرَج. لا يوجد ترقيم للصفحات: أكثر من 1000 تطابق يعني الخطأ 400 الذي يطلب بادئة أضيق، لذا فضّل listAssetPage للأشجار الكبيرة.
المعلمات
| الاسم | الموضع | النوع | مطلوب | القواعد |
|---|---|---|---|---|
repository | المسار | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_-]{0,63}$ |
prefix | الاستعلام | string | لا | — |
الاستجابة 200
| الحقل | النوع | مطلوب | القواعد |
|---|---|---|---|
items | مصفوفة من object | لا | — |
items[].path | string | نعم | — |
items[].revision | integer | نعم | 1–2147483647 |
items[].artifactId | string (uuid) | نعم | — |
الاستجابات: 200, 400, 401, 403, 404, 409, 422, 503, 507
مثال
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/assets" \
-H "Authorization: Bearer $ARKVORY_TOKEN"عرض قائمة مسارات الملفات صفحةً صفحة
GET HEAD /api/v1/repositories/{repository}/assets/page
الوصول: إذن المستودع: asset.read; مفاتيح الملفات: read · إعادة المحاولة: آمن للتكرار (قراءة)
يعيد مسارات الملفات الحالية التي تبدأ بـ prefix (حرفيًا؛ وتعني القيمة الفارغة كل المسارات) بترتيب بايتات UTF-8، لكل منها مراجعته الحالية ومعرّف المُخرَج. تحتوي الصفحة على limit عنصرًا (من 1 إلى 100، والافتراضي 50)؛ وللمتابعة اضبط after على قيمة next غير الشفافة (opaque). الصفحات ليست لقطة ثابتة: قد تظهر المسارات التي تغيّرت بين الطلبات بمراجعتها الأحدث، أو تفوتك حتى المرور التالي.
المعلمات
| الاسم | الموضع | النوع | مطلوب | القواعد |
|---|---|---|---|---|
repository | المسار | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_-]{0,63}$ |
prefix | الاستعلام | string | لا | عدد الأحرف: 1024 كحد أقصى; القيمة الافتراضية ``; Case-sensitive literal prefix; % and _ are ordinary characters. |
after | الاستعلام | string | لا | يطابق النمط ^[A-Za-z0-9_-]+$; عدد الأحرف: 1–8192 |
limit | الاستعلام | integer | لا | 1–100; القيمة الافتراضية 50 |
الاستجابة 200
| الحقل | النوع | مطلوب | القواعد |
|---|---|---|---|
items | مصفوفة من object | نعم | عدد العناصر: 100 كحد أقصى |
items[].path | string | نعم | — |
items[].revision | integer | نعم | 1–2147483647 |
items[].artifactId | string (uuid) | نعم | — |
next | string | نعم | يطابق النمط ^[A-Za-z0-9_-]+$; عدد الأحرف: 1–8192; يمكن أن يكون null; مؤشر غير شفاف (opaque) مرتبط بالمستودع والبادئة؛ null عند النهاية. ولا يمنح وصولًا أبدًا. |
الاستجابات: 200, 400, 401, 403, 404, 409, 422, 503, 507
مثال
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/assets/page" \
-H "Authorization: Bearer $ARKVORY_TOKEN"الحصول على المراجعة الحالية لمسار ملف
GET HEAD /api/v1/repositories/{repository}/asset
الوصول: إذن المستودع: asset.read; مفاتيح الملفات: read · إعادة المحاولة: آمن للتكرار (قراءة)
يعيد revision الحالية للمسار path ومعرّف المُخرَج الذي يشير إليه؛ والمسار غير المعروف هو 404. يتكوّن المسار من 1 إلى 1024 حرفًا في مقاطع تفصل بينها /، دون مقاطع فارغة أو . أو ..، ودون \ أو : أو محارف تحكم. نزّل البايتات بـ downloadAssetContent، أو مرّر المراجعة إلى setAsset بوصفها expectedRevision.
المعلمات
| الاسم | الموضع | النوع | مطلوب | القواعد |
|---|---|---|---|---|
repository | المسار | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_-]{0,63}$ |
path | الاستعلام | string | نعم | — |
الاستجابة 200
| الحقل | النوع | مطلوب | القواعد |
|---|---|---|---|
path | string | نعم | — |
revision | integer | نعم | 1–2147483647 |
artifactId | string (uuid) | نعم | — |
الاستجابات: 200, 400, 401, 403, 404, 409, 422, 503, 507
مثال
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset?path=$PATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN"ربط مسار ملف بمُخرَج
PUT /api/v1/repositories/{repository}/asset
الوصول: إذن المستودع: asset.write, artifact.read; مفاتيح الملفات: read, write · إعادة المحاولة: لا تكرّره إلا مع المراجعة المتوقعة (compare-and-swap)
يجعل path يسمّي مُخرَجًا منشورًا في المستودع نفسه بوصفه مراجعته الجديدة؛ وتكون expectedRevision هي 0 لإنشاء المسار، وهي المراجعة الحالية لاستبداله، وإلا كانت النتيجة 409 revision_mismatch. تبقى المراجعات السابقة في المحفوظات وتحمي مُخرَجاتها من الحذف. ولتخزين البايتات وتسميتها في طلب واحد استخدم putRawFile.
المعلمات
| الاسم | الموضع | النوع | مطلوب | القواعد |
|---|---|---|---|---|
repository | المسار | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_-]{0,63}$ |
نص الطلب (application/json)
| الحقل | النوع | مطلوب | القواعد |
|---|---|---|---|
path | string | نعم | — |
artifactId | string (uuid) | نعم | — |
expectedRevision | integer | نعم | 0–2147483646 |
الاستجابة 200
| الحقل | النوع | مطلوب | القواعد |
|---|---|---|---|
path | string | نعم | — |
revision | integer | نعم | 1–2147483647 |
artifactId | string (uuid) | نعم | — |
الاستجابات: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
مثال
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"path":"<path>","artifactId":"00000000-0000-4000-8000-000000000000","expectedRevision":0}'عرض قائمة مراجعات مسار ملف
GET HEAD /api/v1/repositories/{repository}/asset/history
الوصول: إذن المستودع: asset.read; مفاتيح الملفات: read · إعادة المحاولة: آمن للتكرار (قراءة)
يعيد مراجعات path بدءًا من الأحدث، 50 في الصفحة، لكل منها مُخرَجها والفاعل والوقت، وبالنسبة للاستعادة sourceRevision التي نُسخت (يكون الفاعل والوقت null في المراجعات المسجّلة بإصدارات الخادم المبكرة). تابع بضبط before على قيمة next. والمسار غير المعروف هو 404.
المعلمات
| الاسم | الموضع | النوع | مطلوب | القواعد |
|---|---|---|---|---|
repository | المسار | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_-]{0,63}$ |
path | الاستعلام | string | نعم | — |
before | الاستعلام | integer | لا | 1–2147483647; Only revisions strictly smaller than this value |
الاستجابة 200
| الحقل | النوع | مطلوب | القواعد |
|---|---|---|---|
items | مصفوفة من object | نعم | عدد العناصر: 50 كحد أقصى |
items[].path | string | نعم | — |
items[].revision | integer | نعم | 1–2147483647 |
items[].artifactId | string (uuid) | نعم | — |
items[].actor | string | نعم | يمكن أن يكون null; null للمحفوظات المسجّلة قبل الترحيل 4 |
items[].createdAt | string (date-time) | نعم | يمكن أن يكون null; null للمحفوظات المسجّلة قبل الترحيل 4 |
items[].sourceRevision | integer | نعم | 1–2147483647; يمكن أن يكون null; المراجعة المستعادة؛ null للاستبدال العادي |
next | integer | نعم | 1–2147483647; يمكن أن يكون null; مؤشر حصري لما قبله؛ null عند النهاية |
الاستجابات: 200, 400, 401, 403, 404, 409, 422, 503, 507
مثال
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/history?path=$PATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN"الحصول على مراجعة واحدة لمسار ملف
GET HEAD /api/v1/repositories/{repository}/asset/revision
الوصول: إذن المستودع: asset.read; مفاتيح الملفات: read · إعادة المحاولة: آمن للتكرار (قراءة)
يعيد المراجعة revision للمسار path مع معرّف مُخرَجها والفاعل والوقت ومصدر الاستعادة. المراجعات لا تتغير أبدًا، لذا يمكن تخزين معرّف المُخرَج مؤقتًا؛ ونزّله بـ downloadArtifact. والمسار أو المراجعة غير الموجودة يعطي 404.
المعلمات
| الاسم | الموضع | النوع | مطلوب | القواعد |
|---|---|---|---|---|
repository | المسار | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_-]{0,63}$ |
path | الاستعلام | string | نعم | — |
revision | الاستعلام | integer | نعم | 1–2147483647 |
الاستجابة 200
| الحقل | النوع | مطلوب | القواعد |
|---|---|---|---|
path | string | نعم | — |
revision | integer | نعم | 1–2147483647 |
artifactId | string (uuid) | نعم | — |
actor | string | نعم | يمكن أن يكون null; null للمحفوظات المسجّلة قبل الترحيل 4 |
createdAt | string (date-time) | نعم | يمكن أن يكون null; null للمحفوظات المسجّلة قبل الترحيل 4 |
sourceRevision | integer | نعم | 1–2147483647; يمكن أن يكون null; المراجعة المستعادة؛ null للاستبدال العادي |
الاستجابات: 200, 400, 401, 403, 404, 409, 422, 503, 507
مثال
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/revision?path=$PATH&revision=$REVISION" \
-H "Authorization: Bearer $ARKVORY_TOKEN"استعادة مراجعة سابقة لمسار ملف
POST /api/v1/repositories/{repository}/asset/restore
الوصول: إذن المستودع: asset.restore, asset.read, artifact.read; مفاتيح الملفات: read, write · إعادة المحاولة: لا تكرّره إلا مع المراجعة المتوقعة (compare-and-swap)
يضيف مراجعة جديدة للمسار path تشير إلى مُخرَج sourceRevision؛ ولا يُنسخ شيء ولا تُزال أي مراجعة. يجب أن تكون expectedRevision هي المراجعة الحالية (1 على الأقل)، وإلا كانت النتيجة 409 revision_mismatch، ولذلك فإن تكرار استعادة نجحت سابقًا يعطي 409 لا استعادة ثانية. تسجّل المراجعة الجديدة sourceRevision، ويُدقَّق التغيير في المعاملة نفسها.
المعلمات
| الاسم | الموضع | النوع | مطلوب | القواعد |
|---|---|---|---|---|
repository | المسار | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_-]{0,63}$ |
نص الطلب (application/json)
| الحقل | النوع | مطلوب | القواعد |
|---|---|---|---|
path | string | نعم | — |
sourceRevision | integer | نعم | 1–2147483647 |
expectedRevision | integer | نعم | 1–2147483646 |
الاستجابة 200
| الحقل | النوع | مطلوب | القواعد |
|---|---|---|---|
path | string | نعم | — |
revision | integer | نعم | 1–2147483647 |
artifactId | string (uuid) | نعم | — |
الاستجابات: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
مثال
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/restore" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"path":"<path>","sourceRevision":1,"expectedRevision":1}'تنزيل ملف حسب المسار
GET HEAD /api/v1/repositories/{repository}/asset/content
الوصول: إذن المستودع: content.read; مفاتيح الملفات: read · إعادة المحاولة: آمن للتكرار (قراءة)
يحدد path إلى مراجعته الحالية ويبثّ مُخرَجها كما يفعل downloadArtifact، مع Range وIf-Range وIf-None-Match وHEAD. يُحدَّد المسار في كل طلب، لذا استأنف باستخدام If-Range مضبوطًا على ETag المُعاد: فإذا تغيّر المسار بعد ذلك كان الردّ هو الملف الجديد كاملًا بدلًا من ملف مختلط. ويفعل downloadRawFile الأمر نفسه والمسار في العنوان (URL).
المعلمات
| الاسم | الموضع | النوع | مطلوب | القواعد |
|---|---|---|---|---|
repository | المسار | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_-]{0,63}$ |
Range | الترويسة | string | لا | Single bytes range; multi-range is unsupported. HEAD ignores Range. |
If-Range | الترويسة | string | لا | Exact strong ETag; a mismatch causes a full response. |
If-None-Match | الترويسة | string | لا | Matching ETag returns 304, including HEAD. |
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. |
path | الاستعلام | string | نعم | — |
الاستجابات: 200, 206, 304, 400, 401, 403, 404, 409, 416, 422, 503, 507
مثال
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/content?path=$PATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-o fileرفع ملف إلى مسار في طلب واحد
PUT /api/v1/repositories/{repository}/raw/{assetPath}
الوصول: إذن المستودع: upload.create, upload.write, upload.complete, asset.read, asset.write, artifact.read; مفاتيح الملفات: write · إعادة المحاولة: آمن للتكرار: الطلب نفسه يُحدث الأثر نفسه
يخزّن متن الطلب، من أي نوع وسائط، بوصفه المراجعة الجديدة للمسار الموجود في العنوان (URL)، للنصوص البرمجية (scripts) وأنظمة CI (curl -T)؛ والردّ 201 مع المسار والمراجعة والمُخرَج. مع X-Checksum-Sha256 وContent-Length تُبثّ البايتات مباشرة إلى التخزين وتُتحقَّق؛ ومن دونهما تُحفظ مؤقتًا في منطقة التجهيز (staging) وتُحسَب تجزئتها أولًا (422 إذا لم يطابق المتن المجموع الاختباري المعطى). البايتات نفسها كالمراجعة الحالية لا تضيف شيئًا ويكون الردّ 200 مع created: false، وIf-None-Match: * ينشئ فقط (409 already_exists)، وكاتب متزامن لنفس المسار يحصل على 409 revision_mismatch. وللملفات الكبيرة جدًا فضّل جلسات الرفع القابلة للاستئناف.
المعلمات
| الاسم | الموضع | النوع | مطلوب | القواعد |
|---|---|---|---|---|
repository | المسار | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_-]{0,63}$ |
assetPath | المسار | string | نعم | عدد الأحرف: 1–1024; File path; may contain slashes (folders). No empty, "." or ".." segments, backslash or colon. |
X-Checksum-Sha256 | الترويسة | string | لا | يطابق النمط ^[a-fA-F0-9]{64}$; SHA-256 of the body (64 hex digits); a mismatch stores nothing (422). |
If-None-Match | الترويسة | string | لا | إحدى القيم: *; "*": store only when the path does not exist yet (409 already_exists). |
نص الطلب (application/octet-stream)
الاستجابة 200
| الحقل | النوع | مطلوب | القواعد |
|---|---|---|---|
path | string | نعم | — |
revision | integer | نعم | 1 على الأقل |
created | boolean | نعم | — |
artifact | object | نعم | — |
artifact.id | string (uuid) | نعم | — |
artifact.size | string | نعم | عدد صحيح بأرقام عشرية، يُرسَل كسلسلة نصية |
artifact.sha256 | string | نعم | SHA-256: 64 رقمًا ست عشريًا بأحرف صغيرة |
الاستجابات: 200, 201, 400, 401, 403, 404, 405, 409, 422, 503, 507
مثال
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/raw/$ASSETPATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/octet-stream" \
--data-binary @fileتنزيل ملف عبر مسار العنوان
GET HEAD /api/v1/repositories/{repository}/raw/{assetPath}
الوصول: إذن المستودع: content.read; مفاتيح الملفات: read · إعادة المحاولة: آمن للتكرار (قراءة)
يبثّ المراجعة الحالية للمسار الموجود في العنوان (URL) كما يفعل downloadArtifact، مع Range وIf-Range وIf-None-Match وHEAD، ويسمّي X-Arkvory-Artifact-Id المُخرَج. يُحدَّد المسار في كل طلب، لذا استأنف باستخدام If-Range مضبوطًا على ETag المُعاد، أو نزّل المُخرَج بمعرّفه.
المعلمات
| الاسم | الموضع | النوع | مطلوب | القواعد |
|---|---|---|---|---|
repository | المسار | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_-]{0,63}$ |
assetPath | المسار | string | نعم | عدد الأحرف: 1–1024; File path; may contain slashes (folders). No empty, "." or ".." segments, backslash or colon. |
Range | الترويسة | string | لا | Single bytes range; multi-range is unsupported. HEAD ignores Range. |
If-Range | الترويسة | string | لا | Exact strong ETag; a mismatch causes a full response. |
If-None-Match | الترويسة | string | لا | Matching ETag returns 304, including HEAD. |
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. |
الاستجابات: 200, 206, 304, 400, 401, 403, 404, 409, 416, 422, 503, 507
مثال
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/raw/$ASSETPATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-o file